# Run Locally (/en/docs/tanstack-start/run-locally)

After [Quickstart](/en/docs/quickstart), start local
Supabase, refresh the app's connection settings, then run Vite.

## Daily development

<Steps>
  <Step>
    ### Start Supabase

    ```bash
    bunx supabase start
    ```

    Keep Docker running. This reuses the checkout's local database.
  </Step>

  <Step>
    ### Sync the app

    ```bash
    ./coremvp env sync
    ```

    Run from the repository root. The CLI derives local connection settings
    from the already-running Supabase instance and writes `.env.local`.
  </Step>

  <Step>
    ### Start the app

    ```bash
    bun run dev
    ```

    Open `http://localhost:3000`. Source edits hot reload. Restart this process
    after changing environment settings.
  </Step>
</Steps>

Use `./coremvp env list` to inspect redacted key presence. The terminal running
`bun run dev` contains the web logs. The CLI does not start or stop the app.

## Update a retained database

After pulling an update with new migrations, apply them without resetting your
local data:

```bash
bunx supabase migration up --local
bunx supabase migration list --local
```

Continue when every checked-in migration matches its applied local version.
Stop and inspect any mismatch or migration error. Do not reset retained data
to install a feature.

## Run the local build

```bash
bun run build
```

The script compiles the app and runs TypeScript checking. Nitro writes the
server entry, traced dependencies and public assets under `.output/`.

Before sending email from the built app, set `EMAIL_DELIVERY_MODE` in ignored
`.env.local` to `test_capture` with a private `TEST_EMAIL_CAPTURE_TOKEN`, or
to `real` with `RESEND_API_KEY` and `RESEND_FROM_EMAIL`. The built app rejects
`mock` when a send is attempted. Signed-in purchase confirmations are suppressed
in `mock` and `test_capture` before send validation; guest capture requires its
setup link and test run ID. Follow [Email Delivery](/en/docs/email/delivery)
for the mode requirements.

Stop the development process so port `3000` is free, then start the Node output:

```bash
NODE_ENV=production node --env-file=.env.local .output/server/index.mjs
```

Open the local app and repeat your sign-in and page checks. Keep `.env.local`
outside build artifacts. Vite embeds `NEXT_PUBLIC_*` settings at build time;
changing a public setting requires another build. See the Start [hosted deployment status](/en/docs/deployment#tanstack-start-deployment-status) for hosted deployment.

## Check the application

Keep the app and Supabase running in their existing terminals, then choose the
check for your change:

| Change                                          | Local command                        |
| ----------------------------------------------- | ------------------------------------ |
| Auth forms, cookies or admission                | `./coremvp e2e auth`                 |
| Organizations and permissions                   | `./coremvp e2e organizations`        |
| Projects and persistence                        | `./coremvp e2e projects`             |
| File validation and controlled Storage failures | `bun test src/tests/storage.test.ts` |

The [Auth testing guide](/en/docs/authentication/test-authentication) explains
the local browser boundary and OAuth limits. [Storage](/en/docs/storage) also
describes the separate checks needed for real Storage policies.

Billing needs the selected provider's configured test catalog or offers and an
active listener. Complete the matching setup in [Billing](/en/docs/billing)
before running its checkout tests; the commands stay in that shared guide.

## Stop or reset

Stop the app with `Ctrl+C` in its terminal. Stop local Supabase when you finish:

```bash
bunx supabase stop
```

When you intentionally want a clean local database, keep Supabase running and
use:

```bash
bunx supabase db reset --local
```

Reset replaces local data and reapplies the checked-in migrations. Seeding is
off, so it does not create sample records or a provider catalog. Follow the matching
[Billing setup](/en/docs/billing) to configure your offers.

If Supabase reports `template database "template1" has a collation version mismatch`,
recreating local Supabase data is a destructive recovery. Preserve any data you
need before running:

```bash
bunx supabase stop --no-backup
bunx supabase start
```

Then verify migrations and sync the local environment again before starting
the app.

## What's next

<Cards>
  <Card title="Configure Environment" href="/en/docs/tanstack-start/configure-environment" description="Understand public build settings and server-only credentials." />

  <Card title="Use CoreMVP CLI" href="/en/docs/getting-started/coremvp-cli" description="Look up supported local environment and test commands." />

  <Card title="Customize Dashboard" href="/en/docs/frontend/customize-dashboard" description="Make a native UI change and verify it locally." />
</Cards>