Skip to content

Local-Setup.md

Latest commit

 

History

History
106 lines (71 loc) · 2.54 KB

Local-Setup.md

File metadata and controls

106 lines (71 loc) · 2.54 KB
Raw

Local setup

This guide starts the full NeonFlux development stack from a fresh checkout.

Requirements

  • Node 24.19.0
  • pnpm 12
  • a Fluxer application with an OAuth client and bot token
  • a Convex development deployment

Docker is optional for normal development. It is required for authenticated end-to-end checks and local production-container checks.

Install the workspace

From the repository root:

cd projects
pnpm install
cp .env.example .env

Use PowerShell when appropriate:

Copy-Item .env.example .env

projects/.env is the application configuration source. An ignored .env.local may contain Convex CLI linking metadata, but NeonFlux does not read application secrets from it.

Create local secrets

Preview the values the setup workflow would add:

pnpm setup:dev

Write only missing local values:

pnpm setup:dev -- --write

The workflow creates a session secret, an OAuth token-encryption key, and separate signing keys for bot, web-service, and browser-user Convex identities. It preserves existing values and never prints generated secrets.

Add your Fluxer application ID, OAuth client secret, bot token, and registered callback URL yourself.

Configure Convex

Validate local auth material without contacting a deployment:

pnpm convex:validate-auth-config

Preview target configuration before applying it:

pnpm convex:configure-auth-env -- --deployment <target>
pnpm convex:configure-runtime-env -- --deployment <target>

Apply only after the output names the intended deployment:

pnpm convex:configure-auth-env -- --deployment <target> --apply --confirm-apply-target <target>
pnpm convex:configure-runtime-env -- --deployment <target> --apply --confirm-apply-target <target>
pnpm convex:check-auth-env -- --deployment <target> --compare-deploy-env

Read Convex before changing, resetting, or self-hosting a deployment.

Start NeonFlux

pnpm dev

This uploads checked Convex functions once, then starts Convex development tooling, the bot, and the web app together.

Use isolated processes for focused work:

pnpm dev:bot
pnpm dev:web

The public website needs only the web process. The signed-in dashboard needs valid Convex authentication and a connected bot for live Fluxer access.

Hosted CAPTCHA links use PUBLIC_WEB_URL. Use http://localhost:3000 for same-machine local testing.

Validate the checkout

pnpm check
pnpm audit:prod

Read Contributing for browser, authenticated, and container checks.