---
title: "Local Development"
description: "Run Convex next to nuxt dev, understand which environment variables the module reads and in what order, and work without a Convex account."
canonical_url: "https://nuxt-convex.onmax.me/getting-started/local-development"
---
# Local Development

> Run Convex next to nuxt dev, understand which environment variables the module reads and in what order, and work without a Convex account.

Local development runs two processes: `npx convex dev`, which pushes your functions and generates types on every save, and `nuxt dev`.

## Run both processes

```bash [Terminal 1]
npx convex dev
```

```bash [Terminal 2]
npx nuxt dev
```

The first run of `npx convex dev` asks you to log in and pick or create a project. It then:

- creates a development deployment for you
- writes `CONVEX_DEPLOYMENT` and `CONVEX_URL` (plus `CONVEX_SITE_URL`) to `.env.local`
- generates `convex/_generated/`, which `#convex/api` points at
- watches `convex/` and pushes every change

Without a browser to log in (CI, a remote box, a coding agent), create a deploy key for the dev deployment in the Convex dashboard and run the CLI with it. It writes the same `.env.local`:

```bash [Terminal]
CONVEX_DEPLOY_KEY='dev:...' npx convex dev --once
```

Start them in any order. If `nuxt dev` starts first, the module notices when `convex/_generated/` appears and picks it up without a restart.

To run both from one terminal, let the Convex CLI start Nuxt alongside it:

```bash [Terminal]
npx convex dev --start 'nuxt dev'
```

## Environment variables

Nuxt loads `.env` by itself but not `.env.local`, which is where `npx convex dev` writes. `nuxt-convex` reads `.env.local` itself, in development only.

The deployment URL is resolved in this order, first match wins:

<table>
<thead>
  <tr>
    <th>
      #
    </th>
    
    <th>
      Source
    </th>
    
    <th>
      When
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      1
    </td>
    
    <td>
      <code>
        convex.url
      </code>
      
       in <code>
        nuxt.config.ts
      </code>
    </td>
    
    <td>
      always
    </td>
  </tr>
  
  <tr>
    <td>
      2
    </td>
    
    <td>
      <code>
        CONVEX_URL
      </code>
    </td>
    
    <td>
      process env, or <code>
        .env
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      3
    </td>
    
    <td>
      <code>
        NUXT_PUBLIC_CONVEX_URL
      </code>
    </td>
    
    <td>
      process env, or <code>
        .env
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      4
    </td>
    
    <td>
      <code>
        VITE_CONVEX_URL
      </code>
    </td>
    
    <td>
      process env, or <code>
        .env
      </code>
      
       (the Convex CLI writes this name when your <code>
        package.json
      </code>
      
       lists <code>
        vite
      </code>
      
      )
    </td>
  </tr>
  
  <tr>
    <td>
      5
    </td>
    
    <td>
      the same names in <code>
        .env.local
      </code>
    </td>
    
    <td>
      <code>
        nuxt dev
      </code>
      
       only
    </td>
  </tr>
</tbody>
</table>

The site URL, used by the Better Auth proxy, follows the same order with `convex.siteUrl`, `CONVEX_SITE_URL`, `NUXT_PUBLIC_CONVEX_SITE_URL` and `VITE_CONVEX_SITE_URL`. When none is set, it's derived from the deployment URL: `https://x.convex.cloud` becomes `https://x.convex.site`, and a local backend's port goes up by one.

At run time, `NUXT_PUBLIC_CONVEX_URL` and `NUXT_PUBLIC_CONVEX_SITE_URL` override whatever was resolved at build time. See [Deployment](https://nuxt-convex.onmax.me/nuxt-module/deployment).

`CONVEX_DEPLOYMENT` isn't needed by the app. The module uses it to link the DevTools tab to the right deployment in the Convex dashboard.

<note>

`.env.local` is only read by `nuxt dev`. `nuxt build` and `nuxt generate` ignore it, so a production build never picks up a developer's deployment by accident. Pass `--dotenv .env.local` to `nuxi build` if you do want it.

</note>

## Work without a Convex account

Convex can run a local, anonymous backend, with no login. It's handy for trying the module, for CI, and for coding agents:

```bash [Terminal]
CONVEX_AGENT_MODE=anonymous npx convex dev
```

The backend listens on `http://127.0.0.1:3210`, HTTP actions on port `3211`, and the dashboard on `http://127.0.0.1:6790`. The CLI writes those URLs to `.env.local` as usual, the site URL is derived correctly, and the DevTools tab links to the local dashboard. Data lives on your machine; run `npx convex dev` again without the variable to move to a cloud deployment later.

## Set Convex environment variables

Variables your Convex functions read, such as `BETTER_AUTH_SECRET` or R2 credentials, live in the deployment, not in Nuxt's `.env`:

```bash [Terminal]
npx convex env set BETTER_AUTH_SECRET "$(openssl rand -base64 32)"
npx convex env list
```

## DevTools

With Nuxt DevTools enabled, the module adds a **Convex** tab in development. It links to your deployment's data, functions and logs in the Convex dashboard (the dashboard refuses to be embedded, so it opens in a new tab). Turn it off with `convex.devtools: false`.

## Next steps

- [Deployment](https://nuxt-convex.onmax.me/nuxt-module/deployment) for production environments
- [Module Configuration](https://nuxt-convex.onmax.me/api-reference/module-configuration) for every option
- [Troubleshooting](https://nuxt-convex.onmax.me/troubleshooting) if the app starts disconnected


## Sitemap

See the full [sitemap](https://nuxt-convex.onmax.me/sitemap.md) for all pages.