make publishable client keys truly optional ig (i hope)

[mantrakp04]

Summary by CodeRabbit

Documentation

• Updated setup instructions across all documentation to clarify that the publishable client key is only required when your project configuration enforces it, removing confusion about unconditional requirements.

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
stack-auth-hosted-components	Ready	Preview, Comment	Mar 23, 2026 4:30pm
stack-backend	Ready	Preview, Comment	Mar 23, 2026 4:30pm
stack-dashboard	Ready	Preview, Comment	Mar 23, 2026 4:30pm
stack-demo	Ready	Preview, Comment	Mar 23, 2026 4:30pm
stack-docs	Ready	Preview, Comment	Mar 23, 2026 4:30pm

[coderabbitai]

Important

Review skipped

Review was skipped due to path filters

⛔ Files ignored due to path filters (1)

• pnpm-lock.yaml is excluded by !**/pnpm-lock.yaml

CodeRabbit blocks several paths by default. You can override this behavior by explicitly including those paths in the path filters. For example, including **/dist/** will override the default block on the dist directory, by removing the pattern from both the lists.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: d81c77f6-e1c8-4f45-99e4-bec7f3dd8dc1

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

📝 Walkthrough

Walkthrough

Documentation updates clarify that the NEXT_PUBLIC_STACK_PUBLISHABLE_CLIENT_KEY is conditionally required only when projects enforce publishable client keys, rather than always required. Changes span setup guides, API documentation, and CLI initialization prompts.

Changes

Cohort / File(s)	Summary
Documentation - Setup & Initialization docs/content/docs/(guides)/concepts/stack-app.mdx, docs/content/docs/(guides)/getting-started/setup.mdx, docs/src/app/api/internal/[transport]/setup-instructions.md	Updated initialization documentation to mark publishable client key as conditionally required. Removed unconditional requirement language and replaced with "only if your project requires..." wording. Adjusted code snippets to comment out publishable client key initialization where applicable.
CLI Setup Prompt Generation packages/stack-cli/src/lib/init-prompt.ts	Updated generated setup prompt text to clarify publishable client key is only needed when enabled for the project. Adjusted initialization instructions to pass projectId explicitly while treating publishableClientKey as conditional.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Possibly related PRs

• init stack cli project-id and publishable-client-key args #888: Handles publishable client key and init/setup flow across documentation and CLI args.
• Init stack more args #892: Modifies stack initialization flow and init tooling/templates for publishable client key handling.
• init script: add projectId and pck to next client app #911: Treats publishable client key and projectId as optional/on-demand in Next client app setup templates and environment handling.

Suggested reviewers

• N2D4

Poem

🐰 Keys that once were always needed,
Now just when the project's greeded!
Setup paths now conditional shine,
Docs clarified, oh how divine! ✨
Simpler init, less confusion to find!

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Description check	⚠️ Warning	The PR description only contains the template comment and lacks substantive details about the changes, objectives, and rationale.	Add a detailed description explaining the changes made to documentation and setup prompts, why publishable client keys are now optional, and the impact on users.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title refers to the main change (making publishable client keys optional) but uses informal language and expresses uncertainty, which reduces clarity.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

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

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch make-publishable-client-key-truly-not-required

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

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

[Copilot]

Pull request overview

Updates CLI-generated setup instructions and documentation to reflect that publishableClientKey / *_STACK_PUBLISHABLE_CLIENT_KEY should be optional unless a project is configured to require publishable client keys.

Changes:

• Adjusts Stack CLI init prompt text to describe publishableClientKey as conditional.
• Updates multiple docs pages/instructions to mark publishable client keys as optional depending on project configuration.
• Updates pnpm-lock.yaml (adds a new importer and bumps some transitive deps such as minimatch).

Reviewed changes

Copilot reviewed 4 out of 5 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
pnpm-lock.yaml	Lockfile updates; introduces a new workspace importer entry and updates transitive dependency versions.
packages/stack-cli/src/lib/init-prompt.ts	Updates CLI init prompt guidance around when to provide publishableClientKey.
docs/src/app/api/internal/[transport]/setup-instructions.md	Updates internal setup workflow text/code samples to treat publishable client key as conditional.
docs/content/docs/(guides)/getting-started/setup.mdx	Updates getting-started prose to describe publishable client keys as optional depending on project configuration.
docs/content/docs/(guides)/concepts/stack-app.mdx	Updates conceptual docs to clarify publishable client key is only required for projects configured to require it.

Files not reviewed (1)

• pnpm-lock.yaml: Language not supported

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@packages/stack-cli/src/lib/init-prompt.ts`:
- Around line 47-49: Update the Vite example in the comment block that currently
shows "projectId: import.meta.env.VITE_STACK_PROJECT_ID," and
"publishableClientKey: import.meta.env.VITE_STACK_PUBLISHABLE_CLIENT_KEY," so
the publishableClientKey is presented conditionally (not shown as always
required); modify the Vite snippet in the "Other frameworks" comment near the
existing Vite lines so that publishableClientKey is either commented out or
annotated with a conditional note (matching the earlier sentence that says it's
only needed conditionally) to avoid implying it's required by default.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: a8eb72df-d048-491b-8c22-16c73e397b93

📥 Commits

Reviewing files that changed from the base of the PR and between e59a707 and f2c2442.

⛔ Files ignored due to path filters (1)

• pnpm-lock.yaml is excluded by !**/pnpm-lock.yaml

