Skip to content

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

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
robskinney wants to merge 1 commit into
base: main
Choose a base branch
from
+51 −12
Open

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

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
25 changes: 25 additions & 0 deletions .env.example
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,25 @@
## Database
DATABASE_URL=postgresql://user:password@localhost:5432/workflow_builder

## Better Auth
BETTER_AUTH_SECRET=your-secret-key # Generate with: openssl rand -base64 32
BETTER_AUTH_URL=http://localhost:3000

# GitHub
GITHUB_CLIENT_ID=
GITHUB_CLIENT_SECRET=
NEXT_PUBLIC_GITHUB_CLIENT_ID=

# Google
GOOGLE_CLIENT_ID=
GOOGLE_CLIENT_SECRET=
NEXT_PUBLIC_GOOGLE_CLIENT_ID=

## AI Gateway (for AI workflow generation)
AI_GATEWAY_API_KEY=your-openai-api-key

## API URL (for application Route Handlers)
NEXT_PUBLIC_API_URL=http://localhost:3000

## Credentials Encryption
INTEGRATION_ENCRYPTION_KEY=your-32-byte-hexadecimal-key # Generate with: openssl rand -hex 32
Copy link
Contributor

@vercel vercel bot Nov 29, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

2 changes: 1 addition & 1 deletion .gitignore
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -33,13 +33,13 @@ yarn-error.log*

# env files (can opt-in for committing if needed)
.env*
!.env.example

# vercel
.vercel

# typescript
*.tsbuildinfo
next-env.d.ts
.env*.local

tmp/
26 changes: 17 additions & 9 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -68,16 +68,20 @@ Required variables for development:

```bash
# Database
DATABASE_URL=postgres://localhost:5432/workflow
DATABASE_URL=postgresql://user:password@localhost:5432/workflow_builder

# Authentication
BETTER_AUTH_SECRET=your-auth-secret-here # Generate with: openssl rand -base64 32
# Better Auth
BETTER_AUTH_SECRET=your-secret-key # Generate with: openssl rand -base64 32
BETTER_AUTH_URL=http://localhost:3000

# Credentials Encryption
INTEGRATION_ENCRYPTION_KEY=your-64-character-hex-string # Generate with: openssl rand -hex 32
# AI Gateway (for AI workflow generation)
AI_GATEWAY_API_KEY=your-openai-api-key

# API URL (for application Route Handlers)
NEXT_PUBLIC_API_URL=http://localhost:3000

# App URLs
NEXT_PUBLIC_APP_URL=http://localhost:3000
# Credentials Encryption
INTEGRATION_ENCRYPTION_KEY=your-32-byte-hexadecimal-key # Generate with: openssl rand -hex 32
```

Optional OAuth providers (configure at least one for authentication):
Expand Down Expand Up @@ -384,7 +388,9 @@ export type SendMessageInput = StepInput & {
/**
* Send message logic - separated for clarity and testability
*/
async function sendMessage(input: SendMessageInput): Promise<SendMessageResult> {
async function sendMessage(
input: SendMessageInput
): Promise<SendMessageResult> {
const credentials = input.integrationId
? await fetchCredentials(input.integrationId)
: {};
Expand Down Expand Up @@ -788,7 +794,9 @@ import "server-only";

import { type StepInput, withStepLogging } from "@/lib/steps/step-handler";

type MyResult = { success: true; data: string } | { success: false; error: string };
type MyResult =
| { success: true; data: string }
| { success: false; error: string };

export type MyInput = StepInput & {
field1: string;
Expand Down
10 changes: 8 additions & 2 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -38,18 +38,24 @@ You can deploy your own version of the workflow builder to Vercel with one click

### Environment Variables

Create a `.env.local` file with the following:
Create a `.env.local` file (or rename the existing `.env.example` file) with the following:

```env
# Database
DATABASE_URL=postgresql://user:password@localhost:5432/workflow_builder

# Better Auth
BETTER_AUTH_SECRET=your-secret-key
BETTER_AUTH_SECRET=your-secret-key # Generate with: openssl rand -base64 32
BETTER_AUTH_URL=http://localhost:3000

# AI Gateway (for AI workflow generation)
AI_GATEWAY_API_KEY=your-openai-api-key

# API URL (for application Route Handlers)
NEXT_PUBLIC_API_URL=http://localhost:3000

# Credentials Encryption
INTEGRATION_ENCRYPTION_KEY=your-32-byte-hexadecimal-key # Generate with: openssl rand -hex 32
```

### Installation
Expand Down