Skip to content
Toprent.app Docs

Setup & Environment

Requirements:

  • Node 22
  • Yarn 1.x (repo uses yarn.lock)
  • Vercel npm package installed globally
  • Neon cli installed globally

Environment variables: see .env.example and next.config.js env exposure.

  • Core: NEXT_PUBLIC_VERCEL_URL, GOOGLE_API_KEY, CLOUDINARY_*, MAILGUN_*, TWILIO_*, STRIPE_WEBHOOK_SECRET, FIREBASE_KEY, ROOT_KEY (Fauna root), etc.
  • Database: ROOT_POSTGRES_URL, ROOT_POSTGRES_URL_NON_POOLING (Neon PostgreSQL)
  • Edge Config: must provide cargosCredentialsKey (used for CARGOS credentials encryption/masking)

Pre-install:

Terminal window
npm i -g neonctl
neon auth

Installation:

Terminal window
yarn
# Generate Prisma client and Relay/GraphQL artifacts
yarn postinstall

Local development:

Terminal window
yarn dev

Optional tooling:

  • Spotlight: runs automatically with yarn dev (telemetry UI at http://localhost:8969)
  • Storybook: yarn storybook

Build & start:

Terminal window
yarn build
yarn start

Secrets management:

  • Fetch secrets: vc env pull .env
  • Local via .env.local
  • Vercel project vars for deployment

Neon Database Branching

The project uses automated Neon database branching integrated with Git workflows. Each Git branch can have its own isolated database.

Quick Setup:

Terminal window
# Install neonctl package
npm i -g neonctl
neon auth

How it works:

  • Creating a new Git branch → Automatically creates a Neon database branch from develop
  • Switching Git branches → Automatically switches to that branch’s database
  • Updates .env with ROOT_POSTGRES_URL and ROOT_POSTGRES_URL_NON_POOLING
  • Provisions a disposable <branch>-shadow Neon branch (6h TTL) and writes SHADOW_DATABASE_URL for Prisma Migrate’s shadow database, so prisma_migrate_shadow_db_* databases are not created on the working branch
  • Fallback to develop database if branch creation or connection string retrieval fails

Manual operations:

Terminal window
npm run neon:list                   # List all Neon branches
npm run neon:create -- feature/x    # Create branch manually
npm run neon:sync                   # Sync current git branch to Neon

Disable automation: Set NEON_DB_HOOKS_DISABLED=1 to skip automatic database switching on branch checkout.

See also:

  • Architecture decision: docs/adr/0010-neon-git-hooks-automation.md