Docs/Guides/Local Development

Local Development Setup

Get EdgeURL running locally for development and testing

Prerequisites

Before you begin, make sure you have the following installed:

Node.js

Version 18.17 or later. Download from nodejs.org

pnpm (recommended) or npm

pnpm is preferred for faster installs. Install via npm install -g pnpm

Git

For cloning the repository

Stripe CLI (optional)

Required for testing Stripe webhooks locally. Install from stripe.com/docs/stripe-cli

1. Clone and Install

Clone the repository

git clone https://github.com/zorath-llc/edgeurl.git cd edgeurl

Install dependencies

# Using pnpm (recommended) pnpm install # Or using npm npm install

2. Environment Setup

Copy the example environment file and fill in your values:

cp .env.example .env.local

At minimum, you need to configure:

Supabase: NEXT_PUBLIC_SUPABASE_URL, NEXT_PUBLIC_SUPABASE_ANON_KEY, SUPABASE_SERVICE_ROLE_KEY
Redis/KV: KV_REST_API_URL, KV_REST_API_TOKEN (Upstash)
Stripe: STRIPE_SECRET_KEY, NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY
Application: NEXT_PUBLIC_BASE_URL (http://localhost:3000), NEXT_PUBLIC_SHORT_DOMAIN
Security: CRON_SECRET, INTERNAL_API_SECRET (32+ characters each)
Email: RESEND_API_KEY, RESEND_FROM_EMAIL

See the full Environment Variables Guide for all available options.

3. Stripe Webhook Testing

To test Stripe webhooks locally, use the Stripe CLI to forward events to your dev server:

Login to Stripe CLI

stripe login

Forward webhooks to localhost

stripe listen --forward-to localhost:3000/api/webhooks/stripe

The CLI will output a webhook signing secret (starts with whsec_). Add this as STRIPE_WEBHOOK_SECRET_DEV in your .env.local file.

Trigger test events

# Trigger a specific event stripe trigger checkout.session.completed # Trigger a subscription event stripe trigger customer.subscription.created

4. Running the Dev Server

# Start the development server npm run dev # Or with pnpm pnpm dev

The app will be available at http://localhost:3000

Other useful scripts

npm run buildBuild for production

npm run lintRun ESLint

npm run testRun unit tests with Vitest

npm run test:e2eRun E2E tests with Playwright

npm run env:checkValidate environment variables with zorath-env

npm run setup:stripeSet up Stripe price IDs

Troubleshooting

Environment validation errors

Run npm run env:check to see which variables are missing or invalid. EdgeURL uses t3-oss/env-nextjs for strict validation with Zod schemas.

Supabase key contains newlines

If you copied keys from the Vercel dashboard, they may contain corrupted newline characters. Re-copy the key from the Supabase dashboard directly.

Stripe webhook events not received

Make sure the Stripe CLI is running and the webhook secret matches your .env.local file. Check that the forward URL matches your dev server port.

Next Steps

→ Environment Variables Reference → Testing Guide → Deployment Checklist