@jhustle44 / jcr-guide-pro
Code Commits Issues Pulls Cloud Agent CI/CD
main
copilot/add-firebase copilot/change-app-name-to-jcrguru copilot/create-zip-file copilot/create-zip-file-again copilot/merge-any-updates main master
jinja2 166 lines 10.6 KB
Raw
1 # Port the imported Bolt app
2
3 ## Goal
4
5 The user just imported a project from bolt.new. Port it from the imported state into the Replit `pnpm_workspace` stack so it runs cleanly in this environment. **It must look and work like the original.**
6
7 This app is the user's real product. Treat it like porting someone's live app — every lost feature, broken style, or missing interaction is a regression.
8
9 ## In scope
10
11 - Restructure the imported tree into the Replit `pnpm_workspace` layout (frontend artifact + optional `api-server`).
12 - Make the app actually run via the Replit workflow (HMR + preview pane).
13 - Wire any external services the imported app uses (database, auth, storage, AI integrations) to Replit equivalents — see `.local/secondary_skills/replit-migration-guardrails/SKILL.md`.
14
15 ## Out of scope
16
17 - Building new features or refactoring beyond what's needed to run.
18 - Strict typecheck — use `// @ts-ignore` to keep moving. Visual + functional parity matters more than zero TS errors.
19 - Fixing bugs that existed before the import.
20
21 ## Bolt-specific notes
22
23 Bolt projects vary widely. Detect the shape first instead of assuming.
24
25 - **`.bolt/`, `bolt.config.*`, `stackblitz.json`** — StackBlitz-only metadata. Safe to ignore; nothing inside affects runtime on Replit.
26 - **Most Bolt apps are Vite + React** (sometimes SvelteKit / Astro / Next.js — check `package.json` + config files).
27 - Vite + React → follow the steps below; this is the default path.
28 - Next.js → STOP. Next.js does not migrate cleanly to `pnpm_workspace`. Inform the user that auto-migration is skipped for Next.js Bolt projects and run the project as-is via expert mode.
29 - Other frameworks → Inform the user the framework isn't auto-supported; run as-is.
30 - **Backend shape** — Bolt apps usually ship as frontend-only (API calls go to third-party services). If there's no `server/` directory and no Express/Fastify/Hono entry, treat as **frontend-only** and skip the backend copy step (step 3 below).
31 - **Bolt env handling** — Bolt uses Vite-style `import.meta.env.VITE_*`. Keep that convention. Replit secrets surfaced as `VITE_*` env vars are read the same way.
32
33 ## Pre-existing scaffold (do NOT remove)
34
35 The pnpm_workspace scaffold is already applied. These existed before this task started:
36
37 - `artifacts/api-server/` — backend artifact (kind=api).
38 - `artifacts/mockup-sandbox/` — design/mockup artifact.
39 - `lib/api-spec/`, `lib/api-client-react/`, `lib/db/` — shared packages.
40
41 The existing app's frontend goes into a NEW web artifact created via `createArtifact`. Do NOT put frontend code into `artifacts/api-server/`.
42
43 ## How to communicate
44
45 Short, non-technical updates: "Looking at your project..." → "Setting things up..." → "Moving your app..." → "Checking everything works..."
46
47 ## Steps
48
49 ### 0. Read the pnpm_workspace skill
50
51 Read `.local/skills/pnpm-workspace/SKILL.md` first. It contains the canonical patterns for project references, artifact routing, package management, and common pitfalls.
52
53 ### 1. Detect + install
54
55 ```sh
56 bash .local/secondary_skills/migrate-to-multi-artifact/references/fullstack_detect.sh
57 pnpm install
58 ```
59
60 Read the detect output. Note:
61
62 - `CLIENT_DIR` (typically `.` or `src/` for Bolt — flat Vite layout).
63 - `SCHEMA_PATH` and `ROUTE_LAYOUT` — only relevant if a backend exists.
64 - `CONFLICTS` — fix these before continuing.
65
66 ### 2. Read what you need
67
68 If a backend exists, read its route file(s) and schema file from `.migration-backup/` (you need their content for the OpenAPI spec).
69
70 For frontend-only Bolt apps, read just `package.json` from `.migration-backup/` to capture deps and scripts. Do NOT read the rest — the copy script handles it.
71
72 ### 3. Copy backend (skip for frontend-only apps)
73
74 If the imported app has a real backend:
75
76 ```sh
77 bash .local/secondary_skills/migrate-to-multi-artifact/references/fullstack_copy_backend.sh
78 ```
79
80 Then write `lib/api-spec/openapi.yaml` based on the routes/schema you read in step 2 (only if practical — small/medium apps). For large legacy backends, skip the spec and keep the existing fetch layer in the frontend.
81
82 Run codegen + DB push in parallel:
83
84 - `pnpm --filter @workspace/api-spec run codegen`
85 - `pnpm --filter @workspace/db run push`
86
87 Read `lib/api-client-react/src/generated/api.ts` for exact hook names you'll need in step 5.
88
89 **Frontend-only Bolt apps**: skip this whole step. The backend copy script will fail (no `server/`) — don't run it.
90
91 ### 4. Copy frontend
92
93 ```sh
94 createArtifact({ artifactType: "react-vite", slug: "<app-name>", previewPath: "/", title: "<Title>" })
95 ```
96
97 Then run the copy script — do NOT skip this or manually rewrite files instead:
98
99 ```sh
100 bash .local/secondary_skills/migrate-to-multi-artifact/references/fullstack_copy_frontend.sh <app-name>
101 ```
102
103 The script copies source files from `.migration-backup/` into the new artifact, patches imports, installs dependencies, and handles both flat and nested layouts. Manually rewriting files loses styles, fonts, and subtle markup that the script preserves.
104
105 Read the script output and act on it:
106
107 - `AGENT TODO` — required edits (vite.config.ts, wouter base path). Do these.
108 - `SKIPPED` — files intentionally not copied (conflicts). Check if they matter.
109 - `PATCHED` — automatic fixes applied (fonts, imports). No action needed.
110 - `INSTALLED` — dependencies added. No action needed.
111
112 ### 5. Fix frontend imports + preserve app identity
113
114 If you wrote an OpenAPI spec, replace old fetch calls with generated hooks from `@workspace/api-client-react`. Otherwise keep the existing fetch layer — just fix paths so they resolve.
115
116 Verify these are preserved (the copy script handles most, but check):
117
118 - **Fonts** — `index.html` Google Fonts `<link>` tags + CSS `--font-sans` variables.
119 - **Colors / theme** — if `theme.json` existed, verify it was copied and the vite plugin was wired.
120 - **Routing** — if using wouter, the `<Router>` must have `base={import.meta.env.BASE_URL}`.
121 - **Bolt-specific env vars** — anything `import.meta.env.VITE_*` the imported app reads needs a Replit secret with the same name. Use the environment-secrets skill to ask the user for any missing one.
122
123 If the original app calls external services directly (Supabase, Firebase, OpenAI / Anthropic / SendGrid / Twilio / Stripe / etc.), follow `.local/secondary_skills/replit-migration-guardrails/SKILL.md` to swap them for Replit equivalents. For auth (Supabase Auth, Firebase Auth, Auth0, etc.), use Clerk — see the authentication skill.
124
125 ### 6. Verify
126
127 Restart the workflow, then use the testing agent (see the testing skill) to exercise the main flows — navigation, key interactions, any auth or data features. The testing agent will screenshot each step and report failures.
128
129 **Replit apps run via workflows, not root-level `pnpm dev`.** Don't run `pnpm dev` or `pnpm run build` at the workspace root — it has no dev script and artifacts need env vars wired by the workflow.
130
131 **What to check**: Does it look the same? Does it work? If the testing agent reports failures, fix and re-run. If it passes, you're done.
132
133 {% if not is_free_import %}
134 ### 7. Propose follow-up tasks
135
136 Before completing, call `proposeFollowUpTasks` with the three tasks below in a single call. **The mobile task MUST be the first task in the `tasks` array and MUST be proposed on every Bolt port — this is the single most valuable thing Replit offers that Bolt cannot, and it is the reason many users are porting over.** Do not skip it, do not reorder it. Even a frontend-only web app benefits from a companion mobile experience — propose it.
137
138 Do not prescribe the exact `createArtifact` API in the task descriptions — the agent who picks up the follow-up will consult the create-artifact skill for the correct `artifactType` and other parameters. Just describe the artifact to build.
139
140 1. **"Take your app mobile"** (category: `next_steps`) — **ALWAYS FIRST. ALWAYS INCLUDED.** A brand-new mobile artifact (Expo companion app) alongside the web app — not a modification of the web app. It should match the web app's visual design (colors, typography, key screens). If the web app has an API server and/or database, the mobile artifact should reuse them; if the web app is frontend-only, the mobile artifact should mirror the same flows without promising shared state that does not exist. Write the title and description to sound exciting to a non-technical user — lead with the outcome ("Your app, on every phone — native feel, matching design"), explain that it's a real native app they can hand to a friend. This is the charm moment for a Bolt user: they shipped a web app, and now Replit gives them a mobile app too.
141 2. **"Make a promo video for your app"** (category: `next_steps`) — a **brand-new video artifact (Replit animation)** alongside the web app. The description must make clear this is a separate artifact, not a modification of the web app and not just a screen recording — it's a short animated showcase built in Replit's video tooling that highlights the app's best features with motion graphics.
142 3. **"Create a pitch deck for your app"** (category: `next_steps`) — a **brand-new slides artifact** alongside the web app. The description must make clear this is a separate artifact presenting the app's value proposition, core features, and key user flows for demos and stakeholders.
143
144 {% endif %}
145 ### 8. Complete
146
147 Call `mark_task_complete` with `skip_validation_reason` set. Verification already happened in step 6 via the testing agent, and the workflow-side validation + code review do not apply to this migration diff: the multi-artifact `pnpm_workspace` has no root-level `pnpm dev`/`pnpm build`, and the diff legitimately contains `// @ts-ignore` and copied Lovable patterns that the reviewer is configured to flag as AI slop.
148
149 Pass exactly:
150
151 ```
152 skip_validation_reason: "Multi-artifact migration verified via the testing agent in step 6; root-level validation and code review do not apply to this stack-migration diff."
153 ```
154
155 The user will verify visual + functional parity before doing anything else.
156
157 ## Note to the code reviewer
158
159 When reviewing the diff for this task:
160
161 - HONOR the `Out of scope` section above. Don't reject for items the plan explicitly marks out of scope (`any` types, typecheck errors).
162 - Do NOT reject for pre-existing issues — type errors / `any` types / legacy patterns in code copied from the imported tree are not regressions.
163 - Do NOT flag the pre-existing scaffold packages (`artifacts/api-server/`, `lib/*`) as agent additions.
164 - Do NOT reject for `pnpm dev` failing at workspace root — Replit apps run via workflows.
165 - Do NOT flag scaffold files (`src/components/ui/*.tsx` shadcn, default `favicon.svg`).
166 - Apply only the criteria from this task's `## Goal` + `## In scope`. Reject only for real regressions (broken runtime, missing files, lost features).