Getting Started

This guide gets a fresh Leave Localhost checkout running locally. It assumes you want the full starter experience: product app, marketing site, Convex backend, and React Email preview server.

Prerequisites

• Bun. The repository is configured for bun@1.2.22.
• A Convex account for the backend project.
• Optional service accounts for email, analytics, monitoring, and billing.

Use Bun for all repo workflows. Do not install dependencies with npm, pnpm, or yarn unless you are intentionally testing package-manager compatibility.

Install The Repository

git clone https://github.com/leavelocalhost/leave-localhost-starter.git
cd leave-localhost-starter
bun install

If you are starting a new product from the starter, initialize your own git history after cloning or copying the repository:

git init
git add .
git commit -m "Initial commit"

Create Local Environment Files

Copy the example files:

cp apps/app/.env.example apps/app/.env
cp apps/marketing/.env.example apps/marketing/.env
cp apps/docs/.env.example apps/docs/.env
cp packages/backend/.env.example packages/backend/.env

Then fill the required values described in Environment Variables.

Start by renaming the product:

• Set APP_NAME in packages/backend/.env.
• Set SITE_URL in packages/backend/.env to the product app URL.
• Set NEXT_PUBLIC_SITE_URL in apps/marketing/.env to the public marketing URL.
• Update packages/config/src/brand.ts for the static browser-visible name, labels, logo alt text, support email, GitHub URL, and default copy.

Keep APP_NAME aligned with brandConfig.appName: the backend value controls the auth issuer and security emails while the static brand module controls browser-visible metadata and labels. Do this before configuring OAuth, email, or billing so provider dashboards do not inherit starter placeholders.

The minimum local setup needs:

• apps/app/.env: Convex client URL, Convex site URL, app URL, and docs URL.
• apps/marketing/.env: nothing required — the marketing site builds with local defaults and does not use Convex.
• packages/backend/.env: app name, Convex site URL, site URL, Better Auth secret, and Google OAuth credentials.

Set Up Convex

From the backend workspace, create or attach a Convex deployment:

bun --cwd packages/backend setup

The setup command runs Convex once and sets VALIDATE_ENV=true in the Convex environment. It can fail after project creation if required environment variables are not configured yet. That is expected during first setup.

After your backend .env is filled, sync server-side variables to Convex. Convex functions do not read packages/backend/.env at runtime.

bun --cwd packages/backend convex env set BETTER_AUTH_SECRET "your-secret"
bun --cwd packages/backend convex env set APP_NAME "Acme App"
bun --cwd packages/backend convex env set SITE_URL "http://localhost:3000"

Set the rest of the backend variables the same way, especially email, OAuth, and billing values you enable.

Validate Setup

Run the setup doctor before starting the app:

bun setup:doctor

Fix any errors before continuing. Warnings usually mean optional integrations are not configured yet. See Setup Doctor for options.

Start Development

Start all development services:

bun dev

Default local ports:

• Product app: http://localhost:3000
• Marketing site: http://localhost:3002
• React Email preview: http://localhost:3003
• Documentation site: http://localhost:3004
• Convex dev: managed by the Convex CLI

Focused development commands:

bun dev:app
bun dev:marketing
bun dev:docs
bun dev:convex
bun dev:email

Verify The Workspace

Run these before making larger changes:

bun run lint
bun run typecheck
bun run test

For a production-confidence check:

bun run build

The build runs the env doctor first. If you intentionally need to bypass that check in a constrained environment, use:

SKIP_ENV_DOCTOR=1 bun run build

Next Reads

• Installation: dependency and workspace setup.
• Project Structure: where code belongs.
• Environment Variables: required and optional configuration.
• Deployment: production deployment checklist.