feat(astro): Add support for keyless mode by wobsoriano · Pull Request #7812 · clerk/javascript

wobsoriano · 2026-02-10T17:11:03Z

Description

Brings keyless mode support to @clerk/astro, removing the need for API keys during development setup.

Changes

Uses shared helpers from @clerk/shared/keyless
Originally tried to hook keyless logic inside the integration, but it had a UX issue where after adding the keys to .env, you'll have to hard reload the browser for keyless to pick it up. I went with runtime middleware instead, similar to react-router and tanstack start keyless implementation.

Data Flow

Server (Middleware):

resolveKeysWithKeylessFallback() - Checks for user keys, falls back to keyless service
keyless() service - Creates/retrieves accountless application, persists to .clerk/
Store resolved keys in context.locals (Astro's request-scoped storage)
decorateRequest() - Transform HTML response, inject <script id="__CLERK_ASTRO_SAFE_VARS__">

Client (Browser):

runInjectionScript() - Read config from DOM
mergeEnvVarsWithParams() - Merge with integration params
Pass to clerk.load() with keyless URLs for dev prompts

Checklist

pnpm test runs as expected.
pnpm 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

Summary by CodeRabbit

New Features
- Keyless authentication for Astro apps: development-time automatic key resolution, onboarding flow, and client exposure of claim/API-keys URLs.
Configuration
- New optional environment controls to enable/disable keyless flow and supply publishable/secret keys; publishable key can be injected at runtime.
Infrastructure
- Local file-backed key storage and a lazily initialized keyless service for development.
Tests
- Added integration tests validating the Astro keyless workflow and onboarding scenarios.
Chores
- Vite added as a development dependency.

changeset-bot · 2026-02-10T17:11:09Z

🦋 Changeset detected

Latest commit: 4547ca5

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 · 2026-02-10T17:11:10Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
clerk-js-sandbox	Ready	Preview, Comment	Feb 13, 2026 4:28pm

coderabbitai · 2026-02-10T17:22:43Z

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

@coderabbitai resume to resume automatic reviews.
@coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

▶️ Resume reviews
🔍 Trigger review

📝 Walkthrough

Walkthrough

Adds a keyless workflow to the Astro integration: a file-backed keyless service and runtime key resolution utilities with a development-time keyless fallback. Middleware performs per-request keyless resolution and stores keyless data in Astro locals; server/client env merging and get-safe-env prefer injected keyless publishable keys. Integration config/schema accept optional PUBLIC_CLERK_KEYLESS_CLAIM_URL, PUBLIC_CLERK_KEYLESS_API_KEYS_URL, and PUBLIC_CLERK_KEYLESS_DISABLED and make PUBLIC_CLERK_PUBLISHABLE_KEY and CLERK_SECRET_KEY optional. Exports canUseKeyless, adds Playwright tests for keyless flow, and updates Vite and tsup externals.

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 33.33% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title 'feat(astro): Add support for keyless mode' clearly and specifically describes the main change—adding keyless mode support to the Astro integration.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

coderabbitai · 2026-02-10T17:25:12Z

📝 Walkthrough

Walkthrough

This pull request introduces keyless mode support for the Astro framework. Changes include adding new environment configuration properties for keyless URLs and disabled flags, implementing keyless service initialization with file storage, creating utilities for resolving keys with a keyless fallback mechanism, integrating keyless resolution into the middleware for per-request handling, and adding feature flags to control keyless availability based on environment and filesystem support. A new end-to-end test suite validates the keyless workflow, and the build configuration externals list is updated to include vite.

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 33.33% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and specifically describes the main feature being introduced: keyless mode for the Astro integration. It accurately reflects the core purpose of the changeset across all modified files.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

No actionable comments were generated in the recent review. 🎉

Tip

Issue Planner is now in beta. Read the docs and try it out! Share your feedback on Discord.

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

coderabbitai

Actionable comments posted: 3

🤖 Fix all issues with AI agents

In `@packages/astro/package.json`:
- Around line 98-102: The lockfile is out of sync with package.json
devDependencies: add vite@^7.1.0; regenerate and commit the updated lockfile
(e.g., run your package manager's install to update lockfile so it includes the
new "vite" entry) and ensure the changed lockfile is included in the PR; verify
the lockfile now contains the vite@^7.1.0 entry corresponding to the
"devDependencies" section in package.json.

In `@packages/astro/src/env.d.ts`:
- Around line 24-25: The InternalEnv interface is missing definitions for
PUBLIC_CLERK_KEYLESS_CLAIM_URL and PUBLIC_CLERK_KEYLESS_API_KEYS_URL which are
referenced by getContextEnvVar in get-safe-env.ts; add both as readonly optional
string properties to the InternalEnv interface (e.g.,
PUBLIC_CLERK_KEYLESS_CLAIM_URL?: string and PUBLIC_CLERK_KEYLESS_API_KEYS_URL?:
string) so keyof InternalEnv matches the keys used and TypeScript compilation
succeeds.

In `@packages/astro/src/server/get-safe-env.ts`:
- Around line 42-43: The calls to getContextEnvVar with
PUBLIC_CLERK_KEYLESS_CLAIM_URL and PUBLIC_CLERK_KEYLESS_API_KEYS_URL fail
TypeScript because those keys are not declared on the InternalEnv type; update
env.d.ts to add these two keys (PUBLIC_CLERK_KEYLESS_CLAIM_URL and
PUBLIC_CLERK_KEYLESS_API_KEYS_URL) to the InternalEnv interface so
getContextEnvVar(...) compiles, ensuring the names and types match other
PUBLIC_* URL entries already defined.

packages/astro/package.json

coderabbitai · 2026-02-10T17:50:43Z

packages/astro/src/env.d.ts

+  readonly PUBLIC_CLERK_KEYLESS_DISABLED?: string;
 }


