@jhustle44 / jcr-guide-pro
Code Commits Issues Pulls Cloud Agent CI/CD
copilot/create-zip-file-again
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 179 lines 11.1 KB
Raw
1 # Port the imported Vercel / v0 app
2
3 ## Goal
4
5 The user just imported a project from Vercel or v0. 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 The imported project is almost always Next.js. You must convert it to a Vite + React app (`react-vite` artifact). Next.js is not supported as an artifact type.
8
9 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.
10
11 ## In scope
12
13 - Convert the Next.js app to Vite + React and restructure into the Replit `pnpm_workspace` layout (frontend artifact + optional `api-server` for API routes).
14 - Replace Next.js-specific patterns (file-based routing, API routes, `next/image`, `next/link`, SSR) with Vite + React equivalents.
15 - Make the app actually run via the Replit workflow.
16
17 ## Out of scope
18
19 - Building new features or refactoring beyond what's needed to run.
20 - Strict typecheck — use `// @ts-ignore` to keep moving. Visual + functional parity matters more than zero TS errors.
21 - Fixing bugs that existed before the import.
22
23 ## Vercel-specific notes
24
25 Vercel/v0 projects are almost always Next.js. The key job is converting to Vite + React:
26
27 - **Next.js routing → React Router / wouter** — `app/page.tsx` and `pages/*.tsx` become route components. Use wouter (already in the scaffold) or react-router.
28 - **`next/image` → `<img>`** — replace `Image` from `next/image` with standard `<img>` tags. Copy `width`/`height`/`alt` props.
29 - **`next/link` → `<a>` or wouter `<Link>`** — replace Next.js `Link` with standard links or wouter `Link`.
30 - **API routes → Express** — `app/api/` or `pages/api/` routes become Express routes in `artifacts/api-server/`. Simple endpoints can be inlined; heavy backends (DB, auth) go through `lib/db/`.
31 - **SSR / `getServerSideProps` / `getStaticProps`** — convert to client-side data fetching (`useEffect` + `fetch` or react-query). The Vite app is fully client-rendered.
32 - **`next.config.mjs`** — not used in Vite. Migrate relevant settings (env vars, redirects) to `vite.config.ts` or Express middleware.
33 - **Monorepo structure** — some Vercel projects use `apps/web`, `packages/frontend`. Locate the Next.js app first.
34 - **Binary asset spot-check** — v0 exports can ship images/fonts as base64 text. Run `file public/**/*.{png,jpg,webp,woff,woff2,ttf}` — any binary reported as text needs `base64 -d`.
35 - **Env vars** — anything via `process.env.*` or `NEXT_PUBLIC_*` needs a Replit secret. `NEXT_PUBLIC_` vars become `VITE_` vars in the Vite app.
36
37 ## Pre-existing scaffold (do NOT remove)
38
39 The pnpm_workspace scaffold is already applied. These existed before this task started:
40
41 - `artifacts/api-server/` — backend artifact (kind=api).
42 - `artifacts/mockup-sandbox/` — design/mockup artifact.
43 - `lib/api-spec/`, `lib/api-client-react/`, `lib/db/` — shared packages.
44
45 The existing app's frontend goes into a NEW web artifact created via `createArtifact`. Do NOT put frontend code into `artifacts/api-server/`.
46
47 ## How to communicate
48
49 Short, non-technical updates: "Looking at your project..." → "Setting things up..." → "Converting to Vite..." → "Wiring up routes..." → "Checking everything works..."
50
51 ## Steps
52
53 ### 0. Read the pnpm_workspace skill
54
55 Read `.local/skills/pnpm-workspace/SKILL.md` first. It contains the canonical patterns for project references, artifact routing, package management, and common pitfalls.
56
57 ### 1. Detect + install
58
59 ```sh
60 bash .local/secondary_skills/migrate-to-multi-artifact/references/fullstack_detect.sh
61 pnpm install
62 ```
63
64 Read the detect output. For Vercel, expect Next.js. Note:
65
66 - `CLIENT_DIR` — root or a subdirectory if it's a monorepo.
67 - `CONFLICTS` — fix these before continuing.
68 - Check if it's a monorepo (multiple `package.json` files, `apps/` directory).
69
70 ### 2. Read what you need
71
72 Read just enough from `.migration-backup/` to understand the app:
73
74 - `package.json` (deps, scripts).
75 - `next.config.mjs` or `next.config.js` (redirects, env vars, image domains).
76 - `app/` or `pages/` directory listing to understand the routing structure.
77 - Any `app/api/` or `pages/api/` routes — these need extraction to Express.
78 - `.env` or `.env.local` filenames (not contents) to know which secrets are needed.
79
80 Do NOT read every component — focus on routing structure and API surface.
81
82 ### 3. Build backend (only if the app has API routes)
83
84 If the app has `app/api/` or `pages/api/` routes:
85
86 ```sh
87 createArtifact({ artifactType: "api", slug: "api-server", ... }) // skip if api-server already exists
88 ```
89
90 Convert Next.js API routes to Express routes in `artifacts/api-server/`. Set up `lib/db/` (Drizzle + Postgres) if the app uses a database.
91
92 Run codegen + DB push in parallel once the spec exists:
93
94 - `pnpm --filter @workspace/api-spec run codegen`
95 - `pnpm --filter @workspace/db run push`
96
97 If it's purely frontend with no API routes, skip this step.
98
99 ### 4. Copy frontend
100
101 ```sh
102 createArtifact({ artifactType: "react-vite", slug: "<app-name>", previewPath: "/", title: "<Title>" })
103 ```
104
105 Then run the copy script — do NOT skip this or manually rewrite files instead:
106
107 ```sh
108 bash .local/secondary_skills/migrate-to-multi-artifact/references/fullstack_copy_frontend.sh <app-name>
109 ```
110
111 The script copies source files from `.migration-backup/` into the new artifact, patches imports, installs dependencies, and handles both flat and monorepo layouts. Manually rewriting files loses styles, fonts, and subtle markup that the script preserves.
112
113 Read the script output and act on it:
114
115 - `AGENT TODO` — required edits. Do these.
116 - `SKIPPED` — files intentionally not copied (conflicts). Check if they matter.
117 - `PATCHED` — automatic fixes applied. No action needed.
118 - `INSTALLED` — dependencies added. No action needed.
119
120 ### 5. Convert Next.js → Vite + React
121
122 This is the core transformation. Work through these in order:
123
124 - **Remove `next` dependency**, add `react-router-dom` or use wouter (already in scaffold).
125 - **Convert routing** — `app/page.tsx` → route components. Create a `src/App.tsx` with a router that maps the old Next.js paths.
126 - **Replace `next/image`** with `<img>` tags.
127 - **Replace `next/link`** with `<a>` or wouter `<Link>`.
128 - **Convert data fetching** — `getServerSideProps` / `getStaticProps` / server components → `useEffect` + `fetch` or react-query hooks calling the api-server.
129 - **Rename `NEXT_PUBLIC_*` env vars** to `VITE_*` and update references from `process.env.NEXT_PUBLIC_*` to `import.meta.env.VITE_*`.
130 - **Env vars** — use the environment-secrets skill to request any missing values.
131
132 Verify these are preserved:
133
134 - **Fonts** — Google Fonts `<link>` tags + CSS `--font-sans` variables.
135 - **Colors / theme** — Tailwind CSS variables in `:root` and `.dark`.
136 - **Routing** — all original paths should be reachable in the Vite app.
137
138 ### 6. Verify
139
140 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.
141
142 **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.
143
144 **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.
145
146 {% if not is_free_import %}
147 ### 7. Propose follow-up tasks
148
149 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 Vercel port — this is the single most valuable thing Replit offers that Vercel 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.
150
151 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.
152
153 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 Vercel user: they shipped a web app, and now Replit gives them a mobile app too.
154 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.
155 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.
156
157 {% endif %}
158 ### 8. Complete
159
160 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.
161
162 Pass exactly:
163
164 ```
165 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."
166 ```
167
168 The user will verify visual + functional parity before doing anything else.
169
170 ## Note to the code reviewer
171
172 When reviewing the diff for this task:
173
174 - HONOR the `Out of scope` section above. Don't reject for items the plan explicitly marks out of scope (`any` types, typecheck errors).
175 - Do NOT reject for pre-existing issues — type errors / `any` types / legacy patterns in code copied from the imported tree are not regressions.
176 - Do NOT flag the pre-existing scaffold packages (`artifacts/api-server/`, `lib/*`) as agent additions.
177 - Do NOT reject for `pnpm dev` failing at workspace root — Replit apps run via workflows.
178 - Do NOT flag scaffold files (`src/components/ui/*.tsx` shadcn, default `favicon.svg`).
179 - Apply only the criteria from this task's `## Goal` + `## In scope`. Reject only for real regressions (broken runtime, missing files, lost features).