From fb63862043d2b7eb0c10f4835e7b3102791d9e0d Mon Sep 17 00:00:00 2001 From: David Susskind Date: Wed, 29 Jul 2026 13:46:06 +0300 Subject: [PATCH 1/4] docs(base44-cli): tell agents which local dev mode hits production data An app can run locally more than one way and the skills documented only one. `base44 dev` starts a local backend on a throwaway in-memory database; running the frontend alone with `npm run dev` serves it against the real app's live backend, and nothing said so. An agent picking that writes to the user's production data with no error to warn it. Keep the backend-only project shape first-class: the `backend-only` template ships no frontend at all, so `base44 dev` starting just the backend is the normal case there, not a fallback. Document the choice where the agent decides, and stop routing the existing-project case away from that decision: SKILL.md handed every "I have a project" scenario to base44-sdk, which is exactly the user who wants to run their app. Co-Authored-By: Claude Fable 5 --- skills/base44-cli/SKILL.md | 23 ++++++++++++++++++----- 1 file changed, 18 insertions(+), 5 deletions(-) diff --git a/skills/base44-cli/SKILL.md b/skills/base44-cli/SKILL.md index fed6809..55d04fc 100644 --- a/skills/base44-cli/SKILL.md +++ b/skills/base44-cli/SKILL.md @@ -20,6 +20,8 @@ This skill activates on ANY mention of "base44" or when a `base44/` folder exist 2. If **YES** (existing project scenario): - Transfer to base44-sdk skill for implementation - This skill only handles CLI commands (login, deploy, entities push) + - **Except running the app locally** — stays here. Read [Running Local Development](#running-local-development) + before starting a dev server: one way of running hits production data. 3. If **NO**, decide between two initialization paths: - **Provisioned app** — the Base44 app already exists because it was just provisioned through a Stripe Projects / projects.dev flow, OR `BASE44_APP_ID` (or `BASE44_PROJECTS_BASE44_APP_ID`) is present in the environment or a `.env`/`.env.local` file: - Run `npx base44 scaffold` to set up local files for that **existing** app @@ -559,12 +561,23 @@ npx base44 link --create --name my-app ``` ### Running Local Development -```bash -# Starts the Base44 backend locally -npx base44 dev -``` -If you want `base44 dev` to run your frontend too, verify `base44/config.jsonc` has `site.serveCommand` set correctly (for example, `"serveCommand": "npm run dev"`). When that field is present, `base44 dev` runs both the backend and the frontend together. +`npx base44 dev` starts the Base44 backend locally (entities, functions, auth) on a throwaway +in-memory database — empty each start, gone on stop. A backend-only project needs nothing else; it +also runs your frontend when `base44/config.jsonc` sets `site.serveCommand`, wired to that local +backend. + +Running the frontend by itself talks to a different backend: + +| Command | Backend + data | +|---------|----------------| +| `npx base44 dev` | **local** — the throwaway one above | +| `npm run dev` | **production** — the real app's live data | + +**Default to `npx base44 dev`.** Use `npm run dev` only when the user wants real data: every write +hits the live app. The browser can't tell the modes apart; the vite startup line can — +`[base44] Proxy enabled: /api -> https://base44.app (default)` means production. Say which you +started. Options: [dev.md](references/dev.md). ### Deploying All Changes ```bash From 51b6bf3bb81b0e1dcffd2e55ae85ae6fff2acca9 Mon Sep 17 00:00:00 2001 From: David Susskind Date: Wed, 29 Jul 2026 16:20:41 +0300 Subject: [PATCH 2/4] docs(base44-cli): teach the two base44 dev modes Running an app locally goes through the CLI: `base44 dev` for a local throwaway backend, `base44 dev --remote` for the app's real backend and production data. Nothing in the skills said the second mode exists, and nothing said which one touches live data. Also stop routing the existing-project case away from that decision: SKILL.md handed every "I have a project" scenario to base44-sdk, which is exactly the user who wants to run their app. Co-Authored-By: Claude Fable 5 --- skills/base44-cli/SKILL.md | 24 +++++++++++++----------- 1 file changed, 13 insertions(+), 11 deletions(-) diff --git a/skills/base44-cli/SKILL.md b/skills/base44-cli/SKILL.md index 55d04fc..7358eeb 100644 --- a/skills/base44-cli/SKILL.md +++ b/skills/base44-cli/SKILL.md @@ -562,21 +562,23 @@ npx base44 link --create --name my-app ### Running Local Development -`npx base44 dev` starts the Base44 backend locally (entities, functions, auth) on a throwaway -in-memory database — empty each start, gone on stop. A backend-only project needs nothing else; it -also runs your frontend when `base44/config.jsonc` sets `site.serveCommand`, wired to that local -backend. - -Running the frontend by itself talks to a different backend: +Always run through the CLI — two modes: | Command | Backend + data | |---------|----------------| -| `npx base44 dev` | **local** — the throwaway one above | -| `npm run dev` | **production** — the real app's live data | +| `npx base44 dev` | **local** — throwaway, empty each start, gone on stop | +| `npx base44 dev --remote` | **production** — the real app's live data | + +`base44 dev` starts the local backend (entities, functions, auth) and also serves your frontend when +`base44/config.jsonc` sets `site.serveCommand`; a backend-only project needs nothing else. +`--remote` runs *only* the frontend against the real backend, so it needs both a linked project and +`site.serveCommand`. + +Don't run `npm run dev` yourself: without the env vars the CLI injects, the app has no backend to +reach — the dev server prints which command to use instead. -**Default to `npx base44 dev`.** Use `npm run dev` only when the user wants real data: every write -hits the live app. The browser can't tell the modes apart; the vite startup line can — -`[base44] Proxy enabled: /api -> https://base44.app (default)` means production. Say which you +**Default to `npx base44 dev`.** Under `--remote` every write hits the live app. The vite startup +line names the backend either way: `[base44] Proxy enabled: /api -> `. Say which you started. Options: [dev.md](references/dev.md). ### Deploying All Changes From 045f83f356012ab391479aabac19270fb24ffad8 Mon Sep 17 00:00:00 2001 From: David Susskind Date: Thu, 30 Jul 2026 10:49:00 +0300 Subject: [PATCH 3/4] docs(base44-cli): route dev and build through the CLI Adds the two run modes (`base44 dev`, `base44 dev --remote`) and, more urgently, stops instructing the build path that is now broken: a bare `npm run build` leaves VITE_BASE44_APP_ID unset, so the deployed bundle can't resolve its own app and every API call fails. Quick Start, the deploy workflow and troubleshooting all told agents to do exactly that. Also stop routing the existing-project case away from the decision: SKILL.md handed every "I have a project" scenario to base44-sdk, which is exactly the user who wants to run or ship their app. Co-Authored-By: Claude Fable 5 --- skills/base44-cli/SKILL.md | 22 +++++++++++++--------- 1 file changed, 13 insertions(+), 9 deletions(-) diff --git a/skills/base44-cli/SKILL.md b/skills/base44-cli/SKILL.md index 7358eeb..4b279b4 100644 --- a/skills/base44-cli/SKILL.md +++ b/skills/base44-cli/SKILL.md @@ -271,12 +271,14 @@ Workspaces (a.k.a. organizations) group apps under shared membership. By default | Command | Description | Reference | |---------|-------------|-----------| | `base44 dev` | Start local development for your Base44 backend, and your frontend too when `site.serveCommand` is configured | [dev.md](references/dev.md) | +| `base44 dev --remote` | Serve the frontend locally against the **production** backend | [dev.md](references/dev.md) | ### Deployment | Command | Description | Reference | |---------|-------------|-----------| -| `base44 deploy` | Deploy all resources (entities, functions, agents, agent skills, connectors, auth config, and site) | [deploy.md](references/deploy.md) | +| `base44 build` | Build the site with its app id injected — use instead of a bare `npm run build` | — | +| `base44 deploy` | Deploy all resources (entities, functions, agents, agent skills, connectors, auth config, and site); asks whether to build first, or pass `--build` / `--no-build` | [deploy.md](references/deploy.md) | ### Entity Management @@ -525,8 +527,7 @@ Run one-off scripts against your app with the Base44 SDK pre-authenticated. Use 5. Build and deploy everything: ```bash - npm run build - npx base44 deploy -y + npx base44 deploy --build -y ``` Or deploy individual resources: @@ -586,13 +587,15 @@ started. Options: [dev.md](references/dev.md). # Generate types (optional, for TypeScript projects) npx base44 types generate -# Build your project first -npm run build - -# Deploy everything (entities, functions, and site) -npx base44 deploy -y +# Deploy everything (entities, functions, and site), building the site first +npx base44 deploy --build -y ``` +Build through the CLI, not with `npm run build`: `npx base44 build` injects `VITE_BASE44_APP_ID`, +which a bare `npm run build` leaves unset — the bundle then can't resolve its own app and every API +call on the deployed site fails. `npx base44 deploy` asks whether to build first; `--build` / +`--no-build` answers up front (non-interactive defaults to upload-only, so CI is unchanged). + ### Generating TypeScript Types ```bash # Generate types from entities, functions, agents, and connectors @@ -657,5 +660,6 @@ Most commands require authentication. If you're not logged in, the CLI will auto | Duplicate connector type | Each connector type can only be defined once per project | | Connector authorization timeout | Re-run `npx base44 connectors push` and complete the OAuth flow in your browser | | No site configuration found | Check that `site.outputDirectory` is configured in project config | -| Site deployment fails | Ensure you ran `npm run build` first and the build succeeded | +| Site deployment fails | Ensure the site was built first (`npx base44 build`, or `npx base44 deploy --build`) and the build succeeded | +| Deployed site's API calls all fail | The bundle was built without its app id — rebuild with `npx base44 build`, not a bare `npm run build`, and redeploy | | Update available message | If prompted to update, run `npm install -g base44@latest` (or use npx for local installs) | From f93dd74f9810fbcce7076772ef4f2189814c1306 Mon Sep 17 00:00:00 2001 From: David Susskind Date: Sun, 9 Aug 2026 10:34:38 +0300 Subject: [PATCH 4/4] docs(base44-cli): cover dev --remote in the dev reference SKILL.md's new --remote row pointed at a reference that didn't know the flag existed. Co-Authored-By: Claude Fable 5 --- skills/base44-cli/references/dev.md | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/skills/base44-cli/references/dev.md b/skills/base44-cli/references/dev.md index 6549d5a..1a09c9f 100644 --- a/skills/base44-cli/references/dev.md +++ b/skills/base44-cli/references/dev.md @@ -15,6 +15,7 @@ npx base44 dev [options] | Option | Description | Required | Default | |--------|-------------|----------|---------| | `-p, --port ` | Port for the local Base44 backend | No | 4400 | +| `--remote` | Serve only the frontend, against your app's production backend | No | — | ## Authentication @@ -54,6 +55,12 @@ Before using `base44 dev` for full-stack local development, verify your config: If `site.serveCommand` is missing, `base44 dev` still works, but it only starts the Base44 backend. +## Remote Mode (`--remote`) + +`npx base44 dev --remote` starts no local backend: it runs only your frontend (`site.serveCommand`), +wired to your app's **production** backend — every read and write hits live data. Use it to develop +the UI against real content; default to plain `base44 dev` otherwise. + ## Examples ```bash @@ -62,6 +69,9 @@ npx base44 dev # Start the backend on a specific port npx base44 dev --port 4500 + +# Frontend only, against the production backend (live data) +npx base44 dev --remote ``` ## Notes