⚠️ Potential issue | 🔴 Critical

Missing type definitions for keyless URL environment variables.

The InternalEnv interface is missing PUBLIC_CLERK_KEYLESS_CLAIM_URL and PUBLIC_CLERK_KEYLESS_API_KEYS_URL. These are used in get-safe-env.ts (lines 42-43, 61-62) with getContextEnvVar(), which has a parameter typed as keyof InternalEnv. This will cause TypeScript compilation errors.

🐛 Proposed fix

readonly PUBLIC_CLERK_TELEMETRY_DEBUG?: string; readonly PUBLIC_CLERK_KEYLESS_DISABLED?: string; + readonly PUBLIC_CLERK_KEYLESS_CLAIM_URL?: string; + readonly PUBLIC_CLERK_KEYLESS_API_KEYS_URL?: string; }

🤖 Prompt for AI Agents

In `@packages/astro/src/env.d.ts` around lines 24 - 25, The InternalEnv interface is missing definitions for PUBLIC_CLERK_KEYLESS_CLAIM_URL and PUBLIC_CLERK_KEYLESS_API_KEYS_URL which are referenced by getContextEnvVar in get-safe-env.ts; add both as readonly optional string properties to the InternalEnv interface (e.g., PUBLIC_CLERK_KEYLESS_CLAIM_URL?: string and PUBLIC_CLERK_KEYLESS_API_KEYS_URL?: string) so keyof InternalEnv matches the keys used and TypeScript compilation succeeds.

packages/astro/src/server/get-safe-env.ts

The options parameter in clerkClient was not providing any value because getSafeEnv(context) already reads all necessary configuration from both process.env and context.locals (which includes keyless values set by middleware). Changes: 1. clerk-client.ts: - Remove optional options parameter from clerkClient signature - Keep createClerkClientWithOptions internal signature for potential future use - Client configuration fully driven by getSafeEnv(context) 2. keyless/index.ts: - Remove ClerkAstroMiddlewareOptions import (no longer needed) - Remove options parameter from keyless() function - Remove options from clerkClient() calls - Simplify function signature 3. keyless/utils.ts: - Remove ClerkAstroMiddlewareOptions import - Remove options parameter from resolveKeysWithKeylessFallback() - Update keyless() call to not pass options 4. clerk-middleware.ts: - Remove options parameter from resolveKeysWithKeylessFallback() call Why this is correct: - getSafeEnv(context) reads from process.env via getContextEnvVar() - getSafeEnv(context) reads keyless values from context.locals - All necessary config (keys, urls, telemetry) is already available - The spread ...options at end of createClerkClient was never overriding anything useful - Simplifies the API and removes unnecessary parameters Benefits: ✅ Simpler API surface ✅ No unused parameters ✅ Clear single source of truth (getSafeEnv) ✅ Less confusing for developers ✅ All type checks pass

brkalow · 2026-02-13T03:46:54Z

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

+    PUBLIC_CLERK_KEYLESS_CLAIM_URL: envField.string({
+      context: 'client',
+      access: 'public',
+      optional: true,
+      url: true,
+    }),
+    PUBLIC_CLERK_KEYLESS_API_KEYS_URL: envField.string({
+      context: 'client',
+      access: 'public',
+      optional: true,
+      url: true,
+    }),


Are these used?

Nope! Bad claude

brkalow · 2026-02-13T03:47:35Z

