diff --git a/docs-mintlify/guides/getting-started/setup.mdx b/docs-mintlify/guides/getting-started/setup.mdx
index 012d5fd5b4..0e4c832838 100644
--- a/docs-mintlify/guides/getting-started/setup.mdx
+++ b/docs-mintlify/guides/getting-started/setup.mdx
@@ -6,7 +6,7 @@ sidebarTitle: Setup
{/* This file is auto-generated by scripts/generate-setup-prompt-docs.ts. Do not edit it manually; edit packages/stack-shared/src/ai/prompts.ts instead. */}
-export const generatedSetupPromptText = "# Setting up Stack Auth\n\nThis prompt explains how to set up Stack Auth in your project.\n\nTo use it, you can use the sections below to set up Stack Auth in the project. For example, if you are setting up a Svelte project, you would follow the SDK setup instructions for a frontend JS project.\n\n## SDK Setup Instructions\n\nFollow these instructions in order to set up and get started with the Stack Auth SDK in various languages.\n\nNot all steps are applicable to every type of application; for example, React apps have some extra steps that are not needed with other frameworks.\n\nThe frameworks and languages with explicit SDK support are:\n\n- Next.js\n- React\n- Other JS & TS (both frontend and backend)\n\n\n \n Stack Auth has SDKs for various languages, frameworks, and libraries. Use the most specific package each, so, for example, even though a Next.js project uses both Next.js and React, use the Next.js package. If a programming language is not supported entirely, you may have to use the REST API to interface with Stack Auth.\n \n #### JavaScript & TypeScript\n \n For JS & TS, the following packages are available:\n \n - Next.js: `@stackframe/stack`\n - React: `@stackframe/react`\n - Other & vanilla JS: `@stackframe/js`\n \n You can install the correct JavaScript Stack Auth SDK into your project by running the following command:\n\n ```sh\n npm i \n # or: pnpm i \n # or: yarn add \n # or: bun add \n ```\n \n \n \n Next, let us create the Stack App object for your project. This is the most important object in a Stack Auth project.\n\n In a frontend where you cannot keep a secret key safe, you would use the `StackClientApp` constructor:\n \n ```ts src/stack/client.ts\n import { StackClientApp } from \"\";\n \n export const stackClientApp = new StackClientApp({\n tokenStore: \"cookie\", // \"nextjs-cookie\" for Next.js, \"cookie\" for other web frontends, null for backend environments\n });\n ```\n\n In a backend where you can keep a secret key safe, you can use the `StackServerApp`, which provides access to more sensitive APIs compared to `StackClientApp`:\n \n ```ts src/stack/server.ts\n import { StackServerApp } from \"\";\n \n export const stackServerApp = new StackServerApp({\n tokenStore: null,\n });\n ```\n \n In frameworks that are both front- and backend, like Next.js, you can also create a `StackServerApp` from a `StackClientApp` object:\n \n ```ts src/stack/server.ts\n import { StackServerApp } from \"\";\n import { stackClientApp } from \"./client\";\n \n export const stackServerApp = new StackServerApp({\n inheritsFrom: stackClientApp,\n });\n ```\n \n Note that the secret server key should **never** be exposed to the client, as it can be used to read and write everything in your Stack Auth project. In web frontends or bundled applications, you should therefore always only ever create a `StackClientApp` object.\n \n\n \n It's now time to create a development setup for Stack Auth.\n\n You can either run Stack Auth locally, or connect to a project hosted in the cloud.\n\n If you already use Stack Auth for your product, we recommend you re-use the same project to share your configuration between the two.\n\n \n \n First, create a `stack.config.ts` configuration file in the root directory of the workspace (or anywhere else):\n\n ```ts stack.config.ts\n import type { StackConfig } from \"\";\n\n // default: show-onboarding, which shows the onboarding flow for this project when Stack Auth starts\n export const config: StackConfig = \"show-onboarding\";\n ```\n\n To run your application with Stack Auth, you then need to start the emulator and set environment variables expected by your application. The `emulator run` CLI command does both of these, so you can simply wrap your existing `dev` script in your package.json:\n\n ```json package.json\n {\n // ...\n \"scripts\": {\n // ...\n \"dev\": \"npx @stackframe/stack-cli emulator run --config-file ./stack.config.ts -- \"\n }\n }\n ```\n \n\n \n Note: If you're an AI agent, and you don't already have the information you need from the Cloud project, you may have to ask the user for help on this step. You can either ask them to provide the environment variables, or just leave them empty for now and ask the user to complete them at the end.\n\n If you'd rather run your development environment on our infrastructure, or you already have an existing product, you can also connect a cloud project.\n\n This process is slightly different depending on whether you're setting up a frontend or a backend (whether your app can keep a secret key safe or not).\n\n #### Frontend\n\n Go to your project's dashboard on [app.stack-auth.com](https://app.stack-auth.com) and get the project ID. You can find it in the URL after the `/projects/` part. Copy-paste it into your `.env.local` file (or wherever your environment variables are stored):\n\n ```.env .env.local\n STACK_PROJECT_ID= # if available, prefix with your framework's convention for client-exposed variables (e.g. NEXT_PUBLIC_, VITE_, etc.)\n ```\n\n Alternatively, you can also just set the project ID in the `stack/client.ts` file:\n\n ```ts src/stack/client.ts\n export const stackClientApp = new StackClientApp({\n // ...\n projectId: \"your-project-id\",\n });\n ```\n\n\n #### Backend (or both frontend and backend)\n\n First, navigate to the [Project Keys](https://app.stack-auth.com/projects/-selector-/project-keys) page in the Stack Auth dashboard and generate a new set of keys.\n\n Then, copy-paste them into your `.env.local` file (or wherever your environment variables are stored):\n\n ```.env .env.local\n STACK_PROJECT_ID= # if desired, prefix with your framework's convention for client-exposed variables (e.g. NEXT_PUBLIC_, VITE_, etc.)\n STACK_SECRET_SERVER_KEY=\n ```\n\n They'll automatically be picked up by the `StackServerApp` constructor.\n \n \n \n\n and \">\n In React frameworks, Stack Auth provides `StackProvider` and `StackTheme` components that should wrap your entire app at the root level.\n \n For example, if you have an `App.tsx` file, update it as follows:\n \n ```tsx src/App.tsx\n import { StackProvider, StackTheme } from \"\";\n import { stackClientApp } from \"./stack/client\";\n \n export default function App() {\n return (\n \n \n {/* your app content */}\n \n \n );\n }\n ```\n \n For Next.js specifically: You can do this in the `layout.tsx` file in the `app` directory:\n \n ```tsx src/app/layout.tsx\n import { Suspense } from \"react\";\n import { StackProvider, StackTheme } from \"\";\n import { stackServerApp } from \"@/stack/server\";\n \n export default function RootLayout({ children }: { children: React.ReactNode }) {\n return (\n \n \n {children}\n \n \n );\n }\n ```\n \n \n \n Stack Auth also provides additional `useXyz` React hooks for `getXyz`/`listXyz` functions. For example, `useUser` is like `getUser`, but as a suspending React hook.\n \n To support the suspension, you need to add a suspense boundary around your app.\n \n The easiest way to do this is to just wrap your entire app in a `Suspense` component:\n \n ```tsx src/App.tsx\n import { Suspense } from \"react\";\n import { StackProvider, StackTheme } from \"\";\n import { stackClientApp } from \"./stack/client\";\n \n export default function App() {\n return (\n Loading...}>\n \n \n {/* your app content */}\n \n \n \n );\n }\n ```\n \n In Next.js, this can be easily done by adding a `loading.tsx` file in the `app` directory:\n \n ```tsx src/app/loading.tsx\n export default function Loading() {\n return
Loading...
;\n }\n ```\n \n Note: If you are an AI agent, make sure to make the loading indicator visually appealing and match the design of your app, instead of the example that just says \"Loading...\".\n \n\n \n You are now ready to use the Stack Auth SDK. If you have any frontends calling your backend endpoints, you may want to pass along the Stack Auth tokens in a header such that you can access the same user object on your backend.\n \n The most ergonomic way to do this is to pass the result of `stackClientApp.getAuthorizationHeader()` as the `Authorization` header into your backend endpoints when the user is signed in:\n \n ```ts\n // NOTE: This is your frontend's code\n const authorizationHeader = await stackClientApp.getAuthorizationHeader();\n const response = await fetch(\"/my-backend-endpoint\", {\n headers: {\n ...(authorizationHeader ? { Authorization: authorizationHeader } : {}),\n },\n });\n // ...\n ```\n \n In most backend frameworks you can then access the user object by passing the request object as a `tokenStore` of the functions that access the user object:\n \n ```ts\n // NOTE: This is your backend's code\n const user = await stackServerApp.getUser({ tokenStore: request });\n return new Response(\"Hello, \" + user.displayName, { headers: { \"Cache-Control\": \"private, no-store\" } });\n ```\n \n This will work as long as `request` is an object that follows the shape `{ headers: Record | { get: (name: string) => string | null } }`.\n \n \n Make sure that HTTP caching is disabled with `Cache-Control: private, no-store` for authenticated backend endpoints.\n \n \n If you cannot use `getAuthorizationHeader()`, for example because you are using a protocol other than HTTP, you can use `getAuthJson()` instead:\n \n ```ts\n // Frontend:\n await rpcCall(\"my-rpc-endpoint\", {\n data: {\n auth: await stackClientApp.getAuthJson(),\n },\n });\n \n // Backend:\n const user = await stackServerApp.getUser({ tokenStore: data.auth });\n return new RpcResponse(\"Hello, \" + user.displayName);\n ```\n \n\n \n\n\n## MCP Setup\n\n\n This prompt is not yet implemented.\n\n\n\n \n Install the MCP package:\n \n \n\n\n## Convex Setup\n\nFollow these instructions to integrate Stack Auth with Convex.\n\n\n \n If the project does not already use Convex, initialize a Convex + Next.js app:\n\n ```sh\n npm create convex@latest\n ```\n\n When prompted, choose **Next.js** and **No auth**. Stack Auth will provide auth.\n\n During development, run the Convex backend and the app dev server:\n\n ```sh\n npx convex dev\n npm run dev\n ```\n \n\n \n Install Stack Auth in the app. If you have not already completed the SDK setup steps above, run the setup wizard:\n\n ```sh\n npx @stackframe/stack-cli@latest init\n ```\n\n Create or select a Stack Auth project in the dashboard. Copy the Stack Auth environment variables into the app's `.env.local` file.\n\n Also add the same Stack Auth environment variables to the Convex deployment environment in the Convex dashboard.\n \n\n \n Create or update `convex/auth.config.ts`:\n\n ```ts convex/auth.config.ts\n import { getConvexProvidersConfig } from \"@stackframe/js\";\n // or: import { getConvexProvidersConfig } from \"@stackframe/react\";\n // or: import { getConvexProvidersConfig } from \"@stackframe/stack\";\n\n export default {\n providers: getConvexProvidersConfig({\n projectId: process.env.STACK_PROJECT_ID, // or process.env.NEXT_PUBLIC_STACK_PROJECT_ID\n }),\n };\n ```\n \n\n \n Update the Convex client setup so Convex receives Stack Auth tokens.\n\n In browser JavaScript:\n\n ```ts\n convexClient.setAuth(stackClientApp.getConvexClientAuth({}));\n ```\n\n In React:\n\n ```ts\n convexReactClient.setAuth(stackClientApp.getConvexClientAuth({}));\n ```\n\n For Convex HTTP clients on the server, pass a request-like token store:\n\n ```ts\n convexHttpClient.setAuth(stackClientApp.getConvexHttpClientAuth({ tokenStore: requestObject }));\n ```\n \n\n \n In Convex queries and mutations, use Stack Auth's Convex integration to read the current user.\n\n ```ts convex/myFunctions.ts\n import { query } from \"./_generated/server\";\n import { stackServerApp } from \"../src/stack/server\";\n\n export const myQuery = query({\n handler: async (ctx, args) => {\n const user = await stackServerApp.getPartialUser({ from: \"convex\", ctx });\n return user;\n },\n });\n ```\n \n\n \n\n\n## Supabase Setup\n\n\n This setup covers Supabase Row Level Security (RLS) with Stack Auth JWTs. It does not sync user data between Supabase and Stack Auth. Use Stack Auth webhooks if you need data sync.\n\n\n\n \n In the Supabase SQL editor, enable Row Level Security for your tables and write policies based on Supabase JWT claims.\n\n For example, this sample table demonstrates public rows, authenticated rows, and user-owned rows:\n\n ```sql\n CREATE TABLE data (\n id bigint PRIMARY KEY,\n text text NOT NULL,\n user_id UUID\n );\n\n INSERT INTO data (id, text, user_id) VALUES\n (1, 'Everyone can see this', NULL),\n (2, 'Only authenticated users can see this', NULL),\n (3, 'Only user with specific id can see this', NULL);\n\n ALTER TABLE data ENABLE ROW LEVEL SECURITY;\n\n CREATE POLICY \"Public read\" ON \"public\".\"data\" TO public\n USING (id = 1);\n\n CREATE POLICY \"Authenticated access\" ON \"public\".\"data\" TO authenticated\n USING (id = 2);\n\n CREATE POLICY \"User access\" ON \"public\".\"data\" TO authenticated\n USING (id = 3 AND auth.uid() = user_id);\n ```\n \n\n \n If you are starting from scratch with Next.js, you can use Supabase's template and then initialize Stack Auth:\n\n ```sh\n npx create-next-app@latest -e with-supabase stack-supabase\n cd stack-supabase\n npx @stackframe/stack-cli@latest init\n ```\n\n Add the Supabase environment variables to `.env.local`:\n\n ```.env .env.local\n NEXT_PUBLIC_SUPABASE_URL=\n NEXT_PUBLIC_SUPABASE_ANON_KEY=\n SUPABASE_JWT_SECRET=\n ```\n\n Also add the Stack Auth environment variables:\n\n ```.env .env.local\n NEXT_PUBLIC_STACK_PROJECT_ID=\n NEXT_PUBLIC_STACK_PUBLISHABLE_CLIENT_KEY=\n STACK_SECRET_SERVER_KEY=\n ```\n \n\n \n Create a server action that signs a Supabase JWT using the current Stack Auth user ID:\n\n ```tsx utils/actions.ts\n 'use server';\n\n import { stackServerApp } from \"@/stack/server\";\n import * as jose from \"jose\";\n\n export const getSupabaseJwt = async () => {\n const user = await stackServerApp.getUser();\n\n if (!user) {\n return null;\n }\n\n const token = await new jose.SignJWT({\n sub: user.id,\n role: \"authenticated\",\n })\n .setProtectedHeader({ alg: \"HS256\" })\n .setIssuedAt()\n .setExpirationTime(\"1h\")\n .sign(new TextEncoder().encode(process.env.SUPABASE_JWT_SECRET));\n\n return token;\n };\n ```\n \n\n \n Create a helper that passes the server-generated JWT to Supabase:\n\n ```tsx utils/supabase-client.ts\n import { createBrowserClient } from \"@supabase/ssr\";\n import { getSupabaseJwt } from \"./actions\";\n\n export const createSupabaseClient = () => {\n return createBrowserClient(\n process.env.NEXT_PUBLIC_SUPABASE_URL!,\n process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!,\n { accessToken: async () => await getSupabaseJwt() || \"\" },\n );\n };\n ```\n \n\n \n Use the Supabase client from your UI. The RLS policies will decide which rows the user can read based on the Stack Auth user ID embedded in the Supabase JWT.\n\n ```tsx app/page.tsx\n 'use client';\n\n import { createSupabaseClient } from \"@/utils/supabase-client\";\n import { useStackApp, useUser } from \"@stackframe/stack\";\n import Link from \"next/link\";\n import { useEffect, useState } from \"react\";\n\n export default function Page() {\n const app = useStackApp();\n const user = useUser();\n const supabase = createSupabaseClient();\n const [data, setData] = useState(null);\n\n useEffect(() => {\n supabase.from(\"data\").select().then(({ data }) => setData(data ?? []));\n }, []);\n\n const listContent = data === null\n ?
Loading...
\n : data.length === 0\n ?
No notes found
\n : data.map((note) =>
{note.text}
);\n\n return (\n
\n {user ? (\n <>\n
You are signed in
\n
User ID: {user.id}
\n Sign Out\n \n ) : (\n Sign In\n )}\n
Supabase data
\n
{listContent}
\n
\n );\n }\n ```\n \n\n \n\n\n## CLI Setup\n\nFollow these instructions to authenticate users in a command line application with Stack Auth.\n\n\n \n Download the Stack Auth CLI authentication template and place it in your project. For Python apps, copy it as `stack_auth_cli_template.py`.\n\n Example project layout:\n\n ```text\n my-python-app/\n ├─ main.py\n └─ stack_auth_cli_template.py\n ```\n \n\n \n Import and call `prompt_cli_login`. It opens the browser, lets the user authenticate, and returns a refresh token.\n\n ```py main.py\n from stack_auth_cli_template import prompt_cli_login\n\n refresh_token = prompt_cli_login(\n app_url=\"https://your-app-url.example.com\",\n project_id=\"your-project-id-here\",\n publishable_client_key=\"your-publishable-client-key-here\",\n )\n\n if refresh_token is None:\n print(\"User cancelled the login process. Exiting\")\n exit(1)\n ```\n\n You can store the refresh token in a local file or keychain and only prompt the user again when no saved refresh token exists.\n \n\n \n Use the refresh token with Stack Auth's REST API to get an access token.\n\n ```py\n def get_access_token(refresh_token):\n access_token_response = stack_auth_request(\n \"post\",\n \"/api/v1/auth/sessions/current/refresh\",\n headers={\n \"x-stack-refresh-token\": refresh_token,\n },\n )\n\n return access_token_response[\"access_token\"]\n ```\n \n\n \n Use the access token to call the Stack Auth REST API as the logged-in user.\n\n ```py\n def get_user_object(access_token):\n return stack_auth_request(\n \"get\",\n \"/api/v1/users/me\",\n headers={\n \"x-stack-access-token\": access_token,\n },\n )\n\n user = get_user_object(get_access_token(refresh_token))\n print(\"The user is logged in as\", user[\"display_name\"] or user[\"primary_email\"])\n ```\n \n\n \n";
+export const generatedSetupPromptText = "# Setting up Stack Auth\n\nThis prompt explains how to set up Stack Auth in your project.\n\nTo use it, you can use the sections below to set up Stack Auth in the project. For example, if you are setting up a Svelte project, you would follow the SDK setup instructions for a frontend JS project.\n\n## SDK Setup Instructions\n\nFollow these instructions in order to set up and get started with the Stack Auth SDK in various languages.\n\nNot all steps are applicable to every type of application; for example, React apps have some extra steps that are not needed with other frameworks.\n\nThe frameworks and languages with explicit SDK support are:\n\n- Next.js\n- React\n- Other JS & TS (both frontend and backend)\n\n\n \n Stack Auth has SDKs for various languages, frameworks, and libraries. Use the most specific package each, so, for example, even though a Next.js project uses both Next.js and React, use the Next.js package. If a programming language is not supported entirely, you may have to use the REST API to interface with Stack Auth.\n \n #### JavaScript & TypeScript\n \n For JS & TS, the following packages are available:\n \n - Next.js: `@stackframe/stack`\n - React: `@stackframe/react`\n - Other & vanilla JS: `@stackframe/js`\n \n You can install the correct JavaScript Stack Auth SDK into your project by running the following command:\n\n ```sh\n npm i \n # or: pnpm i \n # or: yarn add \n # or: bun add \n ```\n \n \n \n Next, let us create the Stack App object for your project. This is the most important object in a Stack Auth project.\n\n In a frontend where you cannot keep a secret key safe, you would use the `StackClientApp` constructor:\n \n ```ts src/stack/client.ts\n import { StackClientApp } from \"\";\n \n export const stackClientApp = new StackClientApp({\n tokenStore: \"cookie\", // \"nextjs-cookie\" for Next.js, \"cookie\" for other web frontends, null for backend environments\n });\n ```\n\n In a backend where you can keep a secret key safe, you can use the `StackServerApp`, which provides access to more sensitive APIs compared to `StackClientApp`:\n \n ```ts src/stack/server.ts\n import { StackServerApp } from \"\";\n \n export const stackServerApp = new StackServerApp({\n tokenStore: null,\n });\n ```\n \n In frameworks that are both front- and backend, like Next.js, you can also create a `StackServerApp` from a `StackClientApp` object:\n \n ```ts src/stack/server.ts\n import { StackServerApp } from \"\";\n import { stackClientApp } from \"./client\";\n \n export const stackServerApp = new StackServerApp({\n inheritsFrom: stackClientApp,\n });\n ```\n \n Note that the secret server key should **never** be exposed to the client, as it can be used to read and write everything in your Stack Auth project. In web frontends or bundled applications, you should therefore always only ever create a `StackClientApp` object.\n \n\n \n It's now time to create a development setup for Stack Auth.\n\n You can either run Stack Auth locally, or connect to a project hosted in the cloud.\n\n If you already use Stack Auth for your product, we recommend you re-use the same project to share your configuration between the two.\n\n \n \n First, create a `stack.config.ts` configuration file in the root directory of the workspace (or anywhere else):\n\n ```ts stack.config.ts\n import type { StackConfig } from \"\";\n\n // default: show-onboarding, which shows the onboarding flow for this project when Stack Auth starts\n export const config: StackConfig = \"show-onboarding\";\n ```\n\n To run your application with Stack Auth, you then need to start the emulator and set environment variables expected by your application. The `emulator run` CLI command does both of these, so you can simply wrap your existing `dev` script in your package.json:\n\n ```json package.json\n {\n // ...\n \"scripts\": {\n // ...\n \"dev\": \"npx @stackframe/stack-cli emulator run --config-file ./stack.config.ts -- \"\n }\n }\n ```\n \n\n \n Note: If you're an AI agent, and you don't already have the information you need from the Cloud project, you may have to ask the user for help on this step. You can either ask them to provide the environment variables, or just leave them empty for now and ask the user to complete them at the end.\n\n If you'd rather run your development environment on our infrastructure, or you already have an existing product, you can also connect a cloud project.\n\n This process is slightly different depending on whether you're setting up a frontend or a backend (whether your app can keep a secret key safe or not).\n\n #### Frontend\n\n Go to your project's dashboard on [app.stack-auth.com](https://app.stack-auth.com) and get the project ID. You can find it in the URL after the `/projects/` part. Copy-paste it into your `.env.local` file (or wherever your environment variables are stored):\n\n ```.env .env.local\n # Prefix the variable name with your framework's convention for client-exposed\n # variables. For Next.js use NEXT_PUBLIC_STACK_PROJECT_ID, for Vite use\n # VITE_STACK_PROJECT_ID, etc. If your framework has no such convention, use\n # STACK_PROJECT_ID as-is.\n STACK_PROJECT_ID=\n ```\n\n This is the **only** environment variable the client SDK reads in the cloud-project setup. Do not invent or add any other Stack Auth env vars on the client (in particular, there is **no** separate publishable / client key — the project ID alone is sufficient on the client).\n\n Alternatively, you can also just set the project ID in the `stack/client.ts` file:\n\n ```ts src/stack/client.ts\n export const stackClientApp = new StackClientApp({\n // ...\n projectId: \"your-project-id\",\n });\n ```\n\n\n #### Backend (or both frontend and backend)\n\n First, navigate to the [Project Keys](https://app.stack-auth.com/projects/-selector-/project-keys) page in the Stack Auth dashboard and generate a new set of keys.\n\n Then, copy-paste them into your `.env.local` file (or wherever your environment variables are stored):\n\n ```.env .env.local\n # Prefix STACK_PROJECT_ID with your framework's convention for client-exposed\n # variables (e.g. NEXT_PUBLIC_STACK_PROJECT_ID for Next.js, VITE_STACK_PROJECT_ID\n # for Vite). STACK_SECRET_SERVER_KEY must NEVER be exposed to the client and\n # must NOT be prefixed.\n STACK_PROJECT_ID=\n STACK_SECRET_SERVER_KEY=\n ```\n\n These two variables are the **complete** set the SDK reads in the cloud-project setup. Do not add any additional Stack Auth env vars (in particular, there is **no** separate publishable / client key — the project ID alone is sufficient on the client). The dashboard \"Project Keys\" page exposes exactly these two values; if a third slot is present in any `.env.local` you write, it is wrong.\n\n They'll automatically be picked up by the `StackServerApp` constructor.\n \n \n \n\n and \">\n In React frameworks, Stack Auth provides `StackProvider` and `StackTheme` components that should wrap your entire app at the root level.\n \n For example, if you have an `App.tsx` file, update it as follows:\n \n ```tsx src/App.tsx\n import { StackProvider, StackTheme } from \"\";\n import { stackClientApp } from \"./stack/client\";\n \n export default function App() {\n return (\n \n \n {/* your app content */}\n \n \n );\n }\n ```\n \n For Next.js specifically: You can do this in the `layout.tsx` file in the `app` directory:\n \n ```tsx src/app/layout.tsx\n import { Suspense } from \"react\";\n import { StackProvider, StackTheme } from \"\";\n import { stackServerApp } from \"@/stack/server\";\n \n export default function RootLayout({ children }: { children: React.ReactNode }) {\n return (\n \n \n {children}\n \n \n );\n }\n ```\n \n \n \n Stack Auth also provides additional `useXyz` React hooks for `getXyz`/`listXyz` functions. For example, `useUser` is like `getUser`, but as a suspending React hook.\n \n To support the suspension, you need to add a suspense boundary around your app.\n \n The easiest way to do this is to just wrap your entire app in a `Suspense` component:\n \n ```tsx src/App.tsx\n import { Suspense } from \"react\";\n import { StackProvider, StackTheme } from \"\";\n import { stackClientApp } from \"./stack/client\";\n \n export default function App() {\n return (\n Loading...}>\n \n \n {/* your app content */}\n \n \n \n );\n }\n ```\n \n In Next.js, this can be easily done by adding a `loading.tsx` file in the `app` directory:\n \n ```tsx src/app/loading.tsx\n export default function Loading() {\n return
Loading...
;\n }\n ```\n \n Note: If you are an AI agent, make sure to make the loading indicator visually appealing and match the design of your app, instead of the example that just says \"Loading...\".\n \n\n \n You are now ready to use the Stack Auth SDK. If you have any frontends calling your backend endpoints, you may want to pass along the Stack Auth tokens in a header such that you can access the same user object on your backend.\n \n The most ergonomic way to do this is to pass the result of `stackClientApp.getAuthorizationHeader()` as the `Authorization` header into your backend endpoints when the user is signed in:\n \n ```ts\n // NOTE: This is your frontend's code\n const authorizationHeader = await stackClientApp.getAuthorizationHeader();\n const response = await fetch(\"/my-backend-endpoint\", {\n headers: {\n ...(authorizationHeader ? { Authorization: authorizationHeader } : {}),\n },\n });\n // ...\n ```\n \n In most backend frameworks you can then access the user object by passing the request object as a `tokenStore` of the functions that access the user object:\n \n ```ts\n // NOTE: This is your backend's code\n const user = await stackServerApp.getUser({ tokenStore: request });\n return new Response(\"Hello, \" + user.displayName, { headers: { \"Cache-Control\": \"private, no-store\" } });\n ```\n \n This will work as long as `request` is an object that follows the shape `{ headers: Record | { get: (name: string) => string | null } }`.\n \n \n Make sure that HTTP caching is disabled with `Cache-Control: private, no-store` for authenticated backend endpoints.\n \n \n If you cannot use `getAuthorizationHeader()`, for example because you are using a protocol other than HTTP, you can use `getAuthJson()` instead:\n \n ```ts\n // Frontend:\n await rpcCall(\"my-rpc-endpoint\", {\n data: {\n auth: await stackClientApp.getAuthJson(),\n },\n });\n \n // Backend:\n const user = await stackServerApp.getUser({ tokenStore: data.auth });\n return new RpcResponse(\"Hello, \" + user.displayName);\n ```\n \n\n \n\n\n## MCP Setup\n\n\n This prompt is not yet implemented.\n\n\n\n \n Install the MCP package:\n \n \n\n\n## Convex Setup\n\nFollow these instructions to integrate Stack Auth with Convex.\n\n\n \n If the project does not already use Convex, initialize a Convex + Next.js app:\n\n ```sh\n npm create convex@latest\n ```\n\n When prompted, choose **Next.js** and **No auth**. Stack Auth will provide auth.\n\n During development, run the Convex backend and the app dev server:\n\n ```sh\n npx convex dev\n npm run dev\n ```\n \n\n \n Install Stack Auth in the app. If you have not already completed the SDK setup steps above, run the setup wizard:\n\n ```sh\n npx @stackframe/stack-cli@latest init\n ```\n\n Create or select a Stack Auth project in the dashboard. Copy the Stack Auth environment variables into the app's `.env.local` file.\n\n Also add the same Stack Auth environment variables to the Convex deployment environment in the Convex dashboard.\n \n\n \n Create or update `convex/auth.config.ts`:\n\n ```ts convex/auth.config.ts\n import { getConvexProvidersConfig } from \"@stackframe/js\";\n // or: import { getConvexProvidersConfig } from \"@stackframe/react\";\n // or: import { getConvexProvidersConfig } from \"@stackframe/stack\";\n\n export default {\n providers: getConvexProvidersConfig({\n projectId: process.env.STACK_PROJECT_ID, // or process.env.NEXT_PUBLIC_STACK_PROJECT_ID\n }),\n };\n ```\n \n\n \n Update the Convex client setup so Convex receives Stack Auth tokens.\n\n In browser JavaScript:\n\n ```ts\n convexClient.setAuth(stackClientApp.getConvexClientAuth({}));\n ```\n\n In React:\n\n ```ts\n convexReactClient.setAuth(stackClientApp.getConvexClientAuth({}));\n ```\n\n For Convex HTTP clients on the server, pass a request-like token store:\n\n ```ts\n convexHttpClient.setAuth(stackClientApp.getConvexHttpClientAuth({ tokenStore: requestObject }));\n ```\n \n\n \n In Convex queries and mutations, use Stack Auth's Convex integration to read the current user.\n\n ```ts convex/myFunctions.ts\n import { query } from \"./_generated/server\";\n import { stackServerApp } from \"../src/stack/server\";\n\n export const myQuery = query({\n handler: async (ctx, args) => {\n const user = await stackServerApp.getPartialUser({ from: \"convex\", ctx });\n return user;\n },\n });\n ```\n \n\n \n\n\n## Supabase Setup\n\n\n This setup covers Supabase Row Level Security (RLS) with Stack Auth JWTs. It does not sync user data between Supabase and Stack Auth. Use Stack Auth webhooks if you need data sync.\n\n\n\n \n In the Supabase SQL editor, enable Row Level Security for your tables and write policies based on Supabase JWT claims.\n\n For example, this sample table demonstrates public rows, authenticated rows, and user-owned rows:\n\n ```sql\n CREATE TABLE data (\n id bigint PRIMARY KEY,\n text text NOT NULL,\n user_id UUID\n );\n\n INSERT INTO data (id, text, user_id) VALUES\n (1, 'Everyone can see this', NULL),\n (2, 'Only authenticated users can see this', NULL),\n (3, 'Only user with specific id can see this', NULL);\n\n ALTER TABLE data ENABLE ROW LEVEL SECURITY;\n\n CREATE POLICY \"Public read\" ON \"public\".\"data\" TO public\n USING (id = 1);\n\n CREATE POLICY \"Authenticated access\" ON \"public\".\"data\" TO authenticated\n USING (id = 2);\n\n CREATE POLICY \"User access\" ON \"public\".\"data\" TO authenticated\n USING (id = 3 AND auth.uid() = user_id);\n ```\n \n\n \n If you are starting from scratch with Next.js, you can use Supabase's template and then initialize Stack Auth:\n\n ```sh\n npx create-next-app@latest -e with-supabase stack-supabase\n cd stack-supabase\n npx @stackframe/stack-cli@latest init\n ```\n\n Add the Supabase environment variables to `.env.local`:\n\n ```.env .env.local\n NEXT_PUBLIC_SUPABASE_URL=\n NEXT_PUBLIC_SUPABASE_ANON_KEY=\n SUPABASE_JWT_SECRET=\n ```\n\n Also add the Stack Auth environment variables:\n\n ```.env .env.local\n NEXT_PUBLIC_STACK_PROJECT_ID=\n NEXT_PUBLIC_STACK_PUBLISHABLE_CLIENT_KEY=\n STACK_SECRET_SERVER_KEY=\n ```\n \n\n \n Create a server action that signs a Supabase JWT using the current Stack Auth user ID:\n\n ```tsx utils/actions.ts\n 'use server';\n\n import { stackServerApp } from \"@/stack/server\";\n import * as jose from \"jose\";\n\n export const getSupabaseJwt = async () => {\n const user = await stackServerApp.getUser();\n\n if (!user) {\n return null;\n }\n\n const token = await new jose.SignJWT({\n sub: user.id,\n role: \"authenticated\",\n })\n .setProtectedHeader({ alg: \"HS256\" })\n .setIssuedAt()\n .setExpirationTime(\"1h\")\n .sign(new TextEncoder().encode(process.env.SUPABASE_JWT_SECRET));\n\n return token;\n };\n ```\n \n\n \n Create a helper that passes the server-generated JWT to Supabase:\n\n ```tsx utils/supabase-client.ts\n import { createBrowserClient } from \"@supabase/ssr\";\n import { getSupabaseJwt } from \"./actions\";\n\n export const createSupabaseClient = () => {\n return createBrowserClient(\n process.env.NEXT_PUBLIC_SUPABASE_URL!,\n process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!,\n { accessToken: async () => await getSupabaseJwt() || \"\" },\n );\n };\n ```\n \n\n \n Use the Supabase client from your UI. The RLS policies will decide which rows the user can read based on the Stack Auth user ID embedded in the Supabase JWT.\n\n ```tsx app/page.tsx\n 'use client';\n\n import { createSupabaseClient } from \"@/utils/supabase-client\";\n import { useStackApp, useUser } from \"@stackframe/stack\";\n import Link from \"next/link\";\n import { useEffect, useState } from \"react\";\n\n export default function Page() {\n const app = useStackApp();\n const user = useUser();\n const supabase = createSupabaseClient();\n const [data, setData] = useState(null);\n\n useEffect(() => {\n supabase.from(\"data\").select().then(({ data }) => setData(data ?? []));\n }, []);\n\n const listContent = data === null\n ?
Loading...
\n : data.length === 0\n ?
No notes found
\n : data.map((note) =>
{note.text}
);\n\n return (\n
\n {user ? (\n <>\n
You are signed in
\n
User ID: {user.id}
\n Sign Out\n \n ) : (\n Sign In\n )}\n
Supabase data
\n
{listContent}
\n
\n );\n }\n ```\n \n\n \n\n\n## CLI Setup\n\nFollow these instructions to authenticate users in a command line application with Stack Auth.\n\n\n \n Download the Stack Auth CLI authentication template and place it in your project. For Python apps, copy it as `stack_auth_cli_template.py`.\n\n Example project layout:\n\n ```text\n my-python-app/\n ├─ main.py\n └─ stack_auth_cli_template.py\n ```\n \n\n \n Import and call `prompt_cli_login`. It opens the browser, lets the user authenticate, and returns a refresh token.\n\n ```py main.py\n from stack_auth_cli_template import prompt_cli_login\n\n refresh_token = prompt_cli_login(\n app_url=\"https://your-app-url.example.com\",\n project_id=\"your-project-id-here\",\n publishable_client_key=\"your-publishable-client-key-here\",\n )\n\n if refresh_token is None:\n print(\"User cancelled the login process. Exiting\")\n exit(1)\n ```\n\n You can store the refresh token in a local file or keychain and only prompt the user again when no saved refresh token exists.\n \n\n \n Use the refresh token with Stack Auth's REST API to get an access token.\n\n ```py\n def get_access_token(refresh_token):\n access_token_response = stack_auth_request(\n \"post\",\n \"/api/v1/auth/sessions/current/refresh\",\n headers={\n \"x-stack-refresh-token\": refresh_token,\n },\n )\n\n return access_token_response[\"access_token\"]\n ```\n \n\n \n Use the access token to call the Stack Auth REST API as the logged-in user.\n\n ```py\n def get_user_object(access_token):\n return stack_auth_request(\n \"get\",\n \"/api/v1/users/me\",\n headers={\n \"x-stack-access-token\": access_token,\n },\n )\n\n user = get_user_object(get_access_token(refresh_token))\n print(\"The user is logged in as\", user[\"display_name\"] or user[\"primary_email\"])\n ```\n \n\n \n";
export const setupToolIds = ["nextjs","react","js","tanstack-start","tanstack-query","nodejs","bun","convex","supabase","cli"];
export const setupTabMetadata = [{"toolId":"nextjs","title":"Next.js"},{"toolId":"react","title":"React"},{"toolId":"js","title":"JS/TS"},{"toolId":"tanstack-start","title":"Tanstack Start"},{"toolId":"nodejs","title":"Node.js"},{"toolId":"bun","title":"Bun"},{"toolId":"convex","title":"Convex"},{"toolId":"supabase","title":"Supabase"},{"toolId":"cli","title":"CLI"}];
export const unifiedAiPromptTabTitle = "Unified AI Prompt";
@@ -635,9 +635,15 @@ export const onSetupToolClick = (event) => {
Go to your project's dashboard on [app.stack-auth.com](https://app.stack-auth.com) and get the project ID. You can find it in the URL after the `/projects/` part. Copy-paste it into your `.env.local` file (or wherever your environment variables are stored):
```.env .env.local
- STACK_PROJECT_ID= # if available, prefix with your framework's convention for client-exposed variables (e.g. NEXT_PUBLIC_, VITE_, etc.)
+ # Prefix the variable name with your framework's convention for client-exposed
+ # variables. For Next.js use NEXT_PUBLIC_STACK_PROJECT_ID, for Vite use
+ # VITE_STACK_PROJECT_ID, etc. If your framework has no such convention, use
+ # STACK_PROJECT_ID as-is.
+ STACK_PROJECT_ID=
```
+ This is the **only** environment variable the client SDK reads in the cloud-project setup. Do not invent or add any other Stack Auth env vars on the client (in particular, there is **no** separate publishable / client key — the project ID alone is sufficient on the client).
+
Alternatively, you can also just set the project ID in the `stack/client.ts` file:
```ts src/stack/client.ts
@@ -655,10 +661,16 @@ export const onSetupToolClick = (event) => {
Then, copy-paste them into your `.env.local` file (or wherever your environment variables are stored):
```.env .env.local
- STACK_PROJECT_ID= # if desired, prefix with your framework's convention for client-exposed variables (e.g. NEXT_PUBLIC_, VITE_, etc.)
+ # Prefix STACK_PROJECT_ID with your framework's convention for client-exposed
+ # variables (e.g. NEXT_PUBLIC_STACK_PROJECT_ID for Next.js, VITE_STACK_PROJECT_ID
+ # for Vite). STACK_SECRET_SERVER_KEY must NEVER be exposed to the client and
+ # must NOT be prefixed.
+ STACK_PROJECT_ID=
STACK_SECRET_SERVER_KEY=
```
+ These two variables are the **complete** set the SDK reads in the cloud-project setup. Do not add any additional Stack Auth env vars (in particular, there is **no** separate publishable / client key — the project ID alone is sufficient on the client). The dashboard "Project Keys" page exposes exactly these two values; if a third slot is present in any `.env.local` you write, it is wrong.
+
They'll automatically be picked up by the `StackServerApp` constructor.
@@ -802,9 +814,15 @@ export const onSetupToolClick = (event) => {
Go to your project's dashboard on [app.stack-auth.com](https://app.stack-auth.com) and get the project ID. You can find it in the URL after the `/projects/` part. Copy-paste it into your `.env.local` file (or wherever your environment variables are stored):
```.env .env.local
- STACK_PROJECT_ID= # if available, prefix with your framework's convention for client-exposed variables (e.g. NEXT_PUBLIC_, VITE_, etc.)
+ # Prefix the variable name with your framework's convention for client-exposed
+ # variables. For Next.js use NEXT_PUBLIC_STACK_PROJECT_ID, for Vite use
+ # VITE_STACK_PROJECT_ID, etc. If your framework has no such convention, use
+ # STACK_PROJECT_ID as-is.
+ STACK_PROJECT_ID=
```
+ This is the **only** environment variable the client SDK reads in the cloud-project setup. Do not invent or add any other Stack Auth env vars on the client (in particular, there is **no** separate publishable / client key — the project ID alone is sufficient on the client).
+
Alternatively, you can also just set the project ID in the `stack/client.ts` file:
```ts src/stack/client.ts
@@ -822,10 +840,16 @@ export const onSetupToolClick = (event) => {
Then, copy-paste them into your `.env.local` file (or wherever your environment variables are stored):
```.env .env.local
- STACK_PROJECT_ID= # if desired, prefix with your framework's convention for client-exposed variables (e.g. NEXT_PUBLIC_, VITE_, etc.)
+ # Prefix STACK_PROJECT_ID with your framework's convention for client-exposed
+ # variables (e.g. NEXT_PUBLIC_STACK_PROJECT_ID for Next.js, VITE_STACK_PROJECT_ID
+ # for Vite). STACK_SECRET_SERVER_KEY must NEVER be exposed to the client and
+ # must NOT be prefixed.
+ STACK_PROJECT_ID=
STACK_SECRET_SERVER_KEY=
```
+ These two variables are the **complete** set the SDK reads in the cloud-project setup. Do not add any additional Stack Auth env vars (in particular, there is **no** separate publishable / client key — the project ID alone is sufficient on the client). The dashboard "Project Keys" page exposes exactly these two values; if a third slot is present in any `.env.local` you write, it is wrong.
+
They'll automatically be picked up by the `StackServerApp` constructor.
@@ -1001,9 +1025,15 @@ export const onSetupToolClick = (event) => {
Go to your project's dashboard on [app.stack-auth.com](https://app.stack-auth.com) and get the project ID. You can find it in the URL after the `/projects/` part. Copy-paste it into your `.env.local` file (or wherever your environment variables are stored):
```.env .env.local
- STACK_PROJECT_ID= # if available, prefix with your framework's convention for client-exposed variables (e.g. NEXT_PUBLIC_, VITE_, etc.)
+ # Prefix the variable name with your framework's convention for client-exposed
+ # variables. For Next.js use NEXT_PUBLIC_STACK_PROJECT_ID, for Vite use
+ # VITE_STACK_PROJECT_ID, etc. If your framework has no such convention, use
+ # STACK_PROJECT_ID as-is.
+ STACK_PROJECT_ID=
```
+ This is the **only** environment variable the client SDK reads in the cloud-project setup. Do not invent or add any other Stack Auth env vars on the client (in particular, there is **no** separate publishable / client key — the project ID alone is sufficient on the client).
+
Alternatively, you can also just set the project ID in the `stack/client.ts` file:
```ts src/stack/client.ts
@@ -1021,10 +1051,16 @@ export const onSetupToolClick = (event) => {
Then, copy-paste them into your `.env.local` file (or wherever your environment variables are stored):
```.env .env.local
- STACK_PROJECT_ID= # if desired, prefix with your framework's convention for client-exposed variables (e.g. NEXT_PUBLIC_, VITE_, etc.)
+ # Prefix STACK_PROJECT_ID with your framework's convention for client-exposed
+ # variables (e.g. NEXT_PUBLIC_STACK_PROJECT_ID for Next.js, VITE_STACK_PROJECT_ID
+ # for Vite). STACK_SECRET_SERVER_KEY must NEVER be exposed to the client and
+ # must NOT be prefixed.
+ STACK_PROJECT_ID=
STACK_SECRET_SERVER_KEY=
```
+ These two variables are the **complete** set the SDK reads in the cloud-project setup. Do not add any additional Stack Auth env vars (in particular, there is **no** separate publishable / client key — the project ID alone is sufficient on the client). The dashboard "Project Keys" page exposes exactly these two values; if a third slot is present in any `.env.local` you write, it is wrong.
+
They'll automatically be picked up by the `StackServerApp` constructor.
@@ -1170,9 +1206,15 @@ export const onSetupToolClick = (event) => {
Go to your project's dashboard on [app.stack-auth.com](https://app.stack-auth.com) and get the project ID. You can find it in the URL after the `/projects/` part. Copy-paste it into your `.env.local` file (or wherever your environment variables are stored):
```.env .env.local
- STACK_PROJECT_ID= # if available, prefix with your framework's convention for client-exposed variables (e.g. NEXT_PUBLIC_, VITE_, etc.)
+ # Prefix the variable name with your framework's convention for client-exposed
+ # variables. For Next.js use NEXT_PUBLIC_STACK_PROJECT_ID, for Vite use
+ # VITE_STACK_PROJECT_ID, etc. If your framework has no such convention, use
+ # STACK_PROJECT_ID as-is.
+ STACK_PROJECT_ID=
```
+ This is the **only** environment variable the client SDK reads in the cloud-project setup. Do not invent or add any other Stack Auth env vars on the client (in particular, there is **no** separate publishable / client key — the project ID alone is sufficient on the client).
+
Alternatively, you can also just set the project ID in the `stack/client.ts` file:
```ts src/stack/client.ts
@@ -1190,10 +1232,16 @@ export const onSetupToolClick = (event) => {
Then, copy-paste them into your `.env.local` file (or wherever your environment variables are stored):
```.env .env.local
- STACK_PROJECT_ID= # if desired, prefix with your framework's convention for client-exposed variables (e.g. NEXT_PUBLIC_, VITE_, etc.)
+ # Prefix STACK_PROJECT_ID with your framework's convention for client-exposed
+ # variables (e.g. NEXT_PUBLIC_STACK_PROJECT_ID for Next.js, VITE_STACK_PROJECT_ID
+ # for Vite). STACK_SECRET_SERVER_KEY must NEVER be exposed to the client and
+ # must NOT be prefixed.
+ STACK_PROJECT_ID=
STACK_SECRET_SERVER_KEY=
```
+ These two variables are the **complete** set the SDK reads in the cloud-project setup. Do not add any additional Stack Auth env vars (in particular, there is **no** separate publishable / client key — the project ID alone is sufficient on the client). The dashboard "Project Keys" page exposes exactly these two values; if a third slot is present in any `.env.local` you write, it is wrong.
+
They'll automatically be picked up by the `StackServerApp` constructor.
@@ -1354,9 +1402,15 @@ export const onSetupToolClick = (event) => {
Go to your project's dashboard on [app.stack-auth.com](https://app.stack-auth.com) and get the project ID. You can find it in the URL after the `/projects/` part. Copy-paste it into your `.env.local` file (or wherever your environment variables are stored):
```.env .env.local
- STACK_PROJECT_ID= # if available, prefix with your framework's convention for client-exposed variables (e.g. NEXT_PUBLIC_, VITE_, etc.)
+ # Prefix the variable name with your framework's convention for client-exposed
+ # variables. For Next.js use NEXT_PUBLIC_STACK_PROJECT_ID, for Vite use
+ # VITE_STACK_PROJECT_ID, etc. If your framework has no such convention, use
+ # STACK_PROJECT_ID as-is.
+ STACK_PROJECT_ID=
```
+ This is the **only** environment variable the client SDK reads in the cloud-project setup. Do not invent or add any other Stack Auth env vars on the client (in particular, there is **no** separate publishable / client key — the project ID alone is sufficient on the client).
+
Alternatively, you can also just set the project ID in the `stack/client.ts` file:
```ts src/stack/client.ts
@@ -1374,10 +1428,16 @@ export const onSetupToolClick = (event) => {
Then, copy-paste them into your `.env.local` file (or wherever your environment variables are stored):
```.env .env.local
- STACK_PROJECT_ID= # if desired, prefix with your framework's convention for client-exposed variables (e.g. NEXT_PUBLIC_, VITE_, etc.)
+ # Prefix STACK_PROJECT_ID with your framework's convention for client-exposed
+ # variables (e.g. NEXT_PUBLIC_STACK_PROJECT_ID for Next.js, VITE_STACK_PROJECT_ID
+ # for Vite). STACK_SECRET_SERVER_KEY must NEVER be exposed to the client and
+ # must NOT be prefixed.
+ STACK_PROJECT_ID=
STACK_SECRET_SERVER_KEY=
```
+ These two variables are the **complete** set the SDK reads in the cloud-project setup. Do not add any additional Stack Auth env vars (in particular, there is **no** separate publishable / client key — the project ID alone is sufficient on the client). The dashboard "Project Keys" page exposes exactly these two values; if a third slot is present in any `.env.local` you write, it is wrong.
+
They'll automatically be picked up by the `StackServerApp` constructor.
@@ -1529,9 +1589,15 @@ export const onSetupToolClick = (event) => {
Go to your project's dashboard on [app.stack-auth.com](https://app.stack-auth.com) and get the project ID. You can find it in the URL after the `/projects/` part. Copy-paste it into your `.env.local` file (or wherever your environment variables are stored):
```.env .env.local
- STACK_PROJECT_ID= # if available, prefix with your framework's convention for client-exposed variables (e.g. NEXT_PUBLIC_, VITE_, etc.)
+ # Prefix the variable name with your framework's convention for client-exposed
+ # variables. For Next.js use NEXT_PUBLIC_STACK_PROJECT_ID, for Vite use
+ # VITE_STACK_PROJECT_ID, etc. If your framework has no such convention, use
+ # STACK_PROJECT_ID as-is.
+ STACK_PROJECT_ID=
```
+ This is the **only** environment variable the client SDK reads in the cloud-project setup. Do not invent or add any other Stack Auth env vars on the client (in particular, there is **no** separate publishable / client key — the project ID alone is sufficient on the client).
+
Alternatively, you can also just set the project ID in the `stack/client.ts` file:
```ts src/stack/client.ts
@@ -1549,10 +1615,16 @@ export const onSetupToolClick = (event) => {
Then, copy-paste them into your `.env.local` file (or wherever your environment variables are stored):
```.env .env.local
- STACK_PROJECT_ID= # if desired, prefix with your framework's convention for client-exposed variables (e.g. NEXT_PUBLIC_, VITE_, etc.)
+ # Prefix STACK_PROJECT_ID with your framework's convention for client-exposed
+ # variables (e.g. NEXT_PUBLIC_STACK_PROJECT_ID for Next.js, VITE_STACK_PROJECT_ID
+ # for Vite). STACK_SECRET_SERVER_KEY must NEVER be exposed to the client and
+ # must NOT be prefixed.
+ STACK_PROJECT_ID=
STACK_SECRET_SERVER_KEY=
```
+ These two variables are the **complete** set the SDK reads in the cloud-project setup. Do not add any additional Stack Auth env vars (in particular, there is **no** separate publishable / client key — the project ID alone is sufficient on the client). The dashboard "Project Keys" page exposes exactly these two values; if a third slot is present in any `.env.local` you write, it is wrong.
+
They'll automatically be picked up by the `StackServerApp` constructor.
diff --git a/docs-mintlify/snippets/home-prompt-island.jsx b/docs-mintlify/snippets/home-prompt-island.jsx
index 095afae9c1..ab321e7a8a 100644
--- a/docs-mintlify/snippets/home-prompt-island.jsx
+++ b/docs-mintlify/snippets/home-prompt-island.jsx
@@ -1,6 +1,6 @@
// This file is auto-generated by scripts/generate-setup-prompt-docs.ts. Do not edit it manually; edit packages/stack-shared/src/ai/prompts.ts instead.
-export const generatedSetupPromptText = "# Setting up Stack Auth\n\nThis prompt explains how to set up Stack Auth in your project.\n\nTo use it, you can use the sections below to set up Stack Auth in the project. For example, if you are setting up a Svelte project, you would follow the SDK setup instructions for a frontend JS project.\n\n## SDK Setup Instructions\n\nFollow these instructions in order to set up and get started with the Stack Auth SDK in various languages.\n\nNot all steps are applicable to every type of application; for example, React apps have some extra steps that are not needed with other frameworks.\n\nThe frameworks and languages with explicit SDK support are:\n\n- Next.js\n- React\n- Other JS & TS (both frontend and backend)\n\n\n \n Stack Auth has SDKs for various languages, frameworks, and libraries. Use the most specific package each, so, for example, even though a Next.js project uses both Next.js and React, use the Next.js package. If a programming language is not supported entirely, you may have to use the REST API to interface with Stack Auth.\n \n #### JavaScript & TypeScript\n \n For JS & TS, the following packages are available:\n \n - Next.js: `@stackframe/stack`\n - React: `@stackframe/react`\n - Other & vanilla JS: `@stackframe/js`\n \n You can install the correct JavaScript Stack Auth SDK into your project by running the following command:\n\n ```sh\n npm i \n # or: pnpm i \n # or: yarn add \n # or: bun add \n ```\n \n \n \n Next, let us create the Stack App object for your project. This is the most important object in a Stack Auth project.\n\n In a frontend where you cannot keep a secret key safe, you would use the `StackClientApp` constructor:\n \n ```ts src/stack/client.ts\n import { StackClientApp } from \"\";\n \n export const stackClientApp = new StackClientApp({\n tokenStore: \"cookie\", // \"nextjs-cookie\" for Next.js, \"cookie\" for other web frontends, null for backend environments\n });\n ```\n\n In a backend where you can keep a secret key safe, you can use the `StackServerApp`, which provides access to more sensitive APIs compared to `StackClientApp`:\n \n ```ts src/stack/server.ts\n import { StackServerApp } from \"\";\n \n export const stackServerApp = new StackServerApp({\n tokenStore: null,\n });\n ```\n \n In frameworks that are both front- and backend, like Next.js, you can also create a `StackServerApp` from a `StackClientApp` object:\n \n ```ts src/stack/server.ts\n import { StackServerApp } from \"\";\n import { stackClientApp } from \"./client\";\n \n export const stackServerApp = new StackServerApp({\n inheritsFrom: stackClientApp,\n });\n ```\n \n Note that the secret server key should **never** be exposed to the client, as it can be used to read and write everything in your Stack Auth project. In web frontends or bundled applications, you should therefore always only ever create a `StackClientApp` object.\n \n\n \n It's now time to create a development setup for Stack Auth.\n\n You can either run Stack Auth locally, or connect to a project hosted in the cloud.\n\n If you already use Stack Auth for your product, we recommend you re-use the same project to share your configuration between the two.\n\n \n \n First, create a `stack.config.ts` configuration file in the root directory of the workspace (or anywhere else):\n\n ```ts stack.config.ts\n import type { StackConfig } from \"\";\n\n // default: show-onboarding, which shows the onboarding flow for this project when Stack Auth starts\n export const config: StackConfig = \"show-onboarding\";\n ```\n\n To run your application with Stack Auth, you then need to start the emulator and set environment variables expected by your application. The `emulator run` CLI command does both of these, so you can simply wrap your existing `dev` script in your package.json:\n\n ```json package.json\n {\n // ...\n \"scripts\": {\n // ...\n \"dev\": \"npx @stackframe/stack-cli emulator run --config-file ./stack.config.ts -- \"\n }\n }\n ```\n \n\n \n Note: If you're an AI agent, and you don't already have the information you need from the Cloud project, you may have to ask the user for help on this step. You can either ask them to provide the environment variables, or just leave them empty for now and ask the user to complete them at the end.\n\n If you'd rather run your development environment on our infrastructure, or you already have an existing product, you can also connect a cloud project.\n\n This process is slightly different depending on whether you're setting up a frontend or a backend (whether your app can keep a secret key safe or not).\n\n #### Frontend\n\n Go to your project's dashboard on [app.stack-auth.com](https://app.stack-auth.com) and get the project ID. You can find it in the URL after the `/projects/` part. Copy-paste it into your `.env.local` file (or wherever your environment variables are stored):\n\n ```.env .env.local\n STACK_PROJECT_ID= # if available, prefix with your framework's convention for client-exposed variables (e.g. NEXT_PUBLIC_, VITE_, etc.)\n ```\n\n Alternatively, you can also just set the project ID in the `stack/client.ts` file:\n\n ```ts src/stack/client.ts\n export const stackClientApp = new StackClientApp({\n // ...\n projectId: \"your-project-id\",\n });\n ```\n\n\n #### Backend (or both frontend and backend)\n\n First, navigate to the [Project Keys](https://app.stack-auth.com/projects/-selector-/project-keys) page in the Stack Auth dashboard and generate a new set of keys.\n\n Then, copy-paste them into your `.env.local` file (or wherever your environment variables are stored):\n\n ```.env .env.local\n STACK_PROJECT_ID= # if desired, prefix with your framework's convention for client-exposed variables (e.g. NEXT_PUBLIC_, VITE_, etc.)\n STACK_SECRET_SERVER_KEY=\n ```\n\n They'll automatically be picked up by the `StackServerApp` constructor.\n \n \n \n\n and \">\n In React frameworks, Stack Auth provides `StackProvider` and `StackTheme` components that should wrap your entire app at the root level.\n \n For example, if you have an `App.tsx` file, update it as follows:\n \n ```tsx src/App.tsx\n import { StackProvider, StackTheme } from \"\";\n import { stackClientApp } from \"./stack/client\";\n \n export default function App() {\n return (\n \n \n {/* your app content */}\n \n \n );\n }\n ```\n \n For Next.js specifically: You can do this in the `layout.tsx` file in the `app` directory:\n \n ```tsx src/app/layout.tsx\n import { Suspense } from \"react\";\n import { StackProvider, StackTheme } from \"\";\n import { stackServerApp } from \"@/stack/server\";\n \n export default function RootLayout({ children }: { children: React.ReactNode }) {\n return (\n \n \n {children}\n \n \n );\n }\n ```\n \n \n \n Stack Auth also provides additional `useXyz` React hooks for `getXyz`/`listXyz` functions. For example, `useUser` is like `getUser`, but as a suspending React hook.\n \n To support the suspension, you need to add a suspense boundary around your app.\n \n The easiest way to do this is to just wrap your entire app in a `Suspense` component:\n \n ```tsx src/App.tsx\n import { Suspense } from \"react\";\n import { StackProvider, StackTheme } from \"\";\n import { stackClientApp } from \"./stack/client\";\n \n export default function App() {\n return (\n Loading...}>\n \n \n {/* your app content */}\n \n \n \n );\n }\n ```\n \n In Next.js, this can be easily done by adding a `loading.tsx` file in the `app` directory:\n \n ```tsx src/app/loading.tsx\n export default function Loading() {\n return
Loading...
;\n }\n ```\n \n Note: If you are an AI agent, make sure to make the loading indicator visually appealing and match the design of your app, instead of the example that just says \"Loading...\".\n \n\n \n You are now ready to use the Stack Auth SDK. If you have any frontends calling your backend endpoints, you may want to pass along the Stack Auth tokens in a header such that you can access the same user object on your backend.\n \n The most ergonomic way to do this is to pass the result of `stackClientApp.getAuthorizationHeader()` as the `Authorization` header into your backend endpoints when the user is signed in:\n \n ```ts\n // NOTE: This is your frontend's code\n const authorizationHeader = await stackClientApp.getAuthorizationHeader();\n const response = await fetch(\"/my-backend-endpoint\", {\n headers: {\n ...(authorizationHeader ? { Authorization: authorizationHeader } : {}),\n },\n });\n // ...\n ```\n \n In most backend frameworks you can then access the user object by passing the request object as a `tokenStore` of the functions that access the user object:\n \n ```ts\n // NOTE: This is your backend's code\n const user = await stackServerApp.getUser({ tokenStore: request });\n return new Response(\"Hello, \" + user.displayName, { headers: { \"Cache-Control\": \"private, no-store\" } });\n ```\n \n This will work as long as `request` is an object that follows the shape `{ headers: Record | { get: (name: string) => string | null } }`.\n \n \n Make sure that HTTP caching is disabled with `Cache-Control: private, no-store` for authenticated backend endpoints.\n \n \n If you cannot use `getAuthorizationHeader()`, for example because you are using a protocol other than HTTP, you can use `getAuthJson()` instead:\n \n ```ts\n // Frontend:\n await rpcCall(\"my-rpc-endpoint\", {\n data: {\n auth: await stackClientApp.getAuthJson(),\n },\n });\n \n // Backend:\n const user = await stackServerApp.getUser({ tokenStore: data.auth });\n return new RpcResponse(\"Hello, \" + user.displayName);\n ```\n \n\n \n\n\n## MCP Setup\n\n\n This prompt is not yet implemented.\n\n\n\n \n Install the MCP package:\n \n \n\n\n## Convex Setup\n\nFollow these instructions to integrate Stack Auth with Convex.\n\n\n \n If the project does not already use Convex, initialize a Convex + Next.js app:\n\n ```sh\n npm create convex@latest\n ```\n\n When prompted, choose **Next.js** and **No auth**. Stack Auth will provide auth.\n\n During development, run the Convex backend and the app dev server:\n\n ```sh\n npx convex dev\n npm run dev\n ```\n \n\n \n Install Stack Auth in the app. If you have not already completed the SDK setup steps above, run the setup wizard:\n\n ```sh\n npx @stackframe/stack-cli@latest init\n ```\n\n Create or select a Stack Auth project in the dashboard. Copy the Stack Auth environment variables into the app's `.env.local` file.\n\n Also add the same Stack Auth environment variables to the Convex deployment environment in the Convex dashboard.\n \n\n \n Create or update `convex/auth.config.ts`:\n\n ```ts convex/auth.config.ts\n import { getConvexProvidersConfig } from \"@stackframe/js\";\n // or: import { getConvexProvidersConfig } from \"@stackframe/react\";\n // or: import { getConvexProvidersConfig } from \"@stackframe/stack\";\n\n export default {\n providers: getConvexProvidersConfig({\n projectId: process.env.STACK_PROJECT_ID, // or process.env.NEXT_PUBLIC_STACK_PROJECT_ID\n }),\n };\n ```\n \n\n \n Update the Convex client setup so Convex receives Stack Auth tokens.\n\n In browser JavaScript:\n\n ```ts\n convexClient.setAuth(stackClientApp.getConvexClientAuth({}));\n ```\n\n In React:\n\n ```ts\n convexReactClient.setAuth(stackClientApp.getConvexClientAuth({}));\n ```\n\n For Convex HTTP clients on the server, pass a request-like token store:\n\n ```ts\n convexHttpClient.setAuth(stackClientApp.getConvexHttpClientAuth({ tokenStore: requestObject }));\n ```\n \n\n \n In Convex queries and mutations, use Stack Auth's Convex integration to read the current user.\n\n ```ts convex/myFunctions.ts\n import { query } from \"./_generated/server\";\n import { stackServerApp } from \"../src/stack/server\";\n\n export const myQuery = query({\n handler: async (ctx, args) => {\n const user = await stackServerApp.getPartialUser({ from: \"convex\", ctx });\n return user;\n },\n });\n ```\n \n\n \n\n\n## Supabase Setup\n\n\n This setup covers Supabase Row Level Security (RLS) with Stack Auth JWTs. It does not sync user data between Supabase and Stack Auth. Use Stack Auth webhooks if you need data sync.\n\n\n\n \n In the Supabase SQL editor, enable Row Level Security for your tables and write policies based on Supabase JWT claims.\n\n For example, this sample table demonstrates public rows, authenticated rows, and user-owned rows:\n\n ```sql\n CREATE TABLE data (\n id bigint PRIMARY KEY,\n text text NOT NULL,\n user_id UUID\n );\n\n INSERT INTO data (id, text, user_id) VALUES\n (1, 'Everyone can see this', NULL),\n (2, 'Only authenticated users can see this', NULL),\n (3, 'Only user with specific id can see this', NULL);\n\n ALTER TABLE data ENABLE ROW LEVEL SECURITY;\n\n CREATE POLICY \"Public read\" ON \"public\".\"data\" TO public\n USING (id = 1);\n\n CREATE POLICY \"Authenticated access\" ON \"public\".\"data\" TO authenticated\n USING (id = 2);\n\n CREATE POLICY \"User access\" ON \"public\".\"data\" TO authenticated\n USING (id = 3 AND auth.uid() = user_id);\n ```\n \n\n \n If you are starting from scratch with Next.js, you can use Supabase's template and then initialize Stack Auth:\n\n ```sh\n npx create-next-app@latest -e with-supabase stack-supabase\n cd stack-supabase\n npx @stackframe/stack-cli@latest init\n ```\n\n Add the Supabase environment variables to `.env.local`:\n\n ```.env .env.local\n NEXT_PUBLIC_SUPABASE_URL=\n NEXT_PUBLIC_SUPABASE_ANON_KEY=\n SUPABASE_JWT_SECRET=\n ```\n\n Also add the Stack Auth environment variables:\n\n ```.env .env.local\n NEXT_PUBLIC_STACK_PROJECT_ID=\n NEXT_PUBLIC_STACK_PUBLISHABLE_CLIENT_KEY=\n STACK_SECRET_SERVER_KEY=\n ```\n \n\n \n Create a server action that signs a Supabase JWT using the current Stack Auth user ID:\n\n ```tsx utils/actions.ts\n 'use server';\n\n import { stackServerApp } from \"@/stack/server\";\n import * as jose from \"jose\";\n\n export const getSupabaseJwt = async () => {\n const user = await stackServerApp.getUser();\n\n if (!user) {\n return null;\n }\n\n const token = await new jose.SignJWT({\n sub: user.id,\n role: \"authenticated\",\n })\n .setProtectedHeader({ alg: \"HS256\" })\n .setIssuedAt()\n .setExpirationTime(\"1h\")\n .sign(new TextEncoder().encode(process.env.SUPABASE_JWT_SECRET));\n\n return token;\n };\n ```\n \n\n \n Create a helper that passes the server-generated JWT to Supabase:\n\n ```tsx utils/supabase-client.ts\n import { createBrowserClient } from \"@supabase/ssr\";\n import { getSupabaseJwt } from \"./actions\";\n\n export const createSupabaseClient = () => {\n return createBrowserClient(\n process.env.NEXT_PUBLIC_SUPABASE_URL!,\n process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!,\n { accessToken: async () => await getSupabaseJwt() || \"\" },\n );\n };\n ```\n \n\n \n Use the Supabase client from your UI. The RLS policies will decide which rows the user can read based on the Stack Auth user ID embedded in the Supabase JWT.\n\n ```tsx app/page.tsx\n 'use client';\n\n import { createSupabaseClient } from \"@/utils/supabase-client\";\n import { useStackApp, useUser } from \"@stackframe/stack\";\n import Link from \"next/link\";\n import { useEffect, useState } from \"react\";\n\n export default function Page() {\n const app = useStackApp();\n const user = useUser();\n const supabase = createSupabaseClient();\n const [data, setData] = useState(null);\n\n useEffect(() => {\n supabase.from(\"data\").select().then(({ data }) => setData(data ?? []));\n }, []);\n\n const listContent = data === null\n ?
Loading...
\n : data.length === 0\n ?
No notes found
\n : data.map((note) =>
{note.text}
);\n\n return (\n
\n {user ? (\n <>\n
You are signed in
\n
User ID: {user.id}
\n Sign Out\n \n ) : (\n Sign In\n )}\n
Supabase data
\n
{listContent}
\n
\n );\n }\n ```\n \n\n \n\n\n## CLI Setup\n\nFollow these instructions to authenticate users in a command line application with Stack Auth.\n\n\n \n Download the Stack Auth CLI authentication template and place it in your project. For Python apps, copy it as `stack_auth_cli_template.py`.\n\n Example project layout:\n\n ```text\n my-python-app/\n ├─ main.py\n └─ stack_auth_cli_template.py\n ```\n \n\n \n Import and call `prompt_cli_login`. It opens the browser, lets the user authenticate, and returns a refresh token.\n\n ```py main.py\n from stack_auth_cli_template import prompt_cli_login\n\n refresh_token = prompt_cli_login(\n app_url=\"https://your-app-url.example.com\",\n project_id=\"your-project-id-here\",\n publishable_client_key=\"your-publishable-client-key-here\",\n )\n\n if refresh_token is None:\n print(\"User cancelled the login process. Exiting\")\n exit(1)\n ```\n\n You can store the refresh token in a local file or keychain and only prompt the user again when no saved refresh token exists.\n \n\n \n Use the refresh token with Stack Auth's REST API to get an access token.\n\n ```py\n def get_access_token(refresh_token):\n access_token_response = stack_auth_request(\n \"post\",\n \"/api/v1/auth/sessions/current/refresh\",\n headers={\n \"x-stack-refresh-token\": refresh_token,\n },\n )\n\n return access_token_response[\"access_token\"]\n ```\n \n\n \n Use the access token to call the Stack Auth REST API as the logged-in user.\n\n ```py\n def get_user_object(access_token):\n return stack_auth_request(\n \"get\",\n \"/api/v1/users/me\",\n headers={\n \"x-stack-access-token\": access_token,\n },\n )\n\n user = get_user_object(get_access_token(refresh_token))\n print(\"The user is logged in as\", user[\"display_name\"] or user[\"primary_email\"])\n ```\n \n\n \n";
+export const generatedSetupPromptText = "# Setting up Stack Auth\n\nThis prompt explains how to set up Stack Auth in your project.\n\nTo use it, you can use the sections below to set up Stack Auth in the project. For example, if you are setting up a Svelte project, you would follow the SDK setup instructions for a frontend JS project.\n\n## SDK Setup Instructions\n\nFollow these instructions in order to set up and get started with the Stack Auth SDK in various languages.\n\nNot all steps are applicable to every type of application; for example, React apps have some extra steps that are not needed with other frameworks.\n\nThe frameworks and languages with explicit SDK support are:\n\n- Next.js\n- React\n- Other JS & TS (both frontend and backend)\n\n\n \n Stack Auth has SDKs for various languages, frameworks, and libraries. Use the most specific package each, so, for example, even though a Next.js project uses both Next.js and React, use the Next.js package. If a programming language is not supported entirely, you may have to use the REST API to interface with Stack Auth.\n \n #### JavaScript & TypeScript\n \n For JS & TS, the following packages are available:\n \n - Next.js: `@stackframe/stack`\n - React: `@stackframe/react`\n - Other & vanilla JS: `@stackframe/js`\n \n You can install the correct JavaScript Stack Auth SDK into your project by running the following command:\n\n ```sh\n npm i \n # or: pnpm i \n # or: yarn add \n # or: bun add \n ```\n \n \n \n Next, let us create the Stack App object for your project. This is the most important object in a Stack Auth project.\n\n In a frontend where you cannot keep a secret key safe, you would use the `StackClientApp` constructor:\n \n ```ts src/stack/client.ts\n import { StackClientApp } from \"\";\n \n export const stackClientApp = new StackClientApp({\n tokenStore: \"cookie\", // \"nextjs-cookie\" for Next.js, \"cookie\" for other web frontends, null for backend environments\n });\n ```\n\n In a backend where you can keep a secret key safe, you can use the `StackServerApp`, which provides access to more sensitive APIs compared to `StackClientApp`:\n \n ```ts src/stack/server.ts\n import { StackServerApp } from \"\";\n \n export const stackServerApp = new StackServerApp({\n tokenStore: null,\n });\n ```\n \n In frameworks that are both front- and backend, like Next.js, you can also create a `StackServerApp` from a `StackClientApp` object:\n \n ```ts src/stack/server.ts\n import { StackServerApp } from \"\";\n import { stackClientApp } from \"./client\";\n \n export const stackServerApp = new StackServerApp({\n inheritsFrom: stackClientApp,\n });\n ```\n \n Note that the secret server key should **never** be exposed to the client, as it can be used to read and write everything in your Stack Auth project. In web frontends or bundled applications, you should therefore always only ever create a `StackClientApp` object.\n \n\n \n It's now time to create a development setup for Stack Auth.\n\n You can either run Stack Auth locally, or connect to a project hosted in the cloud.\n\n If you already use Stack Auth for your product, we recommend you re-use the same project to share your configuration between the two.\n\n \n \n First, create a `stack.config.ts` configuration file in the root directory of the workspace (or anywhere else):\n\n ```ts stack.config.ts\n import type { StackConfig } from \"\";\n\n // default: show-onboarding, which shows the onboarding flow for this project when Stack Auth starts\n export const config: StackConfig = \"show-onboarding\";\n ```\n\n To run your application with Stack Auth, you then need to start the emulator and set environment variables expected by your application. The `emulator run` CLI command does both of these, so you can simply wrap your existing `dev` script in your package.json:\n\n ```json package.json\n {\n // ...\n \"scripts\": {\n // ...\n \"dev\": \"npx @stackframe/stack-cli emulator run --config-file ./stack.config.ts -- \"\n }\n }\n ```\n \n\n \n Note: If you're an AI agent, and you don't already have the information you need from the Cloud project, you may have to ask the user for help on this step. You can either ask them to provide the environment variables, or just leave them empty for now and ask the user to complete them at the end.\n\n If you'd rather run your development environment on our infrastructure, or you already have an existing product, you can also connect a cloud project.\n\n This process is slightly different depending on whether you're setting up a frontend or a backend (whether your app can keep a secret key safe or not).\n\n #### Frontend\n\n Go to your project's dashboard on [app.stack-auth.com](https://app.stack-auth.com) and get the project ID. You can find it in the URL after the `/projects/` part. Copy-paste it into your `.env.local` file (or wherever your environment variables are stored):\n\n ```.env .env.local\n # Prefix the variable name with your framework's convention for client-exposed\n # variables. For Next.js use NEXT_PUBLIC_STACK_PROJECT_ID, for Vite use\n # VITE_STACK_PROJECT_ID, etc. If your framework has no such convention, use\n # STACK_PROJECT_ID as-is.\n STACK_PROJECT_ID=\n ```\n\n This is the **only** environment variable the client SDK reads in the cloud-project setup. Do not invent or add any other Stack Auth env vars on the client (in particular, there is **no** separate publishable / client key — the project ID alone is sufficient on the client).\n\n Alternatively, you can also just set the project ID in the `stack/client.ts` file:\n\n ```ts src/stack/client.ts\n export const stackClientApp = new StackClientApp({\n // ...\n projectId: \"your-project-id\",\n });\n ```\n\n\n #### Backend (or both frontend and backend)\n\n First, navigate to the [Project Keys](https://app.stack-auth.com/projects/-selector-/project-keys) page in the Stack Auth dashboard and generate a new set of keys.\n\n Then, copy-paste them into your `.env.local` file (or wherever your environment variables are stored):\n\n ```.env .env.local\n # Prefix STACK_PROJECT_ID with your framework's convention for client-exposed\n # variables (e.g. NEXT_PUBLIC_STACK_PROJECT_ID for Next.js, VITE_STACK_PROJECT_ID\n # for Vite). STACK_SECRET_SERVER_KEY must NEVER be exposed to the client and\n # must NOT be prefixed.\n STACK_PROJECT_ID=\n STACK_SECRET_SERVER_KEY=\n ```\n\n These two variables are the **complete** set the SDK reads in the cloud-project setup. Do not add any additional Stack Auth env vars (in particular, there is **no** separate publishable / client key — the project ID alone is sufficient on the client). The dashboard \"Project Keys\" page exposes exactly these two values; if a third slot is present in any `.env.local` you write, it is wrong.\n\n They'll automatically be picked up by the `StackServerApp` constructor.\n \n \n \n\n and \">\n In React frameworks, Stack Auth provides `StackProvider` and `StackTheme` components that should wrap your entire app at the root level.\n \n For example, if you have an `App.tsx` file, update it as follows:\n \n ```tsx src/App.tsx\n import { StackProvider, StackTheme } from \"\";\n import { stackClientApp } from \"./stack/client\";\n \n export default function App() {\n return (\n \n \n {/* your app content */}\n \n \n );\n }\n ```\n \n For Next.js specifically: You can do this in the `layout.tsx` file in the `app` directory:\n \n ```tsx src/app/layout.tsx\n import { Suspense } from \"react\";\n import { StackProvider, StackTheme } from \"\";\n import { stackServerApp } from \"@/stack/server\";\n \n export default function RootLayout({ children }: { children: React.ReactNode }) {\n return (\n \n \n {children}\n \n \n );\n }\n ```\n \n \n \n Stack Auth also provides additional `useXyz` React hooks for `getXyz`/`listXyz` functions. For example, `useUser` is like `getUser`, but as a suspending React hook.\n \n To support the suspension, you need to add a suspense boundary around your app.\n \n The easiest way to do this is to just wrap your entire app in a `Suspense` component:\n \n ```tsx src/App.tsx\n import { Suspense } from \"react\";\n import { StackProvider, StackTheme } from \"\";\n import { stackClientApp } from \"./stack/client\";\n \n export default function App() {\n return (\n Loading...}>\n \n \n {/* your app content */}\n \n \n \n );\n }\n ```\n \n In Next.js, this can be easily done by adding a `loading.tsx` file in the `app` directory:\n \n ```tsx src/app/loading.tsx\n export default function Loading() {\n return
Loading...
;\n }\n ```\n \n Note: If you are an AI agent, make sure to make the loading indicator visually appealing and match the design of your app, instead of the example that just says \"Loading...\".\n \n\n \n You are now ready to use the Stack Auth SDK. If you have any frontends calling your backend endpoints, you may want to pass along the Stack Auth tokens in a header such that you can access the same user object on your backend.\n \n The most ergonomic way to do this is to pass the result of `stackClientApp.getAuthorizationHeader()` as the `Authorization` header into your backend endpoints when the user is signed in:\n \n ```ts\n // NOTE: This is your frontend's code\n const authorizationHeader = await stackClientApp.getAuthorizationHeader();\n const response = await fetch(\"/my-backend-endpoint\", {\n headers: {\n ...(authorizationHeader ? { Authorization: authorizationHeader } : {}),\n },\n });\n // ...\n ```\n \n In most backend frameworks you can then access the user object by passing the request object as a `tokenStore` of the functions that access the user object:\n \n ```ts\n // NOTE: This is your backend's code\n const user = await stackServerApp.getUser({ tokenStore: request });\n return new Response(\"Hello, \" + user.displayName, { headers: { \"Cache-Control\": \"private, no-store\" } });\n ```\n \n This will work as long as `request` is an object that follows the shape `{ headers: Record | { get: (name: string) => string | null } }`.\n \n \n Make sure that HTTP caching is disabled with `Cache-Control: private, no-store` for authenticated backend endpoints.\n \n \n If you cannot use `getAuthorizationHeader()`, for example because you are using a protocol other than HTTP, you can use `getAuthJson()` instead:\n \n ```ts\n // Frontend:\n await rpcCall(\"my-rpc-endpoint\", {\n data: {\n auth: await stackClientApp.getAuthJson(),\n },\n });\n \n // Backend:\n const user = await stackServerApp.getUser({ tokenStore: data.auth });\n return new RpcResponse(\"Hello, \" + user.displayName);\n ```\n \n\n \n\n\n## MCP Setup\n\n\n This prompt is not yet implemented.\n\n\n\n \n Install the MCP package:\n \n \n\n\n## Convex Setup\n\nFollow these instructions to integrate Stack Auth with Convex.\n\n\n \n If the project does not already use Convex, initialize a Convex + Next.js app:\n\n ```sh\n npm create convex@latest\n ```\n\n When prompted, choose **Next.js** and **No auth**. Stack Auth will provide auth.\n\n During development, run the Convex backend and the app dev server:\n\n ```sh\n npx convex dev\n npm run dev\n ```\n \n\n \n Install Stack Auth in the app. If you have not already completed the SDK setup steps above, run the setup wizard:\n\n ```sh\n npx @stackframe/stack-cli@latest init\n ```\n\n Create or select a Stack Auth project in the dashboard. Copy the Stack Auth environment variables into the app's `.env.local` file.\n\n Also add the same Stack Auth environment variables to the Convex deployment environment in the Convex dashboard.\n \n\n \n Create or update `convex/auth.config.ts`:\n\n ```ts convex/auth.config.ts\n import { getConvexProvidersConfig } from \"@stackframe/js\";\n // or: import { getConvexProvidersConfig } from \"@stackframe/react\";\n // or: import { getConvexProvidersConfig } from \"@stackframe/stack\";\n\n export default {\n providers: getConvexProvidersConfig({\n projectId: process.env.STACK_PROJECT_ID, // or process.env.NEXT_PUBLIC_STACK_PROJECT_ID\n }),\n };\n ```\n \n\n \n Update the Convex client setup so Convex receives Stack Auth tokens.\n\n In browser JavaScript:\n\n ```ts\n convexClient.setAuth(stackClientApp.getConvexClientAuth({}));\n ```\n\n In React:\n\n ```ts\n convexReactClient.setAuth(stackClientApp.getConvexClientAuth({}));\n ```\n\n For Convex HTTP clients on the server, pass a request-like token store:\n\n ```ts\n convexHttpClient.setAuth(stackClientApp.getConvexHttpClientAuth({ tokenStore: requestObject }));\n ```\n \n\n \n In Convex queries and mutations, use Stack Auth's Convex integration to read the current user.\n\n ```ts convex/myFunctions.ts\n import { query } from \"./_generated/server\";\n import { stackServerApp } from \"../src/stack/server\";\n\n export const myQuery = query({\n handler: async (ctx, args) => {\n const user = await stackServerApp.getPartialUser({ from: \"convex\", ctx });\n return user;\n },\n });\n ```\n \n\n \n\n\n## Supabase Setup\n\n\n This setup covers Supabase Row Level Security (RLS) with Stack Auth JWTs. It does not sync user data between Supabase and Stack Auth. Use Stack Auth webhooks if you need data sync.\n\n\n\n \n In the Supabase SQL editor, enable Row Level Security for your tables and write policies based on Supabase JWT claims.\n\n For example, this sample table demonstrates public rows, authenticated rows, and user-owned rows:\n\n ```sql\n CREATE TABLE data (\n id bigint PRIMARY KEY,\n text text NOT NULL,\n user_id UUID\n );\n\n INSERT INTO data (id, text, user_id) VALUES\n (1, 'Everyone can see this', NULL),\n (2, 'Only authenticated users can see this', NULL),\n (3, 'Only user with specific id can see this', NULL);\n\n ALTER TABLE data ENABLE ROW LEVEL SECURITY;\n\n CREATE POLICY \"Public read\" ON \"public\".\"data\" TO public\n USING (id = 1);\n\n CREATE POLICY \"Authenticated access\" ON \"public\".\"data\" TO authenticated\n USING (id = 2);\n\n CREATE POLICY \"User access\" ON \"public\".\"data\" TO authenticated\n USING (id = 3 AND auth.uid() = user_id);\n ```\n \n\n \n If you are starting from scratch with Next.js, you can use Supabase's template and then initialize Stack Auth:\n\n ```sh\n npx create-next-app@latest -e with-supabase stack-supabase\n cd stack-supabase\n npx @stackframe/stack-cli@latest init\n ```\n\n Add the Supabase environment variables to `.env.local`:\n\n ```.env .env.local\n NEXT_PUBLIC_SUPABASE_URL=\n NEXT_PUBLIC_SUPABASE_ANON_KEY=\n SUPABASE_JWT_SECRET=\n ```\n\n Also add the Stack Auth environment variables:\n\n ```.env .env.local\n NEXT_PUBLIC_STACK_PROJECT_ID=\n NEXT_PUBLIC_STACK_PUBLISHABLE_CLIENT_KEY=\n STACK_SECRET_SERVER_KEY=\n ```\n \n\n \n Create a server action that signs a Supabase JWT using the current Stack Auth user ID:\n\n ```tsx utils/actions.ts\n 'use server';\n\n import { stackServerApp } from \"@/stack/server\";\n import * as jose from \"jose\";\n\n export const getSupabaseJwt = async () => {\n const user = await stackServerApp.getUser();\n\n if (!user) {\n return null;\n }\n\n const token = await new jose.SignJWT({\n sub: user.id,\n role: \"authenticated\",\n })\n .setProtectedHeader({ alg: \"HS256\" })\n .setIssuedAt()\n .setExpirationTime(\"1h\")\n .sign(new TextEncoder().encode(process.env.SUPABASE_JWT_SECRET));\n\n return token;\n };\n ```\n \n\n \n Create a helper that passes the server-generated JWT to Supabase:\n\n ```tsx utils/supabase-client.ts\n import { createBrowserClient } from \"@supabase/ssr\";\n import { getSupabaseJwt } from \"./actions\";\n\n export const createSupabaseClient = () => {\n return createBrowserClient(\n process.env.NEXT_PUBLIC_SUPABASE_URL!,\n process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!,\n { accessToken: async () => await getSupabaseJwt() || \"\" },\n );\n };\n ```\n \n\n \n Use the Supabase client from your UI. The RLS policies will decide which rows the user can read based on the Stack Auth user ID embedded in the Supabase JWT.\n\n ```tsx app/page.tsx\n 'use client';\n\n import { createSupabaseClient } from \"@/utils/supabase-client\";\n import { useStackApp, useUser } from \"@stackframe/stack\";\n import Link from \"next/link\";\n import { useEffect, useState } from \"react\";\n\n export default function Page() {\n const app = useStackApp();\n const user = useUser();\n const supabase = createSupabaseClient();\n const [data, setData] = useState(null);\n\n useEffect(() => {\n supabase.from(\"data\").select().then(({ data }) => setData(data ?? []));\n }, []);\n\n const listContent = data === null\n ?
Loading...
\n : data.length === 0\n ?
No notes found
\n : data.map((note) =>
{note.text}
);\n\n return (\n
\n {user ? (\n <>\n
You are signed in
\n
User ID: {user.id}
\n Sign Out\n \n ) : (\n Sign In\n )}\n
Supabase data
\n
{listContent}
\n
\n );\n }\n ```\n \n\n \n\n\n## CLI Setup\n\nFollow these instructions to authenticate users in a command line application with Stack Auth.\n\n\n \n Download the Stack Auth CLI authentication template and place it in your project. For Python apps, copy it as `stack_auth_cli_template.py`.\n\n Example project layout:\n\n ```text\n my-python-app/\n ├─ main.py\n └─ stack_auth_cli_template.py\n ```\n \n\n \n Import and call `prompt_cli_login`. It opens the browser, lets the user authenticate, and returns a refresh token.\n\n ```py main.py\n from stack_auth_cli_template import prompt_cli_login\n\n refresh_token = prompt_cli_login(\n app_url=\"https://your-app-url.example.com\",\n project_id=\"your-project-id-here\",\n publishable_client_key=\"your-publishable-client-key-here\",\n )\n\n if refresh_token is None:\n print(\"User cancelled the login process. Exiting\")\n exit(1)\n ```\n\n You can store the refresh token in a local file or keychain and only prompt the user again when no saved refresh token exists.\n \n\n \n Use the refresh token with Stack Auth's REST API to get an access token.\n\n ```py\n def get_access_token(refresh_token):\n access_token_response = stack_auth_request(\n \"post\",\n \"/api/v1/auth/sessions/current/refresh\",\n headers={\n \"x-stack-refresh-token\": refresh_token,\n },\n )\n\n return access_token_response[\"access_token\"]\n ```\n \n\n \n Use the access token to call the Stack Auth REST API as the logged-in user.\n\n ```py\n def get_user_object(access_token):\n return stack_auth_request(\n \"get\",\n \"/api/v1/users/me\",\n headers={\n \"x-stack-access-token\": access_token,\n },\n )\n\n user = get_user_object(get_access_token(refresh_token))\n print(\"The user is logged in as\", user[\"display_name\"] or user[\"primary_email\"])\n ```\n \n\n \n";
export const setupToolIds = ["nextjs","react","js","tanstack-start","tanstack-query","nodejs","bun","convex","supabase","cli"];
export const setupTabMetadata = [{"toolId":"nextjs","title":"Next.js"},{"toolId":"react","title":"React"},{"toolId":"js","title":"JS/TS"},{"toolId":"tanstack-start","title":"Tanstack Start"},{"toolId":"nodejs","title":"Node.js"},{"toolId":"bun","title":"Bun"},{"toolId":"convex","title":"Convex"},{"toolId":"supabase","title":"Supabase"},{"toolId":"cli","title":"CLI"}];
export const unifiedAiPromptTabTitle = "Unified AI Prompt";
diff --git a/packages/stack-shared/src/ai/prompts.ts b/packages/stack-shared/src/ai/prompts.ts
index 891ef3c386..353a14371e 100644
--- a/packages/stack-shared/src/ai/prompts.ts
+++ b/packages/stack-shared/src/ai/prompts.ts
@@ -533,9 +533,15 @@ export function getSdkSetupPrompt(mainType: "ai-prompt" | "nextjs" | "react" | "
Go to your project's dashboard on [app.stack-auth.com](https://app.stack-auth.com) and get the project ID. You can find it in the URL after the \`/projects/\` part. Copy-paste it into your \`.env.local\` file (or wherever your environment variables are stored):
\`\`\`.env .env.local
- STACK_PROJECT_ID= # if available, prefix with your framework's convention for client-exposed variables (e.g. NEXT_PUBLIC_, VITE_, etc.)
+ # Prefix the variable name with your framework's convention for client-exposed
+ # variables. For Next.js use NEXT_PUBLIC_STACK_PROJECT_ID, for Vite use
+ # VITE_STACK_PROJECT_ID, etc. If your framework has no such convention, use
+ # STACK_PROJECT_ID as-is.
+ STACK_PROJECT_ID=
\`\`\`
+ This is the **only** environment variable the client SDK reads in the cloud-project setup. Do not invent or add any other Stack Auth env vars on the client (in particular, there is **no** separate publishable / client key — the project ID alone is sufficient on the client).
+
Alternatively, you can also just set the project ID in the \`stack/client.ts\` file:
\`\`\`ts src/stack/client.ts
@@ -553,10 +559,16 @@ export function getSdkSetupPrompt(mainType: "ai-prompt" | "nextjs" | "react" | "
Then, copy-paste them into your \`.env.local\` file (or wherever your environment variables are stored):
\`\`\`.env .env.local
- STACK_PROJECT_ID= # if desired, prefix with your framework's convention for client-exposed variables (e.g. NEXT_PUBLIC_, VITE_, etc.)
+ # Prefix STACK_PROJECT_ID with your framework's convention for client-exposed
+ # variables (e.g. NEXT_PUBLIC_STACK_PROJECT_ID for Next.js, VITE_STACK_PROJECT_ID
+ # for Vite). STACK_SECRET_SERVER_KEY must NEVER be exposed to the client and
+ # must NOT be prefixed.
+ STACK_PROJECT_ID=
STACK_SECRET_SERVER_KEY=
\`\`\`
+ These two variables are the **complete** set the SDK reads in the cloud-project setup. Do not add any additional Stack Auth env vars (in particular, there is **no** separate publishable / client key — the project ID alone is sufficient on the client). The dashboard "Project Keys" page exposes exactly these two values; if a third slot is present in any \`.env.local\` you write, it is wrong.
+
They'll automatically be picked up by the \`StackServerApp\` constructor.
diff --git a/packages/stack-shared/src/interface/page-component-versions.ts b/packages/stack-shared/src/interface/page-component-versions.ts
index 23ba0ffa7f..6d4d506f43 100644
--- a/packages/stack-shared/src/interface/page-component-versions.ts
+++ b/packages/stack-shared/src/interface/page-component-versions.ts
@@ -104,6 +104,20 @@ function createCustomPagePrompt(options: {
},
\`\`\`
+ **Important — overriding one URL target does NOT override the others.** Every handler URL is independent and falls back to \`urls.default\`. If \`default\` is \`{ type: "hosted" }\`, customizing only this page will cause the browser to **visibly redirect through \`.built-with-stack-auth.com\`** during OAuth, magic-link, sign-out, email-verification, password-reset, and similar flows — even though your sign-in / sign-up pages render locally. That hosted subdomain must also be on the project's Trusted Domains list, or the API rejects the redirect with \`REDIRECT_URL_NOT_WHITELISTED\`.
+
+ To keep auth flows entirely on your own origin, override every related URL target. The complete set of handler URLs and the SDK call each custom page must invoke:
+
+ | URL target | What the custom page must do |
+ |---|---|
+ | \`signIn\`, \`signUp\` | Render the forms described in this prompt (or its sign-in / sign-up counterpart). |
+ | \`oauthCallback\` | On mount, call \`await stackApp.callOAuthCallback()\`. The SDK exchanges the \`code\`/\`state\` query params for tokens and then redirects to \`afterSignIn\`. |
+ | \`signOut\` | On mount, call \`await stackApp.signOut()\` then \`await stackApp.redirectToAfterSignOut({ replace: true })\`. |
+ | \`magicLinkCallback\` | Complete the magic-link exchange when the link is opened directly (separate from the OTP flow inside the sign-in page). |
+ | \`forgotPassword\`, \`passwordReset\`, \`emailVerification\`, \`accountSettings\`, \`teamInvitation\`, \`mfa\`, \`error\`, \`onboarding\`, \`cliAuthConfirm\` | Each is its own URL target; customize as needed. |
+
+ Any URL target you do NOT customize will keep bouncing through the hosted domain — that may be intentional, but it should be a deliberate choice, not an accident. Always whitelist every origin you redirect to (your app's origin in production, \`http://localhost:\` in dev, and the \`.built-with-stack-auth.com\` host if you keep any handlers on hosted). In development you can also flip the "Allow localhost callbacks" toggle on the Trusted Domains page.
+
${stackAuthReminders}
`;
const versions = {
@@ -155,7 +169,7 @@ function createAuthPagePrompt(type: AuthPagePromptType): CustomPagePrompt {
? "- If sign-ups are enabled (\\`project = await stackApp.getProject(); project.config.signUpEnabled\\`), show a link to the sign-up page."
: "- If sign-ups are disabled (\\`project = await stackApp.getProject(); !project.config.signUpEnabled\\`), show a message that sign-up is disabled."}
- Show a ${authVerb} screen. The auth methods that should render:
- - For each OAuth provider (\`project.config.oauthProviders: { readonly id: string }[]\`), render an OAuth button. Clicking the button calls \`await stackApp.signInWithOAuth("")\`.
+ - For each OAuth provider (\`project.config.oauthProviders: { readonly id: string }[]\`), render an OAuth button. Clicking the button calls \`await stackApp.signInWithOAuth("")\`. Note: this triggers a redirect through \`urls.oauthCallback\`. If that target is hosted (the default unless you override it), the browser will visibly visit \`.built-with-stack-auth.com\` before returning. To keep the flow on your origin, also customize \`urls.oauthCallback\` with a page that calls \`stackApp.callOAuthCallback()\` on mount — see the URL-config note at the end of this prompt.
${isSignIn ? "- If \\`project.config.passkeyEnabled\\`, render a passkey button. Clicking the button calls \\`await stackApp.signInWithPasskey()\\`." : ""}
- If \`project.config.credentialEnabled\`, render a credential ${authVerb} form:
- Email + password${isSignIn ? "" : " + repeat password"}