make publishable client keys truly optional ig (i hope) (#1274)

mantrakp04 · web-flow · commit 3efb226c5901 · 2026-03-23T15:09:01.000-07:00
## 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.
diff --git a/docs/content/docs/(guides)/concepts/stack-app.mdx b/docs/content/docs/(guides)/concepts/stack-app.mdx
@@ -39,7 +39,7 @@ function ClientComponent() {
 
 ## Client vs. server
 
-`StackClientApp` contains everything needed to build a frontend application, for example the currently authenticated user. It requires a publishable client key in its initialization (usually set by the `NEXT_PUBLIC_STACK_PUBLISHABLE_CLIENT_KEY` environment variable).
+`StackClientApp` contains everything needed to build a frontend application, for example the currently authenticated user. It can use a publishable client key in its initialization (usually set by the `NEXT_PUBLIC_STACK_PUBLISHABLE_CLIENT_KEY` environment variable), but that key is only required if the project is configured to require publishable client keys.
 
 `StackServerApp` has all the functionality of `StackClientApp`, but also some functions with elevated permissions, eg. listing or modifying ALL users. This requires a secret server key (usually set by the `STACK_SECRET_SERVER_KEY` environment variable), which **must always be kept secret**.
 
diff --git a/docs/content/docs/(guides)/getting-started/setup.mdx b/docs/content/docs/(guides)/getting-started/setup.mdx
@@ -40,7 +40,7 @@ We recommend using our **setup wizard** for JavaScript frameworks for a seamless
       ### Update API keys
       </Step>
       
-      Create an account on [the Stack Auth dashboard](https://app.stack-auth.com/projects), create a new project with an API key, and copy its environment variables into the appropriate configuration file:
+      Create an account on [the Stack Auth dashboard](https://app.stack-auth.com/projects), create a new project, and copy its environment variables into the appropriate configuration file. If your project requires publishable client keys, create a project key that includes one and copy that as well.
 
       <PlatformCodeblock
         document="setup/setup"
@@ -91,7 +91,7 @@ We recommend using our **setup wizard** for JavaScript frameworks for a seamless
       ### Create API keys
       </Step>
       
-      [Register a new account on Stack](https://app.stack-auth.com/handler/sign-up), create a project in the dashboard, create a new API key from the left sidebar, and copy the project ID, publishable client key, and secret server key.
+      [Register a new account on Stack](https://app.stack-auth.com/handler/sign-up), create a project in the dashboard, and copy the project ID. If your project requires publishable client keys, also create a project key from the left sidebar and copy the publishable client key. For server-side setups, also copy the secret server key.
 
       <Step>
       ### Configure environment variables
diff --git a/docs/src/app/api/internal/[transport]/setup-instructions.md b/docs/src/app/api/internal/[transport]/setup-instructions.md
@@ -46,9 +46,11 @@ Ensure they are added to the repo.
 #### For Next.js Projects:
 Required vars (from Stack dashboard):
 - `NEXT_PUBLIC_STACK_PROJECT_ID`
-- `NEXT_PUBLIC_STACK_PUBLISHABLE_CLIENT_KEY`
 - `STACK_SECRET_SERVER_KEY`
 
+Optional unless your project requires publishable client keys:
+- `NEXT_PUBLIC_STACK_PUBLISHABLE_CLIENT_KEY`
+
 Check `.env.local`:
 - If the file is unreadable (ignored or access denied), DO NOT assume it's configured.
 - If any required var is missing or empty, prompt the user and PAUSE.
@@ -64,7 +66,8 @@ import { StackClientApp } from "@stackframe/react";
 export const stackClientApp = new StackClientApp({
   // You should store these in environment variables
   projectId: "YOUR_PROJECT_ID_HERE",
-  publishableClientKey: "YOUR_PUBLISHABLE_CLIENT_KEY_HERE",
+  // Only include this if your project requires publishable client keys
+  // publishableClientKey: "YOUR_PUBLISHABLE_CLIENT_KEY_HERE",
   tokenStore: "cookie",
   // redirectMethod: {
   //   useNavigate,
@@ -86,8 +89,8 @@ TODO in your web browser:
 3) Choose your framework: Next.js
 4) Copy these keys:
    - NEXT_PUBLIC_STACK_PROJECT_ID=...
-   - NEXT_PUBLIC_STACK_PUBLISHABLE_CLIENT_KEY=...
    - STACK_SECRET_SERVER_KEY=...
+   - NEXT_PUBLIC_STACK_PUBLISHABLE_CLIENT_KEY=... (only if your project requires publishable client keys)
 5) Paste them into your local `.env.local` (do not commit this file).
 6) Save the file.
 
@@ -105,10 +108,10 @@ TODO in your web browser:
 3) Choose your framework: React
 4) Copy these keys:
    - Project ID
-   - Publishable Client Key
+   - Publishable Client Key (only if your project requires publishable client keys)
 5) Update the `stack/client.ts` file with your keys:
    - Replace "YOUR_PROJECT_ID_HERE" with your Project ID
-   - Replace "YOUR_PUBLISHABLE_CLIENT_KEY_HERE" with your Publishable Client Key
+   - If needed, uncomment and replace "YOUR_PUBLISHABLE_CLIENT_KEY_HERE" with your Publishable Client Key
 6) Save the file.
 
 Reply here when done:
