Skip to main content

​
Installation

This guide walks you through setting up PromptRepo for local development. You’ll run Supabase locally using Docker, configure environment variables, and start the Next.js dev server.
PromptRepo is designed for both local development and cloud deployment. This guide covers local setup.

​
Prerequisites

Before you begin, ensure you have the following installed:
1

Node.js 20+

PromptRepo requires Node.js version 20 or higher.Check your version:
node --version
If you need to install or upgrade Node.js, download it from nodejs.org or use a version manager like nvm.
2

Docker

Supabase Local Development requires Docker to run PostgreSQL, Auth, and other services.Install Docker:Verify Docker is running:
docker --version
3

Supabase CLI

The Supabase CLI manages local development environments and database migrations.Install globally via npm:
npm install -g supabase
Verify installation:
supabase --version
Docker must be running before you start Supabase Local Development. If Docker is not running, you’ll see connection errors when running npx supabase start.

​
Setup Steps

​
1. Clone the Repository

1

Clone the repo

git clone <repo-url>
cd prompt-repo
Replace <repo-url> with the actual repository URL.
2

Install dependencies

npm install
This installs all dependencies including Next.js 15, Supabase client libraries, Tailwind CSS 4, and testing tools.

​
2. Start Supabase Local Development

Supabase Local runs PostgreSQL, Auth, Storage, and other services in Docker containers.
1

Initialize Supabase

npx supabase start
The first run downloads Docker images and applies migrations. This may take 2-5 minutes depending on your internet connection.
Expected output:
Started supabase local development setup.

         API URL: http://127.0.0.1:54321
      GraphQL URL: http://127.0.0.1:54321/graphql/v1
   S3 Storage URL: http://127.0.0.1:54321/storage/v1/s3
          DB URL: postgresql://postgres:[email protected]:54322/postgres
      Studio URL: http://127.0.0.1:54323
    Inbucket URL: http://127.0.0.1:54324
      JWT secret: super-secret-jwt-token-with-at-least-32-characters-long
        anon key: eyJh...
service_role key: eyJh...
2

Copy the anon key and service_role key

You’ll need these values for your .env.local file. Save them somewhere safe.
The Supabase Studio URL (http://127.0.0.1:54323) provides a web UI for browsing your database, running queries, and managing auth users.

​
3. Configure Environment Variables

1

Create a .env.local file

In the project root, create a file named .env.local:
touch .env.local
2

Add Supabase credentials

Copy the following template and replace the placeholder values with your keys from Step 2:
.env.local
# Supabase Local Development
NEXT_PUBLIC_SUPABASE_URL=http://127.0.0.1:54321
NEXT_PUBLIC_SUPABASE_ANON_KEY=your-local-anon-key-from-supabase-start
SUPABASE_SERVICE_ROLE_KEY=your-local-service-role-key-from-supabase-start

# OAuth (Optional for local development)
# GITHUB_CLIENT_ID=your-github-client-id
# GITHUB_CLIENT_SECRET=your-github-client-secret
# GOOGLE_CLIENT_ID=your-google-client-id
# GOOGLE_CLIENT_SECRET=your-google-client-secret
SUPABASE_SERVICE_ROLE_KEY is required for the MCP server endpoint (/api/mcp). This key bypasses Row-Level Security (RLS) and should never be exposed to the client.
3

OAuth setup (optional)

If you want to test GitHub or Google OAuth locally:
  1. Create OAuth apps on GitHub or Google Cloud Console
  2. Set the callback URL to http://127.0.0.1:54321/auth/v1/callback
  3. Add the client ID and secret to .env.local
  4. Restart Supabase: npx supabase stop && npx supabase start
For local development, you can skip OAuth and use email/password authentication. OAuth is recommended for production.

​
4. Run Database Migrations

PromptRepo includes versioned SQL migrations in supabase/migrations/. These are automatically applied when you run npx supabase start, but you can verify them:
1

Check migration status

npx supabase migration list
You should see all migrations marked as Applied:
20260208000000_init_foundation.sql [Applied]
20260208000001_prompt_schema.sql [Applied]
20260208000002_search_index.sql [Applied]
20260208000003_collections.sql [Applied]
20260208000004_prompt_snapshots.sql [Applied]
20260208000005_update_search_rpc.sql [Applied]
20260226000006_prompt_lifecycle_archive.sql [Applied]
20260227000007_prompt_public_sharing.sql [Applied]
20260301000008_user_api_keys.sql [Applied]
2

Reset database (if needed)

If you encounter migration errors or want to start fresh:
npx supabase db reset
This deletes all local data and re-applies migrations. Only use this during development.

​
5. Start the Next.js Dev Server

1

Run the dev server

npm run dev
Expected output:
▲ Next.js 15.5.12
- Local:        http://localhost:3000
- Network:      http://192.168.1.x:3000

✓ Ready in 2.3s
2

Open the app

Navigate to http://localhost:3000 in your browser.
Press Cmd+K (Mac) or Ctrl+K (Windows/Linux) to open the search modal immediately.

​
Verify the Installation

1

Sign up with email/password

  1. Go to http://localhost:3000/auth/login
  2. Click Sign Up
  3. Enter an email and password
  4. Click Sign Up
2

Confirm your email (Mailpit)

Supabase Local uses Mailpit to capture auth emails:
  1. Open http://localhost:54324 in a new tab
  2. You’ll see a confirmation email from Supabase
  3. Click the confirmation link in the email body
  4. You’ll be redirected to the PromptRepo dashboard at http://localhost:3000
Mailpit is an email testing tool that captures all outbound emails from Supabase. It’s only available in local development.
3

Create a test prompt

  1. Click Create Prompt
  2. Fill in the form:
    • Title: Test Prompt
    • Content: Hello , welcome to PromptRepo!
  3. Click Create Prompt
You should see the prompt detail page with a variable resolution section.
4

Test search

Press Cmd+K and search for “test”. Your new prompt should appear in the results.

​
Common Issues

​
Docker Not Running

Symptom: npx supabase start fails with “Cannot connect to Docker daemon” Solution: Start Docker Desktop and wait for it to fully initialize, then retry npx supabase start.

​
Port Conflicts

Symptom: npx supabase start fails with “Port 54321 is already in use” Solution: Another service is using Supabase’s default ports. Stop the conflicting service or run: 
npx supabase stop
npx supabase start

​
Missing Environment Variables

Symptom: Next.js throws “Missing environment variable” errors Solution: Ensure .env.local exists in the project root with all required variables (see Step 3).

​
Migrations Not Applied

Symptom: Database tables don’t exist or queries fail Solution: Run npx supabase db reset to re-apply all migrations.

​
Next Steps

Now that PromptRepo is running locally, you can:

Quickstart

Create your first prompt with dynamic variables

Architecture

Learn about the two-table versioning pattern and data model

MCP Server

Connect Claude Desktop or other AI agents to your local instance

Testing

Run the test suite with Vitest

​
Development Workflow

​
Running Tests

npm test           # Run all tests
npm run test:ui    # Open Vitest UI

​
Linting

npm run lint

​
Building for Production

npm run build
The production build runs type checking, linting, and creates an optimized bundle. Fix any errors before deploying.

​
Stopping Local Services

When you’re done developing: 
# Stop Supabase (keeps data)
npx supabase stop

# Stop Supabase and delete data
npx supabase stop --no-backup
The Next.js dev server stops automatically when you close the terminal or press Ctrl+C.
Use npx supabase status to check which services are running and their URLs.

Build docs developers (and LLMs) love

Get started for freeTalk to us