0
Fork 0
mirror of https://github.com/TanStack/router.git synced 2026-11-16 19:38:07 +00:00
router/docs/start/framework/react/guide/environment-variables.md
Tanner Linsley 3526194849
docs(skills): address 8 agent failure modes from user feedback (#7314)
* docs(skills): address 8 agent failure modes from external feedback

Adds new start-core/auth-server-primitives skill (sessions, cookies,
OAuth+PKCE, password-reset enumeration defense, CSRF, rate limiting,
session rotation) and updates 8 existing skills + matching docs to fix
patterns where agents produce insecure or wrong-framework output.

Skill changes:
- new: start-core/auth-server-primitives (server half of auth)
- router-core/auth-and-guards: route guard != RPC guard
- start-core/server-functions: wrong import path, RPC auth required,
  Cache-Control public is a cross-tenant leak, wrong-framework patterns
- start-core/middleware: wrong import path, sendContext shape vs access
  (3-layer wrong/still-wrong/correct), authMiddleware framing
- start-core/execution-model: file markers (server-only/client-only),
  module-level process.env is undefined under Worker SSR
- start-core/deployment: cloudflare env-at-request-time
- router-core/ssr: wrong file structures (next.js, react-router-dom)
- router-core/type-safety: wrong-framework imports + structures

Docs updated to mirror each skill change so source-of-truth and the
intent-indexed skill stay in sync. New authentication-server-primitives
guide is the long-form companion to the new skill.

intent validate: 30 skill files pass (was 29).

* ci: apply automated fixes

* docs(skills): address coderabbit review feedback

- Fix internal docs links to use correct relative paths instead of an
  absolute /start/latest/... URL and missing one ../ segment
- Remove blank line inside auth-and-guards blockquote (markdownlint MD028)
- Restore overload pattern in type-safety ValidateNavigateOptions and
  ValidateRedirectOptions examples; the casts I had introduced stripped
  generic context and contradicted the skill's own no-cast rule
- Add db.sessions.revokeAllForUser before create in login rotation
  snippets so the example matches the prose
- Soften useServerFn guidance: it's required only when the server
  function throws redirect/notFound; plain-data calls work directly and
  via useMutation/useQuery

* ci: apply automated fixes

* docs(skills): compress type-safety to stay under 500-line cap

Prettier's autofix expanded my single-line overload signatures across
multiple lines, pushing the file over the 500-line limit. Drop the
redundant fetchOrRedirect example (same pattern as useDelayedNavigate)
and describe ValidateRedirectOptions usage in prose instead.

* docs(skills): CSRF origin check should compare full origin, not host alone

Comparing only new URL(origin).host against APP_HOST silently accepts a
mismatched scheme — http://example.com would pass a check meant for
https://example.com. Compare the full origin (scheme + host + port)
against APP_ORIGIN instead. Same fix in skill and docs.

* docs(skills): make useDelayedNavigate callback truly return void

The callback returned the result of setTimeout (a timer handle), not
void as the public overload's return type implied. Wrap in a block so
the example matches the declared return type.

Skipped the related nitpick to add a separate redirect example — the
existing prose already describes the same overload pattern, and a
duplicate example would push the file close to the 500-line cap that
prettier autofix has been bumping us against.

* docs(skills): fix two real bugs in auth-server-primitives examples

1. Cookie parser truncated values containing '='. Signed cookies, JWTs,
   and base64-padded values all use '='. Use indexOf to split on the
   FIRST '=' only.

2. Login example short-circuited verifyPasswordHash on user-not-found,
   contradicting the prose's "same time, same error" claim — the
   no-user branch returned instantly while wrong-password spent ~100ms
   hashing, leaking account existence over the wire. Always verify
   against a hash; use a precomputed DUMMY_PASSWORD_HASH when the user
   is missing, then combine with the user-exists bit for the final ok.

Same fixes in the SKILL.md and the docs companion.

* docs(skills): address manuel's review on react-specific guides

- middleware.md, server-functions.md: drop cross-framework <framework>
  placeholders; this is the React-specific guide, just say
  @tanstack/react-start
- execution-model.md: drop the same trailing line about solid-start /
  vue-start paths
- hosting.md: remove the Cloudflare env-handling subsection — the
  general per-request rule lives in environment-variables.md and
  doesn't need to be repeated under a specific host
- environment-variables.md: mention the cloudflare:workers env binding
  as the canonical Cloudflare way to read env (including module scope),
  per Manuel's link to the Cloudflare docs
- deployment skill: same upgrade — show the cloudflare:workers env
  pattern alongside the per-request handler approach

* docs(skills): drop redundant server-only marker in session example

The file already imports from @tanstack/react-start/server, which is
on import protection's default client-deny specifier list. The
side-effect marker is redundant — drop it. Same fix in skill and docs.

* docs(skills): drop wrong-import-path mistakes — TS already catches them

Manuel pointed out that TypeScript catches both common wrong paths:
'@tanstack/react-router' has no exported member createServerFn /
createMiddleware, and '@tanstack/start' is "Cannot find module". Skill
space is precious; the items don't earn their slot if tsc handles them.

Removed:
- Common Mistake "Wrong import path" from server-functions and
  middleware skills (renumbered the remaining mistakes)
- The matching top-of-file CRITICAL line in both skills
- The "Import path" callouts in the middleware and server-functions
  docs

---------

Co-authored-by: autofix-ci[bot] <114827586+autofix-ci[bot]@users.noreply.github.com>
2026-05-02 23:11:30 -06:00

16 KiB

id title
environment-variables Environment Variables

Learn how to securely configure and use environment variables in your TanStack Start application across different contexts (server functions, client code, and build processes).

Read env per-request, not at module scope. On Cloudflare Workers and other edge SSR runtimes, env vars are injected at request time — module-level process.env.X reads run before the env exists and evaluate to undefined even on the server. Always read process.env inside .handler(), middleware .server(), server-route handlers, or other per-request callbacks. Reading at module scope also risks inlining secrets into the client bundle. (On Cloudflare Workers specifically, the canonical way to read env from anywhere — including module scope — is the cloudflare:workers env binding.)

Quick Start

TanStack Start automatically loads .env files and makes variables available in both server and client contexts with proper security boundaries.

# .env
DATABASE_URL=postgresql://user:pass@localhost:5432/mydb
VITE_APP_NAME=My TanStack Start App
// Server function - can access any environment variable
const getUser = createServerFn().handler(async () => {
  const db = await connect(process.env.DATABASE_URL) // ✅ Server-only
  return db.user.findFirst()
})

// Client component - only VITE_ prefixed variables
export function AppHeader() {
  return <h1>{import.meta.env.VITE_APP_NAME}</h1> // ✅ Client-safe
}

Environment Variable Contexts

Server-Side Context (Server Functions & API Routes)

Server functions can access any environment variable using process.env:

import { createServerFn } from '@tanstack/react-start'

// Database connection (server-only)
const connectToDatabase = createServerFn().handler(async () => {
  const connectionString = process.env.DATABASE_URL // No prefix needed
  const apiKey = process.env.EXTERNAL_API_SECRET // Stays on server

  // These variables are never exposed to the client
  return await database.connect(connectionString)
})

// Authentication (server-only)
const authenticateUser = createServerFn()
  .inputValidator(z.object({ token: z.string() }))
  .handler(async ({ data }) => {
    const jwtSecret = process.env.JWT_SECRET // Server-only
    return jwt.verify(data.token, jwtSecret)
  })

Client-Side Context (Components & Client Code)

Client code can only access variables with the VITE_ prefix:

// Client configuration
export function ApiProvider({ children }: { children: React.ReactNode }) {
  const apiUrl = import.meta.env.VITE_API_URL     // ✅ Public
  const apiKey = import.meta.env.VITE_PUBLIC_KEY  // ✅ Public

  // This would be undefined (security feature):
  // const secret = import.meta.env.DATABASE_URL   // ❌ Undefined

  return (
    <ApiContext.Provider value={{ apiUrl, apiKey }}>
      {children}
    </ApiContext.Provider>
  )
}

// Feature flags
export function FeatureGatedComponent() {
  const enableNewFeature = import.meta.env.VITE_ENABLE_NEW_FEATURE === 'true'

  if (!enableNewFeature) return null

  return <NewFeature />
}

Environment File Setup

File Hierarchy (Loaded in Order)

TanStack Start automatically loads environment files in this order:

.env.local          # Local overrides (add to .gitignore)
.env.production     # Production-specific variables
.env.development    # Development-specific variables
.env                # Default variables (commit to git)

Example Setup

.env (committed to repository):

# Public configuration
VITE_APP_NAME=My TanStack Start App
VITE_API_URL=https://api.example.com
VITE_SENTRY_DSN=https://...

# Server configuration templates
DATABASE_URL=postgresql://localhost:5432/myapp_dev
REDIS_URL=redis://localhost:6379

.env.local (add to .gitignore):

# Override for local development
DATABASE_URL=postgresql://user:password@localhost:5432/myapp_local
STRIPE_SECRET_KEY=sk_test_...
JWT_SECRET=your-local-secret

.env.production:

# Production overrides
VITE_API_URL=https://api.myapp.com
DATABASE_POOL_SIZE=20

Common Patterns

Database Configuration

// src/lib/database.ts
import { createServerFn } from '@tanstack/react-start'

const getDatabaseConnection = createServerFn().handler(async () => {
  const config = {
    url: process.env.DATABASE_URL,
    maxConnections: parseInt(process.env.DB_MAX_CONNECTIONS || '10'),
    ssl: process.env.NODE_ENV === 'production',
  }

  return createConnection(config)
})

Authentication Provider Setup

// src/lib/auth.ts (Server)
export const authConfig = {
  secret: process.env.AUTH_SECRET,
  providers: {
    auth0: {
      domain: process.env.AUTH0_DOMAIN,
      clientId: process.env.AUTH0_CLIENT_ID,
      clientSecret: process.env.AUTH0_CLIENT_SECRET, // Server-only
    }
  }
}

// src/components/AuthProvider.tsx (Client)
export function AuthProvider({ children }: { children: React.ReactNode }) {
  return (
    <Auth0Provider
      domain={import.meta.env.VITE_AUTH0_DOMAIN}
      clientId={import.meta.env.VITE_AUTH0_CLIENT_ID}
      // No client secret here - it stays on the server
    >
      {children}
    </Auth0Provider>
  )
}

External API Integration

// src/lib/external-api.ts
import { createServerFn } from '@tanstack/react-start'

// Server-side API calls (can use secret keys)
const fetchUserData = createServerFn()
  .inputValidator(z.object({ userId: z.string() }))
  .handler(async ({ data }) => {
    const response = await fetch(
      `${process.env.EXTERNAL_API_URL}/users/${data.userId}`,
      {
        headers: {
          Authorization: `Bearer ${process.env.EXTERNAL_API_SECRET}`,
          'Content-Type': 'application/json',
        },
      },
    )

    return response.json()
  })

// Client-side API calls (public endpoints only)
export function usePublicData() {
  const apiUrl = import.meta.env.VITE_PUBLIC_API_URL

  return useQuery({
    queryKey: ['public-data'],
    queryFn: () => fetch(`${apiUrl}/public/stats`).then((r) => r.json()),
  })
}

Feature Flags and Configuration

// src/config/features.ts
export const featureFlags = {
  enableNewDashboard: import.meta.env.VITE_ENABLE_NEW_DASHBOARD === 'true',
  enableAnalytics: import.meta.env.VITE_ENABLE_ANALYTICS === 'true',
  debugMode: import.meta.env.VITE_DEBUG_MODE === 'true',
}

// Usage in components
export function Dashboard() {
  if (featureFlags.enableNewDashboard) {
    return <NewDashboard />
  }

  return <LegacyDashboard />
}

Type Safety

TypeScript Declarations

Create src/env.d.ts to add type safety:

/// <reference types="vite/client" />

interface ImportMetaEnv {
  // Client-side environment variables
  readonly VITE_APP_NAME: string
  readonly VITE_API_URL: string
  readonly VITE_AUTH0_DOMAIN: string
  readonly VITE_AUTH0_CLIENT_ID: string
  readonly VITE_SENTRY_DSN?: string
  readonly VITE_ENABLE_NEW_DASHBOARD?: string
}

interface ImportMeta {
  readonly env: ImportMetaEnv
}

// Server-side environment variables
declare global {
  namespace NodeJS {
    interface ProcessEnv {
      readonly DATABASE_URL: string
      readonly REDIS_URL: string
      readonly JWT_SECRET: string
      readonly AUTH0_CLIENT_SECRET: string
      readonly STRIPE_SECRET_KEY: string
      readonly NODE_ENV: 'development' | 'production' | 'test'
    }
  }
}

export {}

Runtime Validation

Use Zod for runtime validation of environment variables:

// src/config/env.ts
import { z } from 'zod'

const envSchema = z.object({
  DATABASE_URL: z.string().url(),
  JWT_SECRET: z.string().min(32),
  NODE_ENV: z.enum(['development', 'production', 'test']),
})

const clientEnvSchema = z.object({
  VITE_APP_NAME: z.string(),
  VITE_API_URL: z.string().url(),
  VITE_AUTH0_DOMAIN: z.string(),
  VITE_AUTH0_CLIENT_ID: z.string(),
})

// Validate server environment
// NOTE: Module-level parse runs at module load. Fine for Node.js;
// on Cloudflare Workers (and other edge runtimes) `process.env` is
// empty at module load, so wrap this in a function and call it
// inside `.handler()` instead:
//
//   export const getServerEnv = () => envSchema.parse(process.env)
//
// Then read `getServerEnv()` per-request from server functions/middleware.
export const serverEnv = envSchema.parse(process.env)

// Validate client environment (build-time, always safe)
export const clientEnv = clientEnvSchema.parse(import.meta.env)

Security Best Practices

1. Never Expose Secrets to Client

// ❌ WRONG - Secret exposed to client bundle
const config = {
  apiKey: import.meta.env.VITE_SECRET_API_KEY, // This will be in your JS bundle!
}

// ✅ CORRECT - Keep secrets on server
const getApiData = createServerFn().handler(async () => {
  const response = await fetch(apiUrl, {
    headers: { Authorization: `Bearer ${process.env.SECRET_API_KEY}` },
  })
  return response.json()
})

2. Use Appropriate Prefixes

# ✅ Server-only (no prefix)
DATABASE_URL=postgresql://...
JWT_SECRET=super-secret-key
STRIPE_SECRET_KEY=sk_live_...

# ✅ Client-safe (VITE_ prefix)
VITE_APP_NAME=My App
VITE_API_URL=https://api.example.com
VITE_SENTRY_DSN=https://...

3. Validate Required Variables

// src/config/validation.ts
const requiredServerEnv = ['DATABASE_URL', 'JWT_SECRET'] as const

const requiredClientEnv = ['VITE_APP_NAME', 'VITE_API_URL'] as const

// Validate on server startup
for (const key of requiredServerEnv) {
  if (!process.env[key]) {
    throw new Error(`Missing required environment variable: ${key}`)
  }
}

// Validate client environment at build time
for (const key of requiredClientEnv) {
  if (!import.meta.env[key]) {
    throw new Error(`Missing required environment variable: ${key}`)
  }
}

Production Checklist

  • All sensitive variables are server-only (no VITE_ prefix)
  • Client variables use VITE_ prefix
  • .env.local is in .gitignore
  • Production environment variables are configured on hosting platform
  • Required environment variables are validated at startup
  • No hardcoded secrets in source code
  • Database URLs use connection pooling in production
  • API keys are rotated regularly

Common Problems

Environment Variable is Undefined

Problem: import.meta.env.MY_VARIABLE returns undefined

Solutions:

  1. Add correct prefix: Use VITE_ prefix (e.g. VITE_MY_VARIABLE)
  2. Restart development server after adding new variables
  3. Check file location: .env file must be in project root
  4. Verify bundler configuration: Ensure variables are properly injected

Example:

# ❌ Won't work in client code
API_KEY=abc123

# ✅ Works in client code
VITE_API_KEY=abc123

# ❌ Won't bundle the variable (assuming it is not set in the environment of the build)
npm run build

# ✅ Works in client code and will bundle the variable for production
VITE_API_KEY=abc123 npm run build

Runtime Client Environment Variables in Production

Problem: If VITE_ variables are replaced at bundle time only, how to make runtime variables available on the client?

Solutions:

Pass variables from the server down to the client:

const getRuntimeVar = createServerFn({ method: 'GET' }).handler(() => {
  return process.env.MY_RUNTIME_VAR // notice `process.env` on the server, and no `VITE_` prefix
})

export const Route = createFileRoute('/')({
  loader: async () => {
    const foo = await getRuntimeVar()
    return { foo }
  },
  component: RouteComponent,
})

function RouteComponent() {
  const { foo } = Route.useLoaderData()
  // ... use your variable however you want
}

Variable Not Updating

Problem: Environment variable changes aren't reflected

Solutions:

  1. Restart development server
  2. Check if you're modifying the correct .env file
  3. Verify file hierarchy (.env.local overrides .env)

TypeScript Errors

Problem: Property 'VITE_MY_VAR' does not exist on type 'ImportMetaEnv'

Solution: Add to src/env.d.ts:

interface ImportMetaEnv {
  readonly VITE_MY_VAR: string
}

Security: Secret Exposed to Client

Problem: Sensitive data appearing in client bundle

Solutions:

  1. Remove VITE_ prefix from sensitive variables
  2. Move sensitive operations to server functions
  3. Use build tools to verify no secrets in client bundle

Build Errors in Production

Problem: Missing environment variables in production build

Solutions:

  1. Configure variables on hosting platform
  2. Validate required variables at build time
  3. Use deployment-specific .env files

Server Build Configuration

Static NODE_ENV Replacement

By default, TanStack Start statically replaces process.env.NODE_ENV in server builds at build time. This enables dead code elimination (tree-shaking) for development-only code paths in your server bundle.

Why this matters: Vite automatically replaces process.env.NODE_ENV in client builds, but server builds run in Node.js where process.env is a real runtime object. Without static replacement, code like this would remain in your production server bundle:

if (process.env.NODE_ENV === 'development') {
  // This code would NOT be eliminated without static replacement
  enableDevTools()
  logDebugInfo()
}

With static replacement enabled (the default), the bundler sees "production" === 'development' and eliminates the entire block.

Configuring Static Replacement

The replacement is controlled by the server.build.staticNodeEnv option:

// vite.config.ts
import { defineConfig } from 'vite'
import { tanstackStart } from '@tanstack/react-start/plugin/vite'
import viteReact from '@vitejs/plugin-react'

export default defineConfig({
  plugins: [
    tanstackStart({
      server: {
        build: {
          // Replace process.env.NODE_ENV at build time (default: true)
          staticNodeEnv: true,
        },
      },
    }),
    viteReact(),
  ],
})

The replacement value is determined in this order:

  1. process.env.NODE_ENV at build time (if set)
  2. Vite's mode (e.g., from --mode staging)
  3. "production" (fallback)

When to Disable Static Replacement

Set staticNodeEnv: false if you need NODE_ENV to remain dynamic at runtime:

tanstackStart({
  server: {
    build: {
      staticNodeEnv: false, // Keep NODE_ENV dynamic at runtime
    },
  },
})

Common reasons to disable:

  • Same build, multiple environments: Deploying one build artifact to staging and production
  • Runtime environment detection: Code that must check the actual runtime environment
  • Testing production builds locally: Running production builds with NODE_ENV=development

Note: Disabling static replacement means development-only code paths will remain in your production bundle and be evaluated at runtime.

Important: If you disable staticNodeEnv, you must set NODE_ENV=production at runtime when running your server in production. Without this, React (and possibly other libraries) will run in development mode, which is significantly slower and includes extra warnings and checks not intended for production use.