Cursor rule

1---
2description: How to add env vas or environmental variables to the app.
3globs: 
4alwaysApply: false
5---
6**Environment Variables (Astro Way)**: Astro provides type-safe environment variables. Follow these steps:
7 
8    **1. Define in astro.config.ts:**
9```typescript
10    // astro.config.ts
11    env: {
12      schema: {
13        MY_ENV_VAR: envField.string({
14          context: 'server',  // 'server' or 'client'
15          access: 'secret',   // 'secret' or 'public'
16          optional: false,    // true if the variable is optional
17        }),
18        PUBLIC_API_URL: envField.string({
19          context: 'client',
20          access: 'public',
21          optional: false,
22        }),
23      },
24    },
25```
26 
27    **2. Import and use in your code:**
28```typescript
29    // Server-side variables (access: 'secret', context: 'server')
30    import { DATABASE_URL, MAILGUN_WEBHOOK_SIGNING_KEY } from 'astro:env/server'
31    
32    // Client-side variables (access: 'public', context: 'client')
33    import { LIVEKIT_API_KEY } from 'astro:env/client'
34```
35 
36    **Key guidelines:**
37    - **Server variables** (`context: 'server'`): Only accessible in server-side code, import from `astro:env/server`
38    - **Client variables** (`context: 'client'`): Accessible in both client and server code, import from `astro:env/client`
39    - **Secret variables** (`access: 'secret'`): Should never be exposed to the client
40    - **Public variables** (`access: 'public'`): Can be safely exposed to the client
41    - All environment variables are type-safe and validated at build time
42    - Ignore linter errors on recently created env vars. Astro needs to rerun its dev server to update its internal types references first.
43 
44    **Example usage:**
45```typescript
46    // apps/web/src/server/db.ts
47    import { setupDb } from '@app/db'
48    import { DATABASE_URL } from 'astro:env/server'
49    
50    export const db = setupDb({
51      connectionString: DATABASE_URL,
52    })
53```
54    
55 
56**Passing Environment Variables to tRPC**: To make environment variables available in tRPC procedures, follow this pattern:
57 
58    **1. Define the Env interface in context.ts:**
59```typescript
60    // packages/api/src/context.ts
61    export interface Env {
62      appEndpoint: string
63      gcsProjectId: string
64      ...
65    }
66 
67    export interface Context {
68      db: Kysely<DB>
69      env: Env
70      session: Session | null
71      user: SelectableUser | null
72    }
73```
74 
75    **2. Pass environment variables in the tRPC handler:**
76```typescript
77    // apps/web/src/pages/api/trpc/[trpc].ts
78    import { LIVEKIT_API_KEY } from 'astro:env/client'
79    import {
80      GCS_BUCKET,
81      GCS_CLIENT_EMAIL,
82      GCS_PRIVATE_KEY,
83      GCS_PROJECT_ID,
84      GEMINI_API_KEY,
85      LIVEKIT_API_SECRET,
86      LIVEKIT_URL,
87      PERPLEXITY_API_KEY,
88    } from 'astro:env/server'
89 
90    async function createContext({ req }: CreateContextOptions): Promise<Context> {
91      const env: Env = {
92        appEndpoint: getAppEndpoint(req),
93        gcsProjectId: GCS_PROJECT_ID,
94       ...
95      }
96 
97      return { db, session: session ?? null, env, user }
98    }
99```
100 
101    **3. Access environment variables in tRPC procedures:**
102```typescript
103    // In any tRPC procedure
104    export const myProcedure = protectedProcedure
105      .input(z.object({ /* ... */ }))
106      .mutation(async ({ ctx, input }) => {
107        // Access env vars through ctx.env
108        const gcsProjectId = ctx.env.gcsProjectId
109        // ... use the environment variables
110      })
111```
112 
113    **Key guidelines for tRPC env vars:**
114    - Always define new env vars in the `Env` interface in `context.ts`
115    - Import env vars from Astro's env system in the tRPC handler
116    - Map them to the `env` object in `createContext`
117    - Access them via `ctx.env` in any tRPC procedure
118    - This ensures type safety and centralized env var management
119 
120**Build and CI Configuration**: When adding new environment variables, you must also update build and CI configuration files:
121 
122    **1. Update turbo.json:**
123    Add new environment variables to the `env` array under the `build` task so Turborepo can properly cache builds:
124```json
125    // turbo.json
126    {
127      "tasks": {
128        "build": {
129          "outputs": ["dist/**"],
130          "dependsOn": ["^build"],
131          "env": [
132            "DATABASE_URL",
133            "AUTH_SECRET",
134            "MY_NEW_ENV_VAR",   // Add your new env var here
135            // ... other env vars
136          ]
137        }
138      }
139    }
140```
141 
142    **2. Update GitHub Actions (if needed):**
143    If your environment variable needs to be available during CI/CD builds or tests, ensure it's properly configured in your GitHub Actions workflows. This may involve:
144    - Adding the env var to repository secrets (for sensitive values)
145    - Setting the env var in workflow files (for public values)
146    - Updating setup actions if they need access to the env var
147 
148    **Key guidelines for build/CI config:**
149    - **Always** add new env vars to `turbo.json` if they affect build output
150    - Only add sensitive env vars to GitHub repository secrets, never commit them to workflow files
151    - Test your builds locally with the new env vars before pushing
152    - Consider whether the env var is needed at build time vs runtime
153    - Document any new env vars in your project's README or deployment docs
154