Environment Setup
Configure environment variables for your Dirstarter application
Dirstarter needs six core variables to start: NEXT_PUBLIC_SITE_URL, NEXT_PUBLIC_SITE_EMAIL, CRON_SECRET, DATABASE_URL, BETTER_AUTH_SECRET and BETTER_AUTH_URL. Every third-party service is optional. A service turns on when every variable in its group is set, and without it the app leaves that feature out instead of failing. This guide explains each variable and what happens when it is missing.
Setup
Create a .env file in the root directory of your project. You can copy the example file as a starting point:
cp .env.example .envNever commit your .env file to version control. It contains sensitive information that should be
kept private.
Environment Variables
Core Configuration
| Variable | Description |
|---|---|
NEXT_PUBLIC_SITE_URL | The public URL of your site (e.g., http://localhost:5173 for development) |
NEXT_PUBLIC_SITE_EMAIL | The contact email for your site |
Cron Jobs
Learn how to set up cron jobs in the Cron Jobs guide.
| Variable | Description |
|---|---|
CRON_SECRET | A random string that authenticates requests to the publishing cron endpoint |
Database
Learn how to set up a database in the Database Setup guide.
| Variable | Description |
|---|---|
DATABASE_URL | PostgreSQL database connection URL |
DATABASE_PUBLIC_URL (optional) | Public PostgreSQL connection URL, used during production builds on platforms where the internal URL is not accessible |
Authentication
Learn how to set up authentication in the Authentication guide.
| Variable | Description |
|---|---|
BETTER_AUTH_SECRET | A random string used to hash tokens and sign cookies |
BETTER_AUTH_URL | The URL of your site (same as NEXT_PUBLIC_SITE_URL) |
AUTH_GOOGLE_ID (optional) | Google OAuth client ID. Without it, the login form has no Google button |
AUTH_GOOGLE_SECRET (optional) | Google OAuth client secret |
Production needs at least one way to sign in: Resend for magic links, or a social provider such as Google. When both are missing, the production build and server stop with "Sign-in is not configured". Development always works, because it logs magic links to the terminal.
Redis
Learn how to set up Redis in the Rate Limiting guide.
| Variable | Description |
|---|---|
REDIS_URL (optional) | Redis connection URL (format: redis://[username:password@]host:port). Falls back to in-memory rate limiting if not set. |
Email Service
Learn how to set up an Resend email service in the Email guide.
Optional. Development always logs emails to the terminal instead of sending them. Without Resend, production does not send email.
| Variable | Description |
|---|---|
RESEND_API_KEY (optional) | API key for Resend email service |
RESEND_SENDER_EMAIL (optional) | Default sender email address |
Storage
Learn how to set up a S3 storage service in the Storage guide.
Optional. Without S3, favicons keep their external URL, screenshots are skipped and admin uploads are off.
| Variable | Description |
|---|---|
S3_BUCKET (optional) | Name of your S3 bucket |
S3_REGION (optional) | AWS region for your S3 bucket |
S3_ACCESS_KEY (optional) | AWS access key ID |
S3_SECRET_ACCESS_KEY (optional) | AWS secret access key |
S3_ENDPOINT (optional) | Custom S3 endpoint for S3-compatible providers |
S3_PUBLIC_URL (optional) | Public URL prefix for uploaded files |
Analytics
Learn how to set up an analytics service in the Analytics guide.
| Variable | Description |
|---|---|
NEXT_PUBLIC_HIGHSEAT_SITE (optional) | Highseat site id. No tracker loads without it |
HIGHSEAT_PATH (optional) | First-party proxy path. Set it for the build and at runtime |
HIGHSEAT_SECRET (optional) | Site secret, required with HIGHSEAT_PATH |
HIGHSEAT_API_KEY (optional) | Read-only API key for the admin visitors chart |
AI & Web Scraping
Learn how to set up AI and web scraping services in the Automation guide or use the Media guide.
| Variable | Description |
|---|---|
AI_GATEWAY_API_KEY (optional) | Vercel AI Gateway API key. AI features are disabled if not set. |
AI_CHAT_MODEL | AI model for content generation (default: anthropic/claude-sonnet-5.5) |
AI_COMPLETION_MODEL | AI model for completions (default: google/gemini-3.5-flash-lite) |
JINA_API_KEY (optional) | Jina API key for web scraping |
SCREENSHOTONE_ACCESS_KEY (optional) | ScreenshotOne API key. Screenshots also need S3. Without either, tools get no screenshot |
MCP Server
Learn how AI agents manage your directory in the MCP Servers guide. The public MCP server needs no variables.
| Variable | Description |
|---|---|
MCP_SECRET (optional) | Turns on the admin MCP server at /api/mcp. Agents send it as a bearer token. At least 32 characters |
Payments
Learn how to set up a payment service in the Payments guide.
Optional. Without Stripe, every submission is free: the tier cards, checkout, billing portal and webhook are off.
| Variable | Description |
|---|---|
STRIPE_SECRET_KEY (optional) | Stripe secret key |
STRIPE_WEBHOOK_SECRET (optional) | Stripe webhook signing secret |
Type-Safe Validation
Dirstarter uses the T3 Env package for type-safe environment variable validation. The validation is configured in env.ts and ensures that:
- The core environment variables are present
- Production has a way to sign in (Resend or a social provider)
- Variables have the correct type (string, number, etc.)
- URLs are properly formatted
- Email addresses are valid
- No empty strings are allowed (they're treated as undefined)
To skip validation during builds (useful for Docker), set SKIP_ENV_VALIDATION flag:
SKIP_ENV_VALIDATION=1 bun buildEnvironment-Specific Variables
Development Environment
For development, you can use local services or development credentials:
NEXT_PUBLIC_SITE_URL="http://localhost:5173"
BETTER_AUTH_URL="http://localhost:5173"Production Environment
For production, use secure, production-ready services, and set the variables of every service you want to turn on.
Verifying Your Environment
To verify that your environment variables are correctly set up, run:
npm run devIf everything is configured correctly, your application should start without any environment-related errors.
What's Next?
Now that your environment is set up, learn how to create your first directory entry in the First Steps guide.
Last updated on