packages/astro/src/server/keyless/file-storage.ts

+    throw new Error(
+      'Keyless mode requires a Node.js runtime with file system access. ' +
+        'Set PUBLIC_CLERK_KEYLESS_DISABLED=1 or CLERK_KEYLESS_DISABLED=1 to disable keyless mode.',
+    );


We should gracefully degrade here, not hard error.

Fixed. Now falls back to in-memory storage for non-Node.js runtimes (e.g., edge environments) instead of throwing. Keys will persist for the process lifetime but won't be written to disk, allowing keyless mode to work gracefully in environments without file system access. 🤦🏼

fixed! updated react-router one as well to match tanstack start's createFileStorage behavior

wobsoriano added the do not merge label Feb 10, 2026

github-actions bot added clerk-js nextjs react backend chrome-extension integration tanstack astro react-router vue core-3 labels Feb 10, 2026

vercel bot deployed to Preview February 10, 2026 17:11 View deployment

wobsoriano force-pushed the rob/astro-keyless branch from a4df941 to 55b6696 Compare February 10, 2026 17:20

vercel bot had a problem deploying to Preview February 10, 2026 17:21 Failure

wobsoriano removed clerk-js nextjs react backend chrome-extension tanstack react-router vue labels Feb 10, 2026

vercel bot had a problem deploying to Preview February 10, 2026 17:46 Failure

coderabbitai bot reviewed Feb 10, 2026

View reviewed changes

wobsoriano force-pushed the rob/astro-keyless branch from 54d9338 to fc1064b Compare February 10, 2026 17:53

chore: reinstall deps

a14541b

vercel bot temporarily deployed to Preview February 10, 2026 19:11 Inactive

vercel bot temporarily deployed to Preview February 10, 2026 19:16 Inactive

wobsoriano added 2 commits February 10, 2026 11:56

chore: add changeset

813e17e

chore: remove unused async keyword

1d79e23

vercel bot temporarily deployed to Preview February 10, 2026 19:56 Inactive

chore: remove unused changes

eaa509f

vercel bot temporarily deployed to Preview February 11, 2026 00:47 Inactive

Merge branch 'main' into rob/astro-keyless

c5cbbe8

vercel bot deployed to Preview February 11, 2026 14:17 View deployment

chore: clean up

5268f12

wobsoriano changed the title ~~feat(astro): [WIP] Introduce keyless mode~~ feat(astro): Add support for keyless mode Feb 11, 2026

chore: dedupe

e6d87ac

vercel bot temporarily deployed to Preview February 11, 2026 14:21 Inactive

wobsoriano removed the do not merge label Feb 11, 2026

chore: add internal params types

0b4fe75

vercel bot temporarily deployed to Preview February 11, 2026 14:30 Inactive

wobsoriano requested a review from brkalow February 11, 2026 14:35

Merge branch 'main' into rob/astro-keyless

a77202e

vercel bot deployed to Preview February 12, 2026 16:48 View deployment

brkalow reviewed Feb 13, 2026

View reviewed changes

Merge branch 'main' into rob/astro-keyless

d205350

vercel bot deployed to Preview February 13, 2026 16:06 View deployment

chore: use static imports for fs and path

4a83554

vercel bot temporarily deployed to Preview February 13, 2026 16:26 Inactive

github-actions bot added the react-router label Feb 13, 2026

Merge branch 'main' into rob/astro-keyless

4547ca5

vercel bot deployed to Preview February 13, 2026 16:28 View deployment

Conversation

wobsoriano commented Feb 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Changes

Data Flow

Checklist

Type of change

Summary by CodeRabbit

Uh oh!

changeset-bot bot commented Feb 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🦋 Changeset detected

Uh oh!

vercel bot commented Feb 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

coderabbitai bot commented Feb 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Reviews paused

Walkthrough

Uh oh!

coderabbitai bot commented Feb 10, 2026

Walkthrough

Uh oh!

coderabbitai bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

coderabbitai bot Feb 10, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

brkalow Feb 13, 2026

Choose a reason for hiding this comment

Uh oh!

wobsoriano Feb 13, 2026

Choose a reason for hiding this comment

Uh oh!

brkalow Feb 13, 2026

Choose a reason for hiding this comment

Uh oh!

wobsoriano Feb 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

wobsoriano Feb 13, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

wobsoriano commented Feb 10, 2026 •

edited

Loading

changeset-bot bot commented Feb 10, 2026 •

edited

Loading

vercel bot commented Feb 10, 2026 •

edited

Loading

coderabbitai bot commented Feb 10, 2026 •

edited

Loading

wobsoriano Feb 13, 2026 •

edited

Loading