@@ -188,4 +191,3 @@ Reply with 1 or 2:
 
 If user replies `1`: Proceed to UI Installation Workflow calling the tool install UI components.
 If user replies `2`: Explain to the user what Stack Auth can do for him by reading our documentation using the MCP
-
diff --git a/packages/stack-cli/src/lib/init-prompt.ts b/packages/stack-cli/src/lib/init-prompt.ts
@@ -31,7 +31,7 @@ Depending on whether you're on a client or a server, you will want to create sta
 The stack client app has client-level permissions. It contains most of the useful methods and hooks for your client-side code.
 The stack server app has full read and write access to all users. It requires STACK_SECRET_SERVER_KEY env variable and should only be used in secure context
 
-In Next.js, env vars are auto-detected (NEXT_PUBLIC_STACK_PROJECT_ID etc.), so the constructor needs no explicit config. For other frameworks, you must pass projectId and publishableClientKey explicitly using the framework's env var access method.
+In Next.js, env vars are auto-detected (NEXT_PUBLIC_STACK_PROJECT_ID etc.), so the constructor needs no explicit config. For other frameworks, you must pass projectId explicitly using the framework's env var access method. Pass publishableClientKey only if your project is configured to require publishable client keys.
 
 The tokenStore should be "nextjs-cookie" for Next.js, or "cookie" for all other frameworks.
 
@@ -44,7 +44,7 @@ import { StackClientApp } from "@stackframe/stack"; // or "@stackframe/react" or
 
 export const stackClientApp = new StackClientApp({
   // Next.js: omit projectId/publishableClientKey (auto-detected from NEXT_PUBLIC_ env vars)
-  // Other frameworks: pass explicitly, e.g. for Vite:
+  // Other frameworks: pass projectId explicitly, and publishableClientKey only if required by your project. For Vite:
   //   projectId: import.meta.env.VITE_STACK_PROJECT_ID,
   //   publishableClientKey: import.meta.env.VITE_STACK_PUBLISHABLE_CLIENT_KEY,
   tokenStore: "nextjs-cookie", // or "cookie" for non-Next.js,
@@ -99,9 +99,10 @@ Rename the env var keys in .env to match the framework's convention for client-e
 
 The required variables are:
 - Project ID (e.g. NEXT_PUBLIC_STACK_PROJECT_ID, VITE_STACK_PROJECT_ID, etc.)
-- Publishable client key (e.g. NEXT_PUBLIC_STACK_PUBLISHABLE_CLIENT_KEY, VITE_STACK_PUBLISHABLE_CLIENT_KEY, etc.)
 - Secret server key: STACK_SECRET_SERVER_KEY (only for frameworks with server-side support, no prefix needed)
 
+The publishable client key (e.g. NEXT_PUBLIC_STACK_PUBLISHABLE_CLIENT_KEY, VITE_STACK_PUBLISHABLE_CLIENT_KEY, etc.) is only required if your project has publishable client keys enabled as a requirement.
+
 ### 6) React only: Wrap the entire page in a Stack provider
 
 This is used for the useUser and useStackApp hooks.
@@ -123,4 +124,3 @@ return (
 );
 \`\`\`
 `;
-
