fix: include a .env.example file, add clarification around required environment variables (fixes #74)

[robskinney]

This PR introduces the following changes:

• Updated .gitignore to allow .env.example files.
• Created a .env.example with all environment variables referenced throughout the project.
• Updated README.md with a snippet including the updated environment variable documentation (NEXT_PUBLIC_API_URL and INTEGRATION_ENCRYPTION_KEY)
• Updated CONTRIBUTING.md with additional available environment variables

[vercel]

@robskinney is attempting to deploy a commit to the Vercel Labs Team on Vercel.

A member of the Team first needs to authorize it.

[vercel]

Missing environment variable NEXT_PUBLIC_APP_URL which is used by the authentication fallback logic. The PR documentation updated variable names without updating the corresponding code.

View Details

📝 Patch Details

diff --git a/.env.example b/.env.example
index 0beb746..236e26b 100644
--- a/.env.example
+++ b/.env.example
@@ -21,5 +21,8 @@ AI_GATEWAY_API_KEY=your-openai-api-key
 ## API URL (for application Route Handlers)
 NEXT_PUBLIC_API_URL=http://localhost:3000
 
+## App URL (fallback for authentication base URL, alternative to BETTER_AUTH_URL)
+NEXT_PUBLIC_APP_URL=http://localhost:3000
+
 ## Credentials Encryption
 INTEGRATION_ENCRYPTION_KEY=your-32-byte-hexadecimal-key # Generate with: openssl rand -hex 32
\ No newline at end of file

Analysis

Missing environment variable documentation for NEXT_PUBLIC_APP_URL

What fails: Authentication fails in custom deployments (non-Vercel) when users follow only the documented environment variables. The getBaseURL() function in lib/auth.ts (lines 38-40) checks for NEXT_PUBLIC_APP_URL as a Priority 2 fallback for determining the authentication base URL, but this variable is not documented in .env.example, causing users to not set it.

How to reproduce:

1. Deploy to a custom hosting environment (not Vercel)
2. Follow documentation: set NEXT_PUBLIC_API_URL but skip undocumented NEXT_PUBLIC_APP_URL
3. Do not set BETTER_AUTH_URL (assuming only documented vars are needed)
4. Attempt authentication

Result: getBaseURL() falls through all documented priorities (no BETTER_AUTH_URL, no VERCEL_URL) and returns hardcoded http://localhost:3000 regardless of actual deployment URL, causing authentication endpoints to fail with CORS or connection errors.

Expected: NEXT_PUBLIC_APP_URL should be documented in .env.example (alongside NEXT_PUBLIC_API_URL) so users can properly configure the authentication base URL for custom deployments. The priority chain in lib/auth.ts is:

1. BETTER_AUTH_URL (Priority 1 - documented)
2. NEXT_PUBLIC_APP_URL (Priority 2 - was undocumented)
3. VERCEL_URL (Priority 3 - auto-set by Vercel)
4. http://localhost:3000 (Priority 4 - hardcoded fallback)

Fix: Added NEXT_PUBLIC_APP_URL to .env.example with documentation explaining it as a fallback/alternative to BETTER_AUTH_URL for scenarios requiring per-environment configuration outside of Vercel deployments.