Setup and Installation
Install dependencies, configure local settings, start the database and app, and verify your installation.
Run setup from the repository root after cloning the kit.
Run Setup
node scripts/setup.mjsIf pnpm is already available, you can use the equivalent command:
pnpm kit:setupThe setup entry point checks Node.js, enables pnpm when possible, installs workspace dependencies when they are missing, and builds the kit's command tools through the install hook. The setup journey then:
- Creates
apps/web/.envfromapps/web/env.exampleand generates a randomBETTER_AUTH_SECRET. On later runs it fills missing settings, preserves configured values, and replaces an empty or example auth secret. - Starts the local PGlite database in the background on port 54323.
- Applies database migrations.
- Starts the app in the background at http://localhost:5173.
- Asks whether to add demo accounts if the database has no accounts. Demo data requires your explicit confirmation; setup skips it once accounts exist.
Let setup create the settings file: copying env.example yourself leaves its auth secret empty. You can rerun setup to finish an interrupted installation.
Verify Your Installation
Open http://localhost:5173. Without demo data, create your first account.
If you accepted demo data, sign in with user1@makerkit.dev and password testingpassword. Demo users run from user1@makerkit.dev through user5@makerkit.dev; these credentials are for local development.
Verification links and codes go to Void's development email inbox. Open .makerkit/processes/app.log locally and follow the link after Email inbox. That link contains an access key; keep it private. Complete any email verification the sign-up flow requests, then confirm you can reach the app after signing in.
Check setup status at any time:
pnpm kit:doctorThe doctor reports what is ready and what still needs attention without changing your project. Follow the next command it returns for the area you are setting up.
Daily Development
Setup leaves the app and database running in the background. Stop them with:
pnpm kit:stopRun pnpm kit:setup to start them again. To run both services in the foreground instead, stop the managed processes, then start the database in one terminal:
pnpm db:startKeep that terminal open. In a second terminal at the repository root, start the app:
pnpm devPress Ctrl+C to stop the foreground app; pnpm db:stop stops the database. Existing local data persists between restarts.
| Command | Purpose |
|---|---|
pnpm check | Check formatting, lint, and types without changing files |
pnpm test:unit | Run unit tests |
pnpm test:e2e | Run Playwright browser tests |
pnpm build | Build the workspace |
Troubleshooting
- Node version rejected: use
nvm installandnvm use, or select a version allowed bypackage.jsonin your version manager. - pnpm cannot be enabled: follow the bootstrap error's pnpm installation instructions, then rerun setup.
- Dependency installation failed: resolve the error printed by
pnpm install, then rerun setup. - App or database failed to start: check
.makerkit/processes/app.logor.makerkit/processes/database.log. If another process occupies port 5173 or 54323, stop that process or follow the kit command's recovery instructions, then rerun setup. - Sign-up email missing: use the development inbox link in the app log; local emails do not arrive in your personal mailbox.
Next Steps
Continue with Configuration to choose account modes, navigation, feature flags, and theme. Configure payment testing through Billing. Follow Deployment when you are ready to deploy to your Cloudflare account.