|
| 1 | +# Environment Variables Configuration |
| 2 | + |
| 3 | +This document explains how to properly configure environment variables for the Local Catch application. |
| 4 | + |
| 5 | +## Important: No Quotes in .env Files |
| 6 | + |
| 7 | +When setting environment variables in `.env` files, **do NOT use quotes** around the values unless the quotes are part of the actual value. Vite will include quotes as part of the value if you add them. |
| 8 | + |
| 9 | +### ❌ Wrong (with quotes) |
| 10 | +```bash |
| 11 | +VITE_STACK_PROJECT_ID='a55799cf-aec1-4699-94ce-fb42094552d9' |
| 12 | +VITE_STACK_PUBLISHABLE_CLIENT_KEY='pck_cn8y47v9g8029134473btakf840y8feyar4jnkmjq2268' |
| 13 | +``` |
| 14 | + |
| 15 | +### ✅ Correct (without quotes) |
| 16 | +```bash |
| 17 | +VITE_STACK_PROJECT_ID=a55799cf-aec1-4699-94ce-fb42094552d9 |
| 18 | +VITE_STACK_PUBLISHABLE_CLIENT_KEY=pck_cn8y47v9g8029134473btakf840y8feyar4jnkmjq2268 |
| 19 | +``` |
| 20 | + |
| 21 | +## Vercel Environment Variables |
| 22 | + |
| 23 | +When adding environment variables to Vercel (either via dashboard or CLI), ensure they are added without quotes: |
| 24 | + |
| 25 | +```bash |
| 26 | +# Using printf to avoid quotes |
| 27 | +printf 'your-value-here' | vercel env add VARIABLE_NAME production |
| 28 | +``` |
| 29 | + |
| 30 | +## Required Environment Variables |
| 31 | + |
| 32 | +### Frontend (Vite) - Client-side |
| 33 | +These are bundled into the client code and exposed to the browser: |
| 34 | +- `VITE_STACK_PROJECT_ID` - Stack Auth project ID |
| 35 | +- `VITE_STACK_PUBLISHABLE_CLIENT_KEY` - Stack Auth public key |
| 36 | +- `VITE_API_URL` - API base URL (empty for production, http://localhost:3000 for dev) |
| 37 | + |
| 38 | +### Backend (Vercel Functions) - Server-side only |
| 39 | +These are only accessible on the server: |
| 40 | +- `STACK_PROJECT_ID` - Stack Auth project ID (server-side) |
| 41 | +- `STACK_SECRET_SERVER_KEY` - Stack Auth secret key (**NEVER expose to client**) |
| 42 | +- `JWT_SECRET` - Secret for signing JWT tokens |
| 43 | +- `DATABASE_URL` - PostgreSQL connection string |
| 44 | +- All `POSTGRES_*` and `PG*` variables from Neon |
| 45 | + |
| 46 | +## Common Issues |
| 47 | + |
| 48 | +### "Invalid project ID" Error |
| 49 | +If you see an error like "Invalid project ID: ... Project IDs must be UUIDs", this usually means: |
| 50 | +1. The environment variable has quotes around it |
| 51 | +2. The environment variable wasn't set correctly in Vercel |
| 52 | +3. The build needs to be redeployed after fixing the variables |
| 53 | + |
| 54 | +**Solution**: Remove quotes from all environment variables and redeploy. |
| 55 | + |
| 56 | +### Authentication 401 Errors |
| 57 | +If you get 401 Unauthorized errors when logged in with OAuth: |
| 58 | +1. Check that `VITE_STACK_PROJECT_ID` and `VITE_STACK_PUBLISHABLE_CLIENT_KEY` are set in Vercel |
| 59 | +2. Verify they don't have quotes around them |
| 60 | +3. Redeploy the application |
| 61 | + |
| 62 | +## Local Development Setup |
| 63 | + |
| 64 | +1. Copy `.env.example` to `.env.development`: |
| 65 | + ```bash |
| 66 | + cp app/.env.example app/.env.development |
| 67 | + ``` |
| 68 | + |
| 69 | +2. Fill in your values **without quotes**: |
| 70 | + ```bash |
| 71 | + VITE_API_URL=http://localhost:3000 |
| 72 | + VITE_STACK_PROJECT_ID=your-project-id-here |
| 73 | + VITE_STACK_PUBLISHABLE_CLIENT_KEY=your-key-here |
| 74 | + DATABASE_URL=your-connection-string-here |
| 75 | + ``` |
| 76 | + |
| 77 | +3. Never commit `.env`, `.env.development`, or `.env.production` files - they're gitignored for security. |
| 78 | + |
| 79 | +## Production Deployment |
| 80 | + |
| 81 | +Environment variables for production are managed in Vercel: |
| 82 | +1. Go to Vercel dashboard → Project Settings → Environment Variables |
| 83 | +2. Add variables without quotes |
| 84 | +3. Select appropriate environments (Production, Preview, Development) |
| 85 | +4. Redeploy to apply changes |
0 commit comments