feat(astro): Add support for type-safe environment variables (#5104)

Co-authored-by: Lennart <lekoarts@gmail.com>

Author: wobsoriano

.changeset/chilly-suns-beg.md

@@ -0,0 +1,20 @@
+---
+'@clerk/astro': minor
+---
+
+Add support for type-safe environment variables using the [`astro:env` API](https://docs.astro.build/en/reference/configuration-reference/#env).
+
+The integration now provides a type-safe schema for all Clerk environment variables by default. You can use the environment variables like so:
+
+```js
+import { PUBLIC_CLERK_PUBLISHABLE_KEY } from "astro:env/client"
+import { CLERK_SECRET_KEY } from "astro:env/server"
+```
+
+To override this behavior, you can disable the feature by setting `enableEnvSchema` to `false`:
+
+```js
+export default defineConfig({
+  integrations: [clerk({ enableEnvSchema: false })],
+})
+```

packages/astro/package.json

@@ -87,7 +87,9 @@
     "nanoid": "5.0.9",
     "nanostores": "0.11.3"
   },
-  "devDependencies": {},
+  "devDependencies": {
+    "astro": "^5.2.5"
+  },
   "peerDependencies": {
     "astro": "^4.15.0 || ^5.0.0"
   },

packages/astro/src/integration/create-integration.ts

@@ -1,5 +1,6 @@
 import type { ClerkOptions } from '@clerk/types';
 import type { AstroIntegration } from 'astro';
+import { envField } from 'astro/config';
 
 import { name as packageName, version as packageVersion } from '../../package.json';
 import type { AstroClerkIntegrationParams } from '../types';
@@ -13,11 +14,12 @@ type HotloadAstroClerkIntegrationParams = AstroClerkIntegrationParams & {
   clerkJSUrl?: string;
   clerkJSVariant?: 'headless' | '';
   clerkJSVersion?: string;
+  enableEnvSchema?: boolean;
 };
 
 function createIntegration<Params extends HotloadAstroClerkIntegrationParams>() {
   return (params?: Params): AstroIntegration => {
-    const { proxyUrl, isSatellite, domain, signInUrl, signUpUrl } = params || {};
+    const { proxyUrl, isSatellite, domain, signInUrl, signUpUrl, enableEnvSchema = true } = params || {};
 
     // These are not provided when the "bundled" integration is used
     const clerkJSUrl = (params as any)?.clerkJSUrl as string | undefined;
@@ -79,6 +81,11 @@ function createIntegration<Params extends HotloadAstroClerkIntegrationParams>()
                 target: 'es2022',
               },
             },
+            env: {
+              schema: {
+                ...(enableEnvSchema ? createClerkEnvSchema() : {}),
+              },
+            },
           });
 
           /**
@@ -158,4 +165,27 @@ function createIntegration<Params extends HotloadAstroClerkIntegrationParams>()
   };
 }
 
+function createClerkEnvSchema() {
+  return {
+    PUBLIC_CLERK_PUBLISHABLE_KEY: envField.string({ context: 'client', access: 'public' }),
+    PUBLIC_CLERK_SIGN_IN_URL: envField.string({ context: 'client', access: 'public', optional: true }),
+    PUBLIC_CLERK_SIGN_UP_URL: envField.string({ context: 'client', access: 'public', optional: true }),
+    PUBLIC_CLERK_IS_SATELLITE: envField.boolean({ context: 'client', access: 'public', optional: true }),
+    PUBLIC_CLERK_PROXY_URL: envField.string({ context: 'client', access: 'public', optional: true, url: true }),
+    PUBLIC_CLERK_DOMAIN: envField.string({ context: 'client', access: 'public', optional: true, url: true }),
+    PUBLIC_CLERK_JS_URL: envField.string({ context: 'client', access: 'public', optional: true, url: true }),
+    PUBLIC_CLERK_JS_VARIANT: envField.enum({
+      context: 'client',
+      access: 'public',
+      optional: true,
+      values: ['headless'],
+    }),
+    PUBLIC_CLERK_JS_VERSION: envField.string({ context: 'client', access: 'public', optional: true }),
+    PUBLIC_CLERK_TELEMETRY_DISABLED: envField.boolean({ context: 'client', access: 'public', optional: true }),
+    PUBLIC_CLERK_TELEMETRY_DEBUG: envField.boolean({ context: 'client', access: 'public', optional: true }),
+    CLERK_SECRET_KEY: envField.string({ context: 'server', access: 'secret' }),
+    CLERK_JWT_KEY: envField.string({ context: 'server', access: 'secret', optional: true }),
+  };
+}
+
 export { createIntegration };

packages/astro/tsconfig.json

@@ -9,7 +9,7 @@
     "forceConsistentCasingInFileNames": true,
     "inlineSources": false,
     "isolatedModules": true,
-    "moduleResolution": "node",
+    "moduleResolution": "Bundler",
     "noUnusedLocals": false,
     "noUnusedParameters": false,
     "preserveWatchOutput": true,
@@ -22,7 +22,8 @@
     "outDir": "dist",
     "resolveJsonModule": true,
     "declarationDir": "dist/types",
-    "noUncheckedIndexedAccess": true
+    "noUncheckedIndexedAccess": true,
+    "rootDir": "src"
   },
   "exclude": [
     "dist",