> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nudgra.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Local development

> Run Nudgra Cloud locally with Next.js and Convex.

Local development is best for dashboard development and UI testing. For a complete Instagram webhook flow, use a deployed Convex site URL and a public app domain or tunnel because Meta cannot call `localhost`.

## Prerequisites

Install:

* Git.
* Node.js 24 or newer.
* A Convex account.

## Install dependencies

<Steps>
  <Step title="Clone the repository">
    ```bash theme={null}
    git clone https://github.com/MaikoCode/nudgra-cloud nudgra-cloud
    cd nudgra-cloud
    ```
  </Step>

  <Step title="Install packages">
    ```bash theme={null}
    npm install
    ```
  </Step>

  <Step title="Create the environment file">
    ```bash theme={null}
    cp .env.example .env.local
    ```

    In Windows PowerShell:

    ```powershell theme={null}
    Copy-Item .env.example .env.local
    ```
  </Step>
</Steps>

## Configure local values

At minimum, set these values in `.env.local`:

```env theme={null}
SITE_URL=http://localhost:3000
NUDGRA_ALLOWED_EMAILS=your-google-email@gmail.com
```

Google OAuth is required for normal sign-in. Follow [Google OAuth](/shared/google-oauth), then set:

```env theme={null}
AUTH_GOOGLE_ID=your-google-client-id
AUTH_GOOGLE_SECRET=your-google-client-secret
```

## Run Convex and Next.js

Start the app:

```bash theme={null}
npm run dev
```

Open:

```text theme={null}
http://localhost:3000
```

The local dev flow runs Next.js and `convex dev` together. The `predev` flow initializes Convex, runs the Convex Auth setup helper once, and opens the Convex dashboard.

If the Convex Auth setup helper prompts for `SITE_URL`, use the local or tunnel URL you configured.

## Convex URLs

`npx convex dev` writes these values locally:

```env theme={null}
NEXT_PUBLIC_CONVEX_URL=https://your-dev-deployment.convex.cloud
NEXT_PUBLIC_CONVEX_SITE_URL=https://your-dev-deployment.convex.site
```

For local Google OAuth, use the Convex site URL as the redirect URI, not the Next.js app URL:

```text theme={null}
Authorized JavaScript origin:
http://localhost:3000

Authorized redirect URI:
https://your-dev-deployment.convex.site/api/auth/callback/google
```

## Public tunnels

For local Meta OAuth or tracked links, set `SITE_URL` to a public tunnel URL instead of `http://localhost:3000`:

```env theme={null}
SITE_URL=https://your-tunnel.example.com
```

Use that same tunnel URL for the Meta OAuth redirect.

## Useful commands

```bash theme={null}
npm run lint
npm test
npx convex dashboard
npx convex env list
```