Local development

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

Clone the repository

git clone https://github.com/MaikoCode/nudgra-cloud nudgra-cloud
cd nudgra-cloud

Install packages

npm install

Create the environment file

cp .env.example .env.local

In Windows PowerShell:

Copy-Item .env.example .env.local

Configure local values

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

SITE_URL=http://localhost:3000
NUDGRA_ALLOWED_EMAILS=your-google-email@gmail.com

Google OAuth is required for normal sign-in. Follow Google OAuth, then set:

AUTH_GOOGLE_ID=your-google-client-id
AUTH_GOOGLE_SECRET=your-google-client-secret

Run Convex and Next.js

Start the app:

npm run dev

Open:

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:

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:

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:

SITE_URL=https://your-tunnel.example.com

Use that same tunnel URL for the Meta OAuth redirect.

Useful commands

npm run lint
npm test
npx convex dashboard
npx convex env list

​Prerequisites

​Install dependencies

​Configure local values

​Run Convex and Next.js

​Convex URLs

​Public tunnels

​Useful commands