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

[wobsoriano]

Description

This PR adds support for type-safe env variables in Astro.

While our integration continues to use import.meta.env and process.env internally, we now provide users the option to import Clerk environment variables in a type-safe way.

When enabled, users can import our built-in variables like so:

import { PUBLIC_CLERK_PUBLISHABLE_KEY } from "astro:env/client"
import { CLERK_SECRET_KEY } from "astro:env/server"

console.log(PUBLIC_CLERK_PUBLISHABLE_KEY)
console.log(CLERK_SECRET_KEY)

Resolves ECO-119

Checklist

• npm test runs as expected.
• npm run build runs as expected.
• (If applicable) JSDoc comments have been added or updated for any package exports
• (If applicable) Documentation has been updated

Type of change

• 🐛 Bug fix
• 🌟 New feature
• 🔨 Breaking change
• 📖 Refactoring / dependency upgrade / documentation
• other:

[changeset-bot]

🦋 Changeset detected

Latest commit: 8f9508b

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
@clerk/astro	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[vercel]

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name	Status	Preview	Comments	Updated (UTC)
clerk-js-sandbox	✅ Ready (Inspect)	Visit Preview	💬 Add feedback	Feb 10, 2025 4:32pm

[wobsoriano]

We need to update this to properly resolve imports from packages that use export maps (like astro/config)

[wobsoriano]

Since this is primarily for convenience and doesn't affect the core functionality of our integration, should we just enable it by default?

[LekoArts]

Yeah, since it's stable in Astro 5 I'd say let's enable it by default and change our docs/quickstart to use it 👍 I guess it's good to give the ability to turn it off in case someone want's to override it (assuming Astro doesn't merge the schema, dunno)

[wobsoriano]

!snapshot

[clerk-cookie]

Hey @wobsoriano - the snapshot version command generated the following package versions:

Package	Version
@clerk/astro	2.2.0-snapshot.v20250208004744
@clerk/backend	1.24.0-snapshot.v20250208004744
@clerk/chrome-extension	2.2.8-snapshot.v20250208004744
@clerk/clerk-js	5.52.2-snapshot.v20250208004744
@clerk/elements	0.22.21-snapshot.v20250208004744
@clerk/clerk-expo	2.7.6-snapshot.v20250208004744
@clerk/expo-passkeys	0.1.19-snapshot.v20250208004744
@clerk/express	1.3.47-snapshot.v20250208004744
@clerk/fastify	2.1.20-snapshot.v20250208004744
@clerk/localizations	3.10.5-snapshot.v20250208004744
@clerk/nextjs	6.11.2-snapshot.v20250208004744
@clerk/nuxt	1.1.3-snapshot.v20250208004744
@clerk/clerk-react	5.22.12-snapshot.v20250208004744
@clerk/react-router	1.0.7-snapshot.v20250208004744
@clerk/remix	4.4.23-snapshot.v20250208004744
@clerk/shared	2.21.0-snapshot.v20250208004744
@clerk/tanstack-start	0.9.5-snapshot.v20250208004744
@clerk/testing	1.4.21-snapshot.v20250208004744
@clerk/themes	2.2.17-snapshot.v20250208004744
@clerk/types	4.45.1-snapshot.v20250208004744
@clerk/ui	0.3.22-snapshot.v20250208004744
@clerk/vue	1.1.11-snapshot.v20250208004744

Tip: Use the snippet copy button below to quickly install the required packages.
@clerk/astro

npm i @clerk/astro@2.2.0-snapshot.v20250208004744 --save-exact

@clerk/backend

npm i @clerk/backend@1.24.0-snapshot.v20250208004744 --save-exact

@clerk/chrome-extension

npm i @clerk/chrome-extension@2.2.8-snapshot.v20250208004744 --save-exact

@clerk/clerk-js

npm i @clerk/clerk-js@5.52.2-snapshot.v20250208004744 --save-exact

@clerk/elements

npm i @clerk/elements@0.22.21-snapshot.v20250208004744 --save-exact

@clerk/clerk-expo

npm i @clerk/clerk-expo@2.7.6-snapshot.v20250208004744 --save-exact

@clerk/expo-passkeys

npm i @clerk/expo-passkeys@0.1.19-snapshot.v20250208004744 --save-exact

@clerk/express

npm i @clerk/express@1.3.47-snapshot.v20250208004744 --save-exact

@clerk/fastify

npm i @clerk/fastify@2.1.20-snapshot.v20250208004744 --save-exact

@clerk/localizations

npm i @clerk/localizations@3.10.5-snapshot.v20250208004744 --save-exact

@clerk/nextjs

npm i @clerk/nextjs@6.11.2-snapshot.v20250208004744 --save-exact

@clerk/nuxt

npm i @clerk/nuxt@1.1.3-snapshot.v20250208004744 --save-exact

@clerk/clerk-react

npm i @clerk/clerk-react@5.22.12-snapshot.v20250208004744 --save-exact

@clerk/react-router

npm i @clerk/react-router@1.0.7-snapshot.v20250208004744 --save-exact

@clerk/remix

npm i @clerk/remix@4.4.23-snapshot.v20250208004744 --save-exact

@clerk/shared

npm i @clerk/shared@2.21.0-snapshot.v20250208004744 --save-exact

@clerk/tanstack-start

npm i @clerk/tanstack-start@0.9.5-snapshot.v20250208004744 --save-exact

@clerk/testing

npm i @clerk/testing@1.4.21-snapshot.v20250208004744 --save-exact

@clerk/themes

npm i @clerk/themes@2.2.17-snapshot.v20250208004744 --save-exact

@clerk/types

npm i @clerk/types@4.45.1-snapshot.v20250208004744 --save-exact

@clerk/ui

npm i @clerk/ui@0.3.22-snapshot.v20250208004744 --save-exact

@clerk/vue

npm i @clerk/vue@1.1.11-snapshot.v20250208004744 --save-exact

[LekoArts]

Yeah, since it's stable in Astro 5 I'd say let's enable it by default and change our docs/quickstart to use it 👍 I guess it's good to give the ability to turn it off in case someone want's to override it (assuming Astro doesn't merge the schema, dunno)