Skip to content

docs(base44-cli): local data persistence & seeding for base44 dev #140

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
netanelgilad wants to merge 1 commit into
base: main
Choose a base branch
from
Draft

docs(base44-cli): local data persistence & seeding for base44 dev #140

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
32 changes: 29 additions & 3 deletions skills/base44-cli/SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -119,8 +119,13 @@ my-app/
│ │ └── entry.ts
│ ├── agents/ # Agent configurations (optional)
│ │ └── support_agent.jsonc
│ └── connectors/ # OAuth connector configurations (optional)
│ └── googlecalendar.jsonc
│ ├── connectors/ # OAuth connector configurations (optional)
│ │ └── googlecalendar.jsonc
│ ├── seed/ # Local dev seed fixtures (optional)
│ │ ├── users.jsonc # Test users for `base44 dev`
│ │ └── Task.jsonc # Records for entity "Task"
│ └── seed.ts # Programmatic seed script (optional, runs in Deno)
├── .base44/ # Local dev state: data + dev.json (gitignored, safe to delete)
├── src/ # Frontend source code
│ ├── api/
│ │ └── base44Client.js # Base44 SDK client
Expand All @@ -139,6 +144,9 @@ my-app/
- `base44/agents/*.jsonc` - Agent configurations (optional)
- `base44/.types/types.d.ts` - Auto-generated TypeScript types for entities, functions, and agents (created by `npx base44 types generate`)
- `base44/connectors/*.jsonc` - OAuth connector configurations (optional)
- `base44/seed/*.jsonc` - Local dev seed fixtures: `users.jsonc` + `<Entity>.jsonc` (see [local-data.md](references/local-data.md))
- `base44/seed.ts` - Programmatic seed script, runs after fixtures (optional, requires Deno)
- `.base44/` - Local dev state written by `base44 dev` (gitignored, safe to delete)
- `src/api/base44Client.js` - Pre-configured SDK client for frontend use

