Skip to main content

Getting Started

This guide covers the three major parts of the project: the Next.js application, the Supabase backend, and the Docusaurus documentation site.

1. Prerequisites​

  • Node.js (v18+ recommended)
  • Yarn classic (npm install -g yarn)
  • Supabase CLI (https://supabase.com/docs/guides/cli)
  • npx (for docs if already used).
  • Docker Desktop (required for Supabase local stack)

2. Repository Setup​

git clone <repo-url>
cd civiq-validation

3. Next.js App (App/)​

Install dependencies

cd App
yarn install

Environment setup

cp .env.example .env.local

Fill values for API keys, Supabase URL/anon key, etc.

Run dev server

yarn dev
  • App available at http://localhost:3000.

4. Supabase Backend (supabase/)​

Install CLI (if not already)

npm install -g supabase

Start local services

supabase start
  • Supabase Studio: http://localhost:54323
  • API: http://localhost:54321

Link to remote database

supabase link --project-ref your-project-ref

Pull remote schema (first time setup)

supabase db pull

This creates migration files from your remote database schema.

Apply migrations

supabase db reset

Making schema changes

  1. Make changes via Supabase Studio (http://localhost:54323)
  2. When ready to push changes to remote, generate a diff:
supabase db diff -f migration_name
  1. Review the generated migration file in supabase/migrations/
  2. Commit changes to GitHub:
git add .
git commit -m "Add migration: migration_name"
git push

The changes will automatically deploy to your remote database.

Creating and serving Edge Functions

Edge Functions live in supabase/functions/ directory.

Create a new function:

supabase functions new function-name

Serve functions locally:

supabase functions serve

Deploy specific Function:

supabase functions deploy function-name

Deploy all functions:

supabase functions deploy

OR Just commit and gitHub will automatically deploy the functions Syncing remote data to local database

Fetch data from remote:

supabase db dump -f dump.sql --data-only

Load data into local database:

psql "postgresql://postgres:postgres@localhost:54322/postgres" -f dump.sql

Stop services

supabase stop

5. Documentation Site (docs/)​

Docusaurus v3.9 powers the docs source.

Install dependencies

cd ../docs
npm install

Local development

npx docusaurus start
  • Docs served at http://localhost:3000 (adjust if port conflict).

Static build

npm run build
  • Output in docs/build/.

Serve built site (preview)

npm run serve

6. Common Tasks​

  • Keep Supabase running while working on the Next.js app; update App/.env.local if Supabase credentials change.
  • Before committing, ensure yarn build and npm run build complete successfully.

7. Troubleshooting​

  • If supabase start fails, confirm Docker is running and ports are free.
  • For Docusaurus hot reload issues, restart npx docusaurus start.

8. Suggested Next Steps​

  • Open Supabase Studio and confirm schema matches expectations.
  • Create sample data and confirm Next.js app reads it.
  • Customize docs by editing MDX pages in docs/src.
  • Always make sure correct schema is deployed after PR merge.