Overview
Shipr uses environment variables for configuration. Copy.env.example to .env and configure the values:
Required Variables
These variables are required for core functionality.Site Configuration
Your production URL used for metadata, sitemap, canonical URLs, and OG images.Example:
https://shipr.devClerk Authentication
Clerk publishable key for client-side authentication.Example:
pk_test_...Find this in your Clerk Dashboard under API Keys.Clerk secret key for server-side authentication.Example:
sk_test_...Important: Keep this secret and never expose it to the client.Clerk JWT issuer domain for Convex authentication integration.Example:
https://caring-bear-12.clerk.accounts.devThis must also be configured in the Convex Dashboard under Authentication settings.Path to the sign-in page.
Path to the sign-up page.
Convex Database
Convex deployment URL for your backend.Example:
https://happy-cat-123.convex.cloudGet this from running npx convex dev or npx convex deploy.Vercel AI Gateway
Vercel AI Gateway key for the dashboard chat feature.Example:
vck_...Create this in your Vercel Dashboard under AI Gateway settings.Email (Resend)
Sender email address for transactional emails.Example:
[email protected]Must be a verified domain in Resend. The default only works in sandbox mode.AI Chat Configuration
These variables configure the AI chat assistant in/dashboard/chat.
Model Settings
The AI model to use for chat responses.Example:
openai/gpt-4.1-mini or anthropic/claude-3-5-sonnet-20241022System prompt that defines the AI assistant’s behavior and personality.
Comma-separated list of enabled tool names for the chat assistant.Available tools:
getCurrentDateTime- Get current date and timecalculate- Perform calculations
Maximum number of model steps or tool calls per response.Prevents infinite loops and controls costs.
Rate Limiting
Maximum number of chat requests allowed per rate limit window.
Rate limit window duration in milliseconds.Default:
60000 (1 minute)Lifetime Message Limits
Enable or disable lifetime per-user message caps.Set to
false to allow unlimited messages per user.Total message cap per user when enforcement is enabled.Useful for preventing abuse in boilerplate demos. Increase for production.
Chat History
Enable or disable Convex chat history persistence.Set to
false to disable saving chat messages to the database.Maximum character length per persisted chat message.Messages longer than this will be truncated before storage.
Maximum number of persisted messages per chat thread.Older messages are removed when this limit is exceeded.
Maximum number of chat threads per user.Oldest threads are removed when this limit is exceeded.
Maximum character length for auto-generated chat thread titles.
Maximum number of persisted messages returned to the chat UI.Controls how much history is loaded in the chat interface.
File Upload Configuration
Maximum number of image uploads allowed per user in each rate limit window.Set to
0 to disable rate limiting.Image upload rate limit window duration in milliseconds.Default:
60000 (1 minute)Set to 0 to disable rate limiting.Optional Services
These services enhance your application but are not required for core functionality.PostHog Analytics
PostHog ingest host URL.Example:
https://us.i.posthog.comShipr uses a reverse proxy via Next.js rewrites to bypass ad blockers (configured in next.config.ts).Sentry Error Tracking
Sentry authentication token for uploading source maps during build.Example:
sntrys_...Create this in your Sentry account settings.Sentry DSN for error reporting to your Sentry project.Example:
https://[email protected]/...Source maps are automatically uploaded during build via @sentry/nextjs. Error tracking helpers are available in src/lib/sentry.ts.Environment-Specific Configuration
Development
For local development:- Use Clerk test keys (
pk_test_...,sk_test_...) - Run
npx convex devto get a development Convex URL - Use Resend sandbox sender (
[email protected]) - Set
NEXT_PUBLIC_SITE_URLtohttp://localhost:3000
Production
For production deployment:- Use Clerk production keys
- Run
npx convex deployto get a production Convex URL - Use a verified domain for
RESEND_FROM_EMAIL - Set
NEXT_PUBLIC_SITE_URLto your actual domain - Review and adjust all rate limits and message caps
- Configure optional services (PostHog, Sentry) for monitoring
Security Best Practices
- Never commit
.envfiles - they contain secrets - Use different keys for development and production
- Rotate API keys regularly
- Store secrets in Vercel environment variables, not in your repository
- Limit API key permissions to only what’s needed
- Monitor usage of paid services (AI Gateway, Resend) to prevent abuse