**config.jsonc example:**
Expand All @@ -150,6 +158,7 @@ my-app/
"functionsDir": "./functions", // Optional: default "functions"
"agentsDir": "./agents", // Optional: default "agents"
"connectorsDir": "./connectors", // Optional: default "connectors"
"seedDir": "./seed", // Optional: default "seed"
"site": { // Optional: site deployment config
"installCommand": "npm install", // Optional: install dependencies
"buildCommand": "npm run build", // Optional: build command
Expand All @@ -169,6 +178,7 @@ my-app/
| `functionsDir` | Directory for backend functions | `"functions"` |
| `agentsDir` | Directory for agent configs | `"agents"` |
| `connectorsDir` | Directory for connector configs | `"connectors"` |
| `seedDir` | Directory for local dev seed fixtures | `"seed"` |
| `site.installCommand` | Command to install dependencies | - |
| `site.buildCommand` | Command to build the project | - |
| `site.serveCommand` | Command to run dev server | - |
Expand Down Expand Up @@ -248,7 +258,19 @@ npx base44 logs --app-id app_123 --json

| 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` | Start local development for your Base44 backend, and your frontend too when `site.serveCommand` is configured; `--fresh` wipes local data and re-seeds | [dev.md](references/dev.md) |
| `base44 dev status` | Show the local dev instance descriptor (URL, port, pid, seed state) | [local-data.md](references/local-data.md) |
| `base44 dev seed` | Apply seed fixtures and `seed.ts` to local data (idempotent upsert; `--replace` truncates first) | [local-data.md](references/local-data.md) |
| `base44 dev reset` | Wipe local data and re-seed — the canonical clean-slate command | [local-data.md](references/local-data.md) |

### Local Data

Local dev data is persistent by default (gitignored `.base44/` directory) and seedable from `base44/seed/` fixtures. Full guide: [local-data.md](references/local-data.md).

| Command | Description | Reference |
|---------|-------------|-----------|
| `base44 data pull` | Pull records from the remote app into `base44/seed/` fixtures (read-only against remote) | [local-data.md](references/local-data.md) |
| `base44 data dump` | Freeze local dev data as `base44/seed/` fixtures | [local-data.md](references/local-data.md) |

### Deployment

Expand Down Expand Up @@ -509,6 +531,8 @@ 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.

Local entity data persists in a gitignored `.base44/` directory — it survives restarts and entity edits. Seed fixtures in `base44/seed/` are applied automatically on first boot; use `npx base44 dev seed` to re-apply and `npx base44 dev reset` for a clean slate. See [local-data.md](references/local-data.md).

### Deploying All Changes
```bash
# Generate types (optional, for TypeScript projects)
Expand Down Expand Up @@ -579,5 +603,7 @@ 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 |
| Local dev data is stale or broken | Run `npx base44 dev reset` (or start with `npx base44 dev --fresh`); `.base44/` is safe to delete |
| `dev` refuses to start (app id mismatch) | The folder was relinked to a different app — start with `npx base44 dev --fresh` to wipe the old local data |
| Site deployment fails | Ensure you ran `npm run build` first and the build succeeded |
| Update available message | If prompted to update, run `npm install -g base44@latest` (or use npx for local installs) |
41 changes: 37 additions & 4 deletions skills/base44-cli/references/dev.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,6 +15,7 @@ npx base44 dev [options]
| Option | Description | Required | Default |
|--------|-------------|----------|---------|
| `-p, --port <number>` | Port for the local Base44 backend | No | 4400 |
| `--fresh` | Wipe the local data directory before starting, then re-seed | No | - |

## Authentication

Expand All @@ -30,10 +31,38 @@ npx base44 dev [options]

1. Reads your linked local project configuration
2. Starts the local Base44 backend for entities, functions, and auth routes
3. Watches local Base44 resources and reloads them when they change
4. If `site.serveCommand` is configured, starts your frontend dev server from the project root
5. Injects `VITE_BASE44_APP_ID` and `VITE_BASE44_APP_BASE_URL` into the frontend process
6. Shuts everything down cleanly when you stop the command
3. Opens the persistent local database in `.base44/data/` (created on first run)
4. If the data directory is empty, applies seeds from `base44/seed/` (and `base44/seed.ts` if present)
5. Writes the instance descriptor `.base44/dev.json` (read by `base44 dev status`)
6. Watches local Base44 resources and reloads them when they change — entity edits reload schemas only, data is preserved
7. If `site.serveCommand` is configured, starts your frontend dev server from the project root
8. Injects `VITE_BASE44_APP_ID` and `VITE_BASE44_APP_BASE_URL` into the frontend process
9. Shuts everything down cleanly when you stop the command (removes `dev.json`)

## Local Data Persistence

**Requires CLI version >= 0.0.x (upcoming release).** Local entity data is **persistent by default**:

- Data lives in a gitignored, project-relative `.base44/` directory — it survives restarts and entity-file edits (schemas reload, data preserved)
- `.base44/` is safe to delete at any time; the next `base44 dev` starts clean and re-seeds
- Because state is project-relative, every git worktree gets isolated local data automatically
- Ephemeral is the opt-in: `npx base44 dev --fresh` wipes the data directory and re-seeds on startup
- If `.base44/` belongs to a different app than the linked one (e.g. the folder was relinked), `dev` warns and refuses to start — pass `--fresh` to wipe and continue

## Seed-on-First-Boot Lifecycle

Seeds are applied automatically **only when the data directory is empty** (first run, after `base44 dev reset`, or with `--fresh`). Existing data is never silently re-seeded.

```
base44 dev # data dir empty? → apply seeds; else leave data alone
base44 dev --fresh # wipe data dir → apply seeds
base44 dev seed # apply seeds NOW (idempotent upsert; --replace to truncate first)
base44 dev reset # wipe + re-seed — the canonical clean-slate command
```

If seed files changed since the last apply, `dev` logs a hint to run `base44 dev seed`.

See [local-data.md](local-data.md) for the full guide: state directory layout, `dev.json` and `base44 dev status`, seed fixture formats (`base44/seed/`), the programmatic `base44/seed.ts` hook, and `base44 data pull` / `base44 data dump`.

## Frontend + Backend Behavior

Expand Down Expand Up @@ -62,10 +91,14 @@ npx base44 dev

# Start the backend on a specific port
npx base44 dev --port 4500

# Start from a clean slate (wipe local data, re-seed)
npx base44 dev --fresh
```

## Notes

- Use this from a linked local project, not with `--app-id`
- When the frontend is running, the CLI streams backend and frontend output together
- If the frontend process exits, the local dev environment shuts down too
- Local data, seeding, and the related commands (`dev status`, `dev seed`, `dev reset`, `data pull`, `data dump`) are documented in [local-data.md](local-data.md)
Loading
Loading