CodeCow/stack
1
0
Fork 0
mirror of https://github.com/stack-auth/stack.git synced 2026-06-04 21:04:37 +08:00
Code Issues Actions 2 Packages Projects Releases Wiki Activity

Improve docs sidebar content

Browse Source
This commit is contained in:
Konstantin Wohlwend 2026-04-06 14:48:26 -07:00
parent 64e6d2936c
commit d2f252d3fa
25 changed files with 259 additions and 200 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

70
docs-mintlify/docs.json
View File

@ -52,7 +52,6 @@
"pages": [
"docs/getting-started/setup",
"docs/getting-started/users",
"docs/getting-started/components",
"docs/getting-started/production",
"docs/getting-started/vite-example"
]
@ -60,7 +59,6 @@
{
"group": "Going Further",
"pages": [
"docs/going-further/working-with-ai",
"docs/concepts/stack-app",
"docs/concepts/backend-integration",
"docs/going-further/local-development",
@ -71,23 +69,9 @@
"docs/customization/custom-styles",
"docs/customization/dark-mode",
"docs/customization/internationalization",
{
"group": "Page Examples",
"pages": [
"docs/customization/page-examples",
"docs/customization/page-examples/forgot-password",
"docs/customization/page-examples/password-reset",
"docs/customization/page-examples/sign-in",
"docs/customization/page-examples/sign-up"
]
}
"docs/customization/page-examples"
]
},
"docs/concepts/custom-user-data",
"docs/concepts/sign-up-rules",
"docs/concepts/jwt",
"docs/concepts/user-onboarding",
"docs/concepts/team-selection"
}
]
},
{
@ -101,6 +85,7 @@
{
"group": "Auth Providers",
"pages": [
"docs/apps/auth-providers",
"docs/concepts/auth-providers",
"docs/concepts/auth-providers/apple",
"docs/concepts/auth-providers/bitbucket",
@ -117,18 +102,31 @@
"docs/concepts/auth-providers/two-factor-auth",
"docs/concepts/auth-providers/x-twitter"
]
}
},
"docs/concepts/sign-up-rules",
"docs/others/cli-authentication"
]
},
"docs/concepts/user-onboarding",
{
"group": "Teams",
"icon": "users",
"pages": [
"docs/apps/orgs-and-teams",
"docs/concepts/orgs-and-teams",
"docs/concepts/team-selection"
]
},
"docs/apps/emails",
"docs/apps/payments",
"docs/apps/analytics",
"docs/apps/api-keys",
"docs/apps/data-vault",
"docs/apps/launch-checklist",
"docs/apps/permissions",
"docs/apps/orgs-and-teams",
"docs/apps/webhooks"
"docs/apps/api-keys",
"docs/apps/payments",
"docs/apps/emails",
"docs/concepts/emails",
"docs/apps/data-vault",
"docs/apps/webhooks",
"docs/apps/launch-checklist",
"docs/going-further/working-with-ai",
"docs/apps/analytics"
]
},
{
@ -136,7 +134,7 @@
"pages": [
"docs/others/supabase",
"docs/others/convex",
"docs/others/mcp-setup"
"docs/others/vercel"
]
},
{
@ -144,6 +142,15 @@
"pages": [
"docs/others/self-host",
"docs/others/cli-authentication",
"docs/others/mcp-setup",
{
"group": "Tutorials",
"pages": [
"docs/others/tutorials/build-a-saas-with-stack-auth",
"docs/others/tutorials/build-a-team-based-app",
"docs/others/tutorials/ship-production-ready-auth"
]
},
"docs/going-further/showcase"
]
}
@ -594,10 +601,5 @@
"robots": "noindex"
}
},
"redirects": [
{
"source": "/docs/overview",
"destination": "/"
}
]
"redirects": []
}

135
docs-mintlify/docs/apps/launch-checklist.mdx
View File

