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.mjs

If pnpm is already available, you can use the equivalent command:

pnpm kit:setup

The 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:

  1. Creates apps/web/.env from apps/web/env.example and generates a random BETTER_AUTH_SECRET. On later runs it fills missing settings, preserves configured values, and replaces an empty or example auth secret.
  2. Starts the local PGlite database in the background on port 54323.
  3. Applies database migrations.
  4. Starts the app in the background at http://localhost:5173.
  5. 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:doctor

The 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:stop

Run 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:start

Keep that terminal open. In a second terminal at the repository root, start the app:

pnpm dev

Press Ctrl+C to stop the foreground app; pnpm db:stop stops the database. Existing local data persists between restarts.

CommandPurpose
pnpm checkCheck formatting, lint, and types without changing files
pnpm test:unitRun unit tests
pnpm test:e2eRun Playwright browser tests
pnpm buildBuild the workspace

Troubleshooting

  • Node version rejected: use nvm install and nvm use, or select a version allowed by package.json in 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.log or .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.