|
1
|
# Port the imported Base44 app |
|
2
|
|
|
3
|
## Goal |
|
4
|
|
|
5
|
The user just imported a project from base44.com. 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 + an `api-server` backed by Replit Postgres + Clerk for auth). |
|
12
|
- Replace Base44's SDK shims (`base44.entities.*`, `base44.auth.*`, `base44.integrations.*`) with Replit primitives — see `## Base44-specific notes`. |
|
13
|
- Make the app actually run via the Replit workflow. |
|
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
|
## Base44-specific notes |
|
22
|
|
|
23
|
Base44 apps follow a very consistent shape — assume this layout: |
|
24
|
|
|
25
|
- **Vite + React, JSX (not TSX)** with a flat `src/` at the repo root. |
|
26
|
- **No `server/` directory in the original** — Base44 talks to a hosted SDK, not a backend the user owns. |
|
27
|
- **SDK shim files** live at: |
|
28
|
- `src/api/base44Client.js`, `src/api/entities.js`, `src/api/integrations.js` |
|
29
|
- `src/lib/app-params.js`, `src/lib/AuthContext.jsx` |
|
30
|
- `src/components/ProtectedRoute.jsx`, `src/components/UserNotRegisteredError.jsx` |
|
31
|
- **`@base44/sdk` and `@base44/vite-plugin`** in `package.json` — remove both as part of the migration. |
|
32
|
- **Vite config** wires the Base44 plugin — remove that wiring. |
|
33
|
|
|
34
|
### Replacement map |
|
35
|
|
|
36
|
| Base44 | Replit replacement | |
|
37
|
| --- | --- | |
|
38
|
| `base44.entities.*` | New `api-server` artifact + `lib/db/` (Drizzle + Postgres) + `/api/*` routes | |
|
39
|
| `base44.auth.*` | Clerk (see the authentication skill) | |
|
40
|
| `InvokeLLM` / `GenerateImage` / `ExtractDataFromUploadedFile` | AI integrations (OpenAI / Anthropic) — see migration-guardrails skill | |
|
41
|
| `UploadFile` | Object storage integration (`javascript_object_storage`) | |
|
42
|
| `SendEmail` / `SendSMS` | Integrations skill, else stub | |
|
43
|
| `base44.appLogs.*` | Delete (no equivalent needed) | |
|
44
|
|
|
45
|
### Files to delete after the swap |
|
46
|
|
|
47
|
`base44Client.js`, `entities.js`, `integrations.js`, `app-params.js`, `NavigationTracker.jsx`, `VisualEditAgent.jsx`, `UserNotRegisteredError.jsx`. Keep `AuthContext.jsx` only after rewriting it to wrap Clerk. |
|
48
|
|
|
49
|
## Pre-existing scaffold (do NOT remove) |
|
50
|
|
|
51
|
The pnpm_workspace scaffold is already applied. These existed before this task started: |
|
52
|
|
|
53
|
- `artifacts/api-server/` — backend artifact (kind=api). |
|
54
|
- `artifacts/mockup-sandbox/` — design/mockup artifact. |
|
55
|
- `lib/api-spec/`, `lib/api-client-react/`, `lib/db/` — shared packages. |
|
56
|
|
|
57
|
The existing app's frontend goes into a NEW web artifact created via `createArtifact`. Do NOT put frontend code into `artifacts/api-server/`. |
|
58
|
|
|
59
|
## How to communicate |
|
60
|
|
|
61
|
Short, non-technical updates: "Looking at your project..." → "Setting things up..." → "Moving your app..." → "Wiring up the database..." → "Checking everything works..." |
|
62
|
|
|
63
|
## Steps |
|
64
|
|
|
65
|
### 0. Read the pnpm_workspace skill |
|
66
|
|
|
67
|
Read `.local/skills/pnpm-workspace/SKILL.md` first. |
|
68
|
|
|
69
|
### 1. Detect + install |
|
70
|
|
|
71
|
```sh |
|
72
|
bash .local/secondary_skills/migrate-to-multi-artifact/references/fullstack_detect.sh |
|
73
|
pnpm install |
|
74
|
``` |
|
75
|
|
|
76
|
For Base44, expect `CLIENT_DIR=.` (flat) and an empty `ROUTE_LAYOUT` / `SCHEMA_PATH`. Fix any `CONFLICTS` first. |
|
77
|
|
|
78
|
### 2. Read the SDK surface |
|
79
|
|
|
80
|
Read these from `.migration-backup/`: |
|
81
|
|
|
82
|
- `src/api/base44Client.js`, `src/api/entities.js`, `src/api/integrations.js` |
|
83
|
- `src/lib/app-params.js`, `src/lib/AuthContext.jsx` |
|
84
|
- `src/components/ProtectedRoute.jsx`, `src/components/UserNotRegisteredError.jsx` |
|
85
|
- `vite.config.js` |
|
86
|
- `package.json` |
|
87
|
|
|
88
|
Then grep for the actual surface area used: |
|
89
|
|
|
90
|
```sh |
|
91
|
grep -rE "base44\.(entities|integrations\.Core|auth)\." .migration-backup/src |
|
92
|
``` |
|
93
|
|
|
94
|
This enumeration drives the shape of the new `api-server` schema and routes. |
|
95
|
|
|
96
|
### 3. Build the backend |
|
97
|
|
|
98
|
Use `lib/db/` (Drizzle + Postgres) to define tables that match the entities you found in step 2. Use `artifacts/api-server/` to expose `/api/*` routes that match the entity calls. |
|
99
|
|
|
100
|
If the app uses `base44.auth.*`, set up Clerk — see the authentication skill. |
|
101
|
|
|
102
|
For AI integrations (`InvokeLLM`, `GenerateImage`, `ExtractDataFromUploadedFile`), use the corresponding Replit AI integration. For storage (`UploadFile`), use the object storage integration. |
|
103
|
|
|
104
|
Run codegen + DB push in parallel once the spec exists: |
|
105
|
|
|
106
|
- `pnpm --filter @workspace/api-spec run codegen` |
|
107
|
- `pnpm --filter @workspace/db run push` |
|
108
|
|
|
109
|
### 4. Copy frontend |
|
110
|
|
|
111
|
```sh |
|
112
|
createArtifact({ artifactType: "react-vite", slug: "<app-name>", previewPath: "/", title: "<Title>" }) |
|
113
|
``` |
|
114
|
|
|
115
|
Then run the copy script — do NOT skip this or manually rewrite files instead: |
|
116
|
|
|
117
|
```sh |
|
118
|
bash .local/secondary_skills/migrate-to-multi-artifact/references/fullstack_copy_frontend.sh <app-name> |
|
119
|
``` |
|
120
|
|
|
121
|
The script copies source files from `.migration-backup/` into the new artifact, patches imports, installs dependencies, and handles Base44's flat `src/` layout. Manually rewriting files loses styles, fonts, and subtle markup that the script preserves. |
|
122
|
|
|
123
|
Read the script output and act on it: |
|
124
|
|
|
125
|
- `AGENT TODO` — required edits (vite.config.ts, wouter base path). Do these. |
|
126
|
- `SKIPPED` — files intentionally not copied (conflicts). Check if they matter. |
|
127
|
- `PATCHED` — automatic fixes applied. No action needed. |
|
128
|
- `INSTALLED` — dependencies added. No action needed. |
|
129
|
|
|
130
|
### 5. Replace the SDK + clean up |
|
131
|
|
|
132
|
- **Remove `@base44/sdk` and `@base44/vite-plugin`** from `package.json`. Strip the Base44 plugin from `vite.config.*`. |
|
133
|
- **Replace `base44.entities.*` calls** with `fetch` to your new `/api/*` routes (or generated hooks if you wrote an OpenAPI spec). |
|
134
|
- **Replace `base44.auth.*`** with Clerk — see the authentication skill. |
|
135
|
- **Replace `InvokeLLM` / `GenerateImage` / `ExtractDataFromUploadedFile`** with the matching AI integration. |
|
136
|
- **Replace `UploadFile`** with the object storage integration. |
|
137
|
- **Delete** the shim files listed in the Base44-specific notes section above. |
|
138
|
|
|
139
|
Verify these are preserved (the copy script handles most, but check): |
|
140
|
|
|
141
|
- **Fonts** — `index.html` Google Fonts `<link>` tags + CSS `--font-sans` variables. |
|
142
|
- **Colors / theme** — Base44 apps usually express theme via Tailwind CSS variables in `:root` and `.dark`. |
|
143
|
- **Routing** — if using wouter, the `<Router>` must have `base={import.meta.env.BASE_URL}`. |
|
144
|
|
|
145
|
### 6. Verify |
|
146
|
|
|
147
|
Restart the workflow, then use the testing agent (see the testing skill) to exercise the main flows — navigation, auth, entity CRUD. The testing agent will screenshot each step and report failures. |
|
148
|
|
|
149
|
**Replit apps run via workflows, not root-level `pnpm dev`.** Don't run `pnpm dev` or `pnpm run build` at the workspace root. |
|
150
|
|
|
151
|
**What to check**: Does it look the same? Do the auth + entity flows work end-to-end? If the testing agent reports failures, fix and re-run. If it passes, you're done. |
|
152
|
|
|
153
|
{% if not is_free_import %} |
|
154
|
### 7. Propose follow-up tasks |
|
155
|
|
|
156
|
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 Base44 port — this is the single most valuable thing Replit offers that Base44 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. |
|
157
|
|
|
158
|
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. |
|
159
|
|
|
160
|
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 Base44 user: they shipped a web app, and now Replit gives them a mobile app too. |
|
161
|
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. |
|
162
|
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. |
|
163
|
|
|
164
|
{% endif %} |
|
165
|
### 8. Complete |
|
166
|
|
|
167
|
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. |
|
168
|
|
|
169
|
Pass exactly: |
|
170
|
|
|
171
|
``` |
|
172
|
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." |
|
173
|
``` |
|
174
|
|
|
175
|
The user will verify visual + functional parity before doing anything else. |
|
176
|
|
|
177
|
## Note to the code reviewer |
|
178
|
|
|
179
|
When reviewing the diff for this task: |
|
180
|
|
|
181
|
- HONOR the `Out of scope` section above. |
|
182
|
- Do NOT reject for pre-existing issues in code copied from `.migration-backup/`. |
|
183
|
- Do NOT flag the pre-existing scaffold packages (`artifacts/api-server/`, `lib/*`) as agent additions. |
|
184
|
- Do NOT reject for `pnpm dev` failing at workspace root. |
|
185
|
- Do NOT flag scaffold files (shadcn `src/components/ui/*.tsx`, default `favicon.svg`). |
|
186
|
- Apply only the criteria from this task's `## Goal` + `## In scope`. Reject only for real regressions. |