@ -1,43 +1,134 @@
---
title: "Launch Checklist"
description: "A guided checklist to make sure your project is ready for production"
description: "Steps to prepare Stack for production use"
icon: "clipboard-check"
---
The Launch Checklist is a built-in dashboard tool that walks you through everything you need to verify before going live. It checks your project configuration and guides you through each requirement, so nothing gets missed on launch day.
Stack makes development easy with various default settings, but these settings need to be optimized for security and user experience when moving to production. Here's a checklist of things you need to do before switching to production mode:
Enable it from the **App Store** in your [Stack Auth dashboard](https://app.stack-auth.com), then find it in your project sidebar.
## Domains
## What it checks
By default, Stack allows all localhost paths as valid callback URLs. This is convenient for development but poses a security risk in production because attackers could use their own domains as callback URLs to intercept sensitive information. Therefore, in production, Stack must know your domain (e.g., `https://your-website.com`) and only allow callbacks from those domains.
The checklist is organized into four areas, each with specific sub-tasks:
Follow these steps when you're ready to push your application to production:
### Domains & callbacks
<Steps>
<Step title="Add Your Domain">
Navigate to the `Domain & Handlers` tab in the Stack dashboard. If you haven't configured your handler, you can leave it as the default. (Learn more about handlers [here](../sdk/objects/stack-app)).
</Step>
<Step title="Disable Localhost Callbacks">
For enhanced security, disable the `Allow all localhost callbacks for development` option.
</Step>
</Steps>
- **Production domain saved** — At least one domain must be configured in your project's domain settings.
- **Localhost callbacks disabled** — The "Allow localhost" option must be turned off. Localhost should not be reachable in production.
## OAuth providers
### OAuth providers
Stack uses shared OAuth keys for development to simplify setup when using "Sign in with Google/GitHub/etc." However, this isn't secure for production as it displays "Stack Development" on the providers' consent screens, making it unclear to users if the OAuth request is genuinely from your site. Thus, you should configure your own OAuth keys with the providers and connect them to Stack.
- **Custom client IDs and secrets** — Any OAuth provider you've enabled (Google, GitHub, etc.) must use your own client credentials, not the shared defaults that Stack Auth provides for development. Shared credentials are not suitable for production.
To use your own OAuth provider setups in production, follow these steps for each provider you use:
The checklist includes expandable guides with callback URLs and setup instructions for each provider.
<Steps>
<Step title="Create an OAuth App">
On the provider's website, create an OAuth app and set the callback URL to the corresponding Stack callback URL. Copy the client ID and client secret.
### Email server
<Tabs>
<Tab title="Google">
[Google OAuth Setup Guide](https://developers.google.com/identity/protocols/oauth2#1.-obtain-oauth-2.0-credentials-from-the-dynamic_data.setvar.console_name-.)
- **Custom SMTP or Resend configured** — Your project must use your own email server, not Stack Auth's shared email service. This ensures reliable deliverability and lets you send from your own domain.
Callback URL:
### Production mode
```
https://api.stack-auth.com/api/v1/auth/oauth/callback/google
```
</Tab>
<Tab title="GitHub">
[GitHub OAuth Setup Guide](https://docs.github.com/en/apps/oauth-apps/building-oauth-apps/creating-an-oauth-app)
- **Automated checks passing** — Stack Auth runs a set of automated validations on your project config. These verify that all trusted domains use HTTPS, are not localhost, and are not raw IP addresses.
- **Production mode enabled** — Once all checks pass, you can flip the production mode toggle directly from the checklist. This locks down your project to production-ready settings.
Callback URL:
<Info>
You can toggle production mode on and off directly from the Launch Checklist page. When you enable it for the first time, you'll get a confetti celebration.
</Info>
```
https://api.stack-auth.com/api/v1/auth/oauth/callback/github
```
</Tab>
<Tab title="Facebook">
[Facebook OAuth Setup Guide](https://developers.facebook.com/docs/development/create-an-app/facebook-login-use-case)
## How it works
Callback URL:
The Launch Checklist doesn't have its own API — it reads your existing project configuration and evaluates readiness based on the settings you've already configured elsewhere (domains, OAuth providers, email server, etc.). Each task links directly to the relevant settings page so you can fix issues in context.
```
https://api.stack-auth.com/api/v1/auth/oauth/callback/facebook
```
</Tab>
<Tab title="Microsoft">
[Microsoft Azure OAuth Setup Guide](https://learn.microsoft.com/en-us/entra/identity-platform/quickstart-register-app)
Progress is tracked visually with a progress bar and completion indicators. The checklist highlights the next action you need to take, making it easy to work through the tasks in order.
Callback URL:
```
https://api.stack-auth.com/api/v1/auth/oauth/callback/microsoft
```
</Tab>
<Tab title="Spotify">
[Spotify OAuth Setup Guide](https://developer.spotify.com/documentation/general/guides/app-settings/)
Callback URL:
```
https://api.stack-auth.com/api/v1/auth/oauth/callback/spotify
```
</Tab>
<Tab title="Gitlab">
[Gitlab OAuth Setup Guide](https://docs.gitlab.com/ee/integration/oauth_provider.html)
Callback URL:
```
https://api.stack-auth.com/api/v1/auth/oauth/callback/gitlab
```
</Tab>
<Tab title="Bitbucket">
[Bitbucket OAuth Setup Guide](https://support.atlassian.com/bitbucket-cloud/docs/use-oauth-on-bitbucket-cloud)
Callback URL:
```
https://api.stack-auth.com/api/v1/auth/oauth/callback/bitbucket
```
</Tab>
<Tab title="LinkedIn">
[LinkedIn OAuth Setup Guide](https://learn.microsoft.com/en-us/linkedin/shared/authentication/authorization-code-flow?context=linkedin%2Fcontext&tabs=HTTPS1)
Callback URL:
```
https://api.stack-auth.com/api/v1/auth/oauth/callback/linkedin
```
</Tab>
<Tab title="X">
[X OAuth Setup Guide](https://developer.x.com/en/docs/apps/overview)
Callback URL:
```
https://api.stack-auth.com/api/v1/auth/oauth/callback/x
```
</Tab>
</Tabs>
</Step>
<Step title="Enter OAuth Credentials">
Go to the `Auth Methods` section in the Stack dashboard, open the provider's settings, switch from shared keys to custom keys, and enter the client ID and client secret.
</Step>
</Steps>
## Email server
For development, Stack uses a shared email server, which sends emails from Stack's domain. This is not ideal for production as users may not trust emails from an unfamiliar domain. You should set up an email server connected to your own domain.
Steps to connect your own email server with Stack:
1. **Setup Email Server**: Configure your own email server and connect it to your domain (this step is beyond Stack's documentation scope).
2. **Configure Stack's Email Settings**: Navigate to the `Emails` section in the Stack dashboard, click `Edit` in the `Email Server` section, switch from `Shared` to `Custom SMTP server`, enter your SMTP configurations, and save.
## Enabling production mode
After completing the steps above, you can enable production mode on the `Project Settings` tab in the Stack dashboard, ensuring that your website runs securely with Stack in a production environment.

1
docs-mintlify/docs/apps/oauth.mdx
View File

@ -1,6 +1,7 @@
---
title: "OAuth"
description: "Managing third-party OAuth access tokens"
sidebarTitle: "Authentication"
---
Stack has good support for working with OAuth and OIDC providers, such as Google, Facebook, Microsoft, and others.

1
docs-mintlify/docs/apps/orgs-and-teams.mdx
View File

@ -1,6 +1,7 @@
---
title: "Orgs and Teams"
description: "Manage teams and team members"
sidebarTitle: Teams
icon: "users"
---

1
docs-mintlify/docs/apps/permissions.mdx
View File

@ -1,6 +1,7 @@
---
title: "RBAC Permissions"
description: "Control what each user can do and access within your application"
sidebarTitle: RBAC
icon: "user-cog"
---

1
docs-mintlify/docs/concepts/auth-providers/two-factor-auth.mdx
View File

@ -1,6 +1,7 @@
---
title: "Two-Factor Authentication (2FA)"
description: "Learn how Two-Factor Authentication works with Stack Auth"
sidebarTitle: "Two-Factor Auth"
---
This guide explains how Two-Factor Authentication (2FA) works with Stack Auth. 2FA adds an extra layer of security by requiring users to provide a verification code in addition to their password.

1
docs-mintlify/docs/concepts/backend-integration.mdx
View File

@ -1,6 +1,7 @@
---
title: "Backend Integration"
description: "Integrate Stack Auth with your own server with the REST APIs"
sidebarTitle: "Integrating with backends"
---
To authenticate your endpoints, you need to send the user's access token in the headers of the request to your server, and then make a request to Stack's server API to verify the user's identity.

1
docs-mintlify/docs/concepts/emails.mdx
View File

@ -1,6 +1,7 @@
---
title: "Emails"
description: "Send custom emails to your users with Stack Auth's email system."
sidebarTitle: Email API
---
Stack Auth provides emails that allows you to send custom emails to your users. The system supports both custom HTML emails and template-based emails with theming.

1
docs-mintlify/docs/concepts/orgs-and-teams.mdx
View File

@ -1,6 +1,7 @@
---
title: "Orgs and Teams"
description: "Manage teams and team members"
sidebarTitle: "Team Settings"
---
Teams provide a structured way to group users and manage their permissions. Users can belong to multiple teams simultaneously, allowing them to represent departments, B2B customers, or projects.

1
docs-mintlify/docs/concepts/stack-app.mdx
View File

@ -1,6 +1,7 @@
---
title: "Stack App"
description: "The most important object of your Stack project"
sidebarTitle: "The StackApp Object"
---
By now, you may have seen the `useStackApp()` hook and the `stackServerApp` variable. Both return a `StackApp`, of type `StackClientApp` and `StackServerApp` respectively.

1
docs-mintlify/docs/concepts/team-selection.mdx
View File

@ -1,6 +1,7 @@
---
title: "Team Selection"
description: ""
sidebarTitle: Selected Teams
---
A user can be a member of multiple teams, so most websites using teams will need a way to select a "current team" that the user is working on. There are two primary methods to accomplish this:

1
docs-mintlify/docs/concepts/user-onboarding.mdx
View File

@ -1,6 +1,7 @@
---
title: "User Onboarding"
description: "Implementing a user onboarding page and collecting information on sign-up"
sidebarTitle: Onboarding
---
By default, Stack Auth collects information such as email addresses from OAuth providers. Sometimes, you may want to collect additional information from users during sign-up, for example a name or address.

1
docs-mintlify/docs/customization/custom-pages.mdx
View File

@ -1,6 +1,7 @@
---
title: Custom Pages
description: Take full control over the layout and logic flow of authentication pages in your application.
sidebarTitle: Component customization
---
Custom pages allow you to take full control over the layout and logic flow of authentication pages in your application. Instead of using the default pages provided by Stack Auth, you can build your own using our built-in components or low-level functions.

1
docs-mintlify/docs/faq.mdx
View File

@ -2,7 +2,6 @@
title: FAQ
description: Frequently asked questions about Stack
sidebarTitle: FAQ
icon: circle-question
---
# FAQ

1
docs-mintlify/docs/getting-started/components.mdx
View File

@ -2,7 +2,6 @@
title: Components
description: Pre-built Next.js components to make your life easier
sidebarTitle: Components
icon: "puzzle-piece"
---
# Components

137
docs-mintlify/docs/getting-started/production.mdx
View File

@ -1,137 +0,0 @@
---
title: Production
description: Steps to prepare Stack for production use
sidebarTitle: Production
icon: "rocket"
---
# Production
Stack makes development easy with various default settings, but these settings need to be optimized for security and user experience when moving to production. Here's a checklist of things you need to do before switching to production mode:
## Domains
By default, Stack allows all localhost paths as valid callback URLs. This is convenient for development but poses a security risk in production because attackers could use their own domains as callback URLs to intercept sensitive information. Therefore, in production, Stack must know your domain (e.g., `https://your-website.com`) and only allow callbacks from those domains.
Follow these steps when you're ready to push your application to production:
<Steps>
<Step title="Add Your Domain">
Navigate to the `Domain & Handlers` tab in the Stack dashboard. If you haven't configured your handler, you can leave it as the default. (Learn more about handlers [here](../sdk/objects/stack-app)).
</Step>
<Step title="Disable Localhost Callbacks">
For enhanced security, disable the `Allow all localhost callbacks for development` option.
</Step>
</Steps>
## OAuth providers
Stack uses shared OAuth keys for development to simplify setup when using "Sign in with Google/GitHub/etc." However, this isn't secure for production as it displays "Stack Development" on the providers' consent screens, making it unclear to users if the OAuth request is genuinely from your site. Thus, you should configure your own OAuth keys with the providers and connect them to Stack.
To use your own OAuth provider setups in production, follow these steps for each provider you use:
<Steps>
<Step title="Create an OAuth App">
On the provider's website, create an OAuth app and set the callback URL to the corresponding Stack callback URL. Copy the client ID and client secret.
<Tabs>
<Tab title="Google">
[Google OAuth Setup Guide](https://developers.google.com/identity/protocols/oauth2#1.-obtain-oauth-2.0-credentials-from-the-dynamic_data.setvar.console_name-.)
Callback URL:
```
https://api.stack-auth.com/api/v1/auth/oauth/callback/google
```
</Tab>
<Tab title="GitHub">
[GitHub OAuth Setup Guide](https://docs.github.com/en/apps/oauth-apps/building-oauth-apps/creating-an-oauth-app)
Callback URL:
```
https://api.stack-auth.com/api/v1/auth/oauth/callback/github
```
</Tab>
<Tab title="Facebook">
[Facebook OAuth Setup Guide](https://developers.facebook.com/docs/development/create-an-app/facebook-login-use-case)
Callback URL:
```
https://api.stack-auth.com/api/v1/auth/oauth/callback/facebook
```
</Tab>
<Tab title="Microsoft">
[Microsoft Azure OAuth Setup Guide](https://learn.microsoft.com/en-us/entra/identity-platform/quickstart-register-app)
Callback URL:
```
https://api.stack-auth.com/api/v1/auth/oauth/callback/microsoft
```
</Tab>
<Tab title="Spotify">
[Spotify OAuth Setup Guide](https://developer.spotify.com/documentation/general/guides/app-settings/)
Callback URL:
```
https://api.stack-auth.com/api/v1/auth/oauth/callback/spotify
```
</Tab>
<Tab title="Gitlab">
[Gitlab OAuth Setup Guide](https://docs.gitlab.com/ee/integration/oauth_provider.html)
Callback URL:
```
https://api.stack-auth.com/api/v1/auth/oauth/callback/gitlab
```
</Tab>
<Tab title="Bitbucket">
[Bitbucket OAuth Setup Guide](https://support.atlassian.com/bitbucket-cloud/docs/use-oauth-on-bitbucket-cloud)
Callback URL:
```
https://api.stack-auth.com/api/v1/auth/oauth/callback/bitbucket
```
</Tab>
<Tab title="LinkedIn">
[LinkedIn OAuth Setup Guide](https://learn.microsoft.com/en-us/linkedin/shared/authentication/authorization-code-flow?context=linkedin%2Fcontext&tabs=HTTPS1)
Callback URL:
```
https://api.stack-auth.com/api/v1/auth/oauth/callback/linkedin
```
</Tab>
<Tab title="X">
[X OAuth Setup Guide](https://developer.x.com/en/docs/apps/overview)
Callback URL:
```
https://api.stack-auth.com/api/v1/auth/oauth/callback/x
```
</Tab>
</Tabs>
</Step>
<Step title="Enter OAuth Credentials">
Go to the `Auth Methods` section in the Stack dashboard, open the provider's settings, switch from shared keys to custom keys, and enter the client ID and client secret.
</Step>
</Steps>
## Email server
For development, Stack uses a shared email server, which sends emails from Stack's domain. This is not ideal for production as users may not trust emails from an unfamiliar domain. You should set up an email server connected to your own domain.
Steps to connect your own email server with Stack:
1. **Setup Email Server**: Configure your own email server and connect it to your domain (this step is beyond Stack's documentation scope).
2. **Configure Stack's Email Settings**: Navigate to the `Emails` section in the Stack dashboard, click `Edit` in the `Email Server` section, switch from `Shared` to `Custom SMTP server`, enter your SMTP configurations, and save.
## Enabling production mode
After completing the steps above, you can enable production mode on the `Project Settings` tab in the Stack dashboard, ensuring that your website runs securely with Stack in a production environment.

1
docs-mintlify/docs/getting-started/setup.mdx
View File

@ -2,7 +2,6 @@
title: Setup
description: Install and configure Stack Auth for your project
sidebarTitle: Setup
icon: "gear"
---
# Setup

3
docs-mintlify/docs/getting-started/users.mdx
View File

@ -1,8 +1,7 @@
---
title: User Fundamentals
description: Access and manage user information within custom components
sidebarTitle: User Fundamentals
icon: "users"
sidebarTitle: Users
---
import { UserFieldsTable } from "/snippets/user-fields-table.jsx";

3
docs-mintlify/docs/getting-started/vite-example.mdx
View File

@ -1,8 +1,7 @@
---
title: Vite JavaScript Example
description: How to integrate Stack Auth with Vite and other JavaScript frameworks
sidebarTitle: Vite Example
icon: "bolt"
sidebarTitle: Customization
---
# Vite JavaScript Example

1
docs-mintlify/docs/going-further/working-with-ai.mdx
View File

@ -1,6 +1,7 @@
---
title: "Working with AI"
description: "Use AI-powered tools and integrations with Stack Auth to accelerate your development workflow"
sidebarTitle: "Catalyst"
---
This page is under construction. Check back soon for guidance on integrating Stack Auth with AI-powered development tools.

14
docs-mintlify/docs/others/tutorials/build-a-saas-with-stack-auth.mdx Normal file
View File

@ -0,0 +1,14 @@
---
title: Build a SaaS with Stack Auth
description: End-to-end tutorial stub for building a SaaS app with Stack Auth.
---
This tutorial is coming soon.
## Planned coverage
- Project setup and auth bootstrapping
- App onboarding, teams, and permissions
- Production deployment checklist
If you want this prioritized, open a request in our community channels and include your stack details.

12
docs-mintlify/docs/others/tutorials/build-a-team-based-app.mdx Normal file
View File

@ -0,0 +1,12 @@
---
title: Build a Team-Based App
description: Tutorial stub for implementing teams and role-based access with Stack Auth.
---
This tutorial is coming soon.
## Planned coverage
- Team creation and membership flows
- Team selection patterns
- RBAC permission modeling for multi-tenant apps

12
docs-mintlify/docs/others/tutorials/ship-production-ready-auth.mdx Normal file
View File

@ -0,0 +1,12 @@
---
title: Ship Production-Ready Auth
description: Tutorial stub for hardening a Stack Auth deployment before launch.
---
This tutorial is coming soon.
## Planned coverage
- Environment and key management strategy
- Provider, email, and webhook production checks
- Launch readiness and rollback planning

57
docs-mintlify/docs/others/vercel.mdx Normal file
View File

@ -0,0 +1,57 @@
---
title: Vercel
description: Deploy your Stack Auth project on Vercel with the dashboard integration flow.
---
This guide mirrors the Vercel integration flow in the Stack Auth dashboard app.
## What this integration covers
- Generate Stack Auth keys for your project
- Add the required environment variables in Vercel
- Redeploy and verify the auth flow
## Setup
<Steps>
<Step title="Open your Vercel project">
In the Vercel dashboard, open the project you want to connect to Stack Auth.
[Open Vercel dashboard](https://vercel.com/dashboard)
</Step>
<Step title="Generate keys from Stack Auth">
In your Stack dashboard, open the **Vercel Integration** app and generate keys for your project.
This produces a project ID plus API keys that you can paste into Vercel.
</Step>
<Step title="Add environment variables in Vercel">
In Vercel, go to **Project -> Settings -> Environment Variables** and add:
- `NEXT_PUBLIC_STACK_PROJECT_ID`
- `NEXT_PUBLIC_STACK_PUBLISHABLE_CLIENT_KEY`
- `STACK_SECRET_SERVER_KEY`
Add `NEXT_PUBLIC_STACK_API_URL` only if you are not using the default hosted Stack API.
</Step>
<Step title="Redeploy">
Trigger a new deployment so Vercel picks up the new environment variables.
If you use both preview and production environments, make sure both are updated.
</Step>
<Step title="Verify the integration">
Open your deployed app and test authentication.
A quick check is to visit `/handler/signup` and confirm the sign-up flow loads correctly.
</Step>
</Steps>
## Notes
- Keys are sensitive. Store server keys only in server-side environment variables.
- If authentication fails after setup, confirm variable names are exact and redeploy again.
For additional Vercel details, see [Vercel environment variable docs](https://vercel.com/docs/environment-variables).

1
docs-mintlify/index.mdx
View File

@ -1,6 +1,7 @@
---
title: "Welcome"
description: "Stack Auth documentation for setup, components, SDK usage, and REST APIs."
sidebarTitle: "Overview"
---
<div className="not-prose relative left-1/2 right-1/2 -mx-[50vw] w-screen overflow-hidden bg-[#121212]">