📒 Files selected for processing (4)

• docs/content/docs/(guides)/concepts/stack-app.mdx
• docs/content/docs/(guides)/getting-started/setup.mdx
• docs/src/app/api/internal/[transport]/setup-instructions.md
• packages/stack-cli/src/lib/init-prompt.ts

[greptile-apps]

Greptile Summary

This PR updates setup documentation and CLI prompt templates to reflect that the publishable client key (publishableClientKey / NEXT_PUBLIC_STACK_PUBLISHABLE_CLIENT_KEY) is only required when the Stack Auth project is explicitly configured to enforce it, rather than being unconditionally required. Changes span the concepts docs, getting-started guide, the AI-agent setup-instructions markdown used by the internal transport API, and the stack-cli init prompt.

• All five changed prose locations (stack-app.mdx, setup.mdx, setup-instructions.md ×3 spots, init-prompt.ts ×2 spots) are updated consistently and the messaging is clear.
• The generated React client template in setup-instructions.md now comments out publishableClientKey with an explanatory note, correctly leaving projectId uncommented.
• pnpm-lock.yaml adds a packages/private importer entry for a rimraf devDependency, but the packages/private directory does not exist in the repository — this orphaned entry was already identified in a prior review thread. Additionally, minimatch is bumped from 10.1.1 to 10.2.4, removing the @isaacs/brace-expansion and @isaacs/balanced-match transitive dependencies, which is consistent with the version upgrade.

Confidence Score: 4/5

• Safe to merge; all documentation changes are consistent and correct — the only concern is the pre-flagged orphaned packages/private entry in the lockfile.
• All prose and template changes accurately reflect the optional nature of publishableClientKey and are consistent across every updated file. No logic or runtime code was modified. The single point of concern — the packages/private lockfile entry referencing a non-existent directory — was already identified in a prior review thread and does not affect documentation or CLI behaviour.
• pnpm-lock.yaml — the orphaned packages/private importer entry should be resolved before merging.

Important Files Changed

Filename	Overview
docs/content/docs/(guides)/concepts/stack-app.mdx	Single-sentence update clarifying that publishableClientKey is optional unless the project enforces it — accurate and well-worded.
docs/content/docs/(guides)/getting-started/setup.mdx	Both the wizard and manual setup steps updated to surface the conditional nature of the publishable client key; changes are clear and consistent.
docs/src/app/api/internal/[transport]/setup-instructions.md	AI-agent setup instructions updated across Next.js and React workflows to mark NEXT_PUBLIC_STACK_PUBLISHABLE_CLIENT_KEY as optional and comment out the key in the generated React template — all sections are internally consistent.
packages/stack-cli/src/lib/init-prompt.ts	CLI init prompt updated to describe publishableClientKey as conditional; projectId is still shown as required for non-Next.js frameworks. No generated code is built from user-provided input, so there is no injection risk.
pnpm-lock.yaml	Lockfile adds an orphaned packages/private importer (non-existent directory) and upgrades minimatch from 10.1.1 to 10.2.4 (removing @isaacs/brace-expansion and @isaacs/balanced-match). The orphaned importer was already flagged in a previous review thread.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[Start StackClientApp setup] --> B{Project configured to\nrequire publishable\nclient keys?}
    B -- Yes --> C[Include publishableClientKey\nin constructor / env var]
    B -- No --> D[Omit publishableClientKey\nentirely]
    C --> E[StackClientApp initialised]
    D --> E
    E --> F{Framework?}
    F -- Next.js --> G[Auto-detect from\nNEXT_PUBLIC_ env vars\nno explicit config needed]
    F -- Other e.g. Vite --> H[Pass projectId explicitly\ne.g. import.meta.env.VITE_STACK_PROJECT_ID]
    G --> I[Ready]
    H --> I

Loading

_{Last reviewed commit: "Merge branch 'dev' i..."}

[mantrakp04]

@greptile-ai review