env-vars

Environment Variables (Astro Way): Astro provides type-safe environment variables. Follow these steps:

**1. Define in astro.config.ts:**
```typescript
// astro.config.ts
env: {
  schema: {
    MY_ENV_VAR: envField.string({
      context: 'server',  // 'server' or 'client'
      access: 'secret',   // 'secret' or 'public'
      optional: false,    // true if the variable is optional
    }),
    PUBLIC_API_URL: envField.string({
      context: 'client',
      access: 'public',
      optional: false,
    }),
  },
},
```

**2. Import and use in your code:**
```typescript
// Server-side variables (access: 'secret', context: 'server')
import { DATABASE_URL, MAILGUN_WEBHOOK_SIGNING_KEY } from 'astro:env/server'

// Client-side variables (access: 'public', context: 'client')
import { LIVEKIT_API_KEY } from 'astro:env/client'
```

**Key guidelines:**
- **Server variables** (`context: 'server'`): Only accessible in server-side code, import from `astro:env/server`
- **Client variables** (`context: 'client'`): Accessible in both client and server code, import from `astro:env/client`
- **Secret variables** (`access: 'secret'`): Should never be exposed to the client
- **Public variables** (`access: 'public'`): Can be safely exposed to the client
- All environment variables are type-safe and validated at build time
- Ignore linter errors on recently created env vars. Astro needs to rerun its dev server to update its internal types references first.

**Example usage:**
```typescript
// apps/web/src/server/db.ts
import { setupDb } from '@app/db'
import { DATABASE_URL } from 'astro:env/server'

export const db = setupDb({
  connectionString: DATABASE_URL,
})
```

Passing Environment Variables to tRPC: To make environment variables available in tRPC procedures, follow this pattern:

**1. Define the Env interface in context.ts:**
```typescript
// packages/api/src/context.ts
export interface Env {
  appEndpoint: string
  gcsProjectId: string
  ...
}

export interface Context {
  db: Kysely<DB>
  env: Env
  session: Session | null
  user: SelectableUser | null
}
```

**2. Pass environment variables in the tRPC handler:**
```typescript
// apps/web/src/pages/api/trpc/[trpc].ts
import { LIVEKIT_API_KEY } from 'astro:env/client'
import {
  GCS_BUCKET,
  GCS_CLIENT_EMAIL,
  GCS_PRIVATE_KEY,
  GCS_PROJECT_ID,
  GEMINI_API_KEY,
  LIVEKIT_API_SECRET,
  LIVEKIT_URL,
  PERPLEXITY_API_KEY,
} from 'astro:env/server'

async function createContext({ req }: CreateContextOptions): Promise<Context> {
  const env: Env = {
    appEndpoint: getAppEndpoint(req),
    gcsProjectId: GCS_PROJECT_ID,
   ...
  }

  return { db, session: session ?? null, env, user }
}
```

**3. Access environment variables in tRPC procedures:**
```typescript
// In any tRPC procedure
export const myProcedure = protectedProcedure
  .input(z.object({ /* ... */ }))
  .mutation(async ({ ctx, input }) => {
    // Access env vars through ctx.env
    const gcsProjectId = ctx.env.gcsProjectId
    // ... use the environment variables
  })
```

**Key guidelines for tRPC env vars:**
- Always define new env vars in the `Env` interface in `context.ts`
- Import env vars from Astro's env system in the tRPC handler
- Map them to the `env` object in `createContext`
- Access them via `ctx.env` in any tRPC procedure
- This ensures type safety and centralized env var management

Build and CI Configuration: When adding new environment variables, you must also update build and CI configuration files:

**1. Update turbo.json:**
Add new environment variables to the `env` array under the `build` task so Turborepo can properly cache builds:
```json
// turbo.json
{
  "tasks": {
    "build": {
      "outputs": ["dist/**"],
      "dependsOn": ["^build"],
      "env": [
        "DATABASE_URL",
        "AUTH_SECRET",
        "MY_NEW_ENV_VAR",   // Add your new env var here
        // ... other env vars
      ]
    }
  }
}
```