Stack Auth
GuidesSDKComponentsAPI Reference
Back to home
Platform
OverviewFAQ
Getting Started
SetupComponentsUsersProduction
Concepts
API KeysBackend IntegrationCustom User DataEmailsJWT TokensOAuth
OAuth Providers
Orgs and TeamsPermissionsStack AppTeam SelectionUser OnboardingWebhooks
Customization
Custom PagesCustom StylesDark ModeInternationalization
Page Examples
Other
Self-hostSupabaseMCP SetupConvex
Stack Auth Docs

Setup

Welcome to the Next.js SDK setup guide. If you're looking for guides for other frameworks, check out the React SDK Setup, or the JavaScript SDK Setup.

Setup

Before getting started, make sure you have a Next.js project using the app router, as Stack Auth does not support the pages router.

We recommend using our setup wizard for a seamless installation experience. The wizard automatically detects your project structure and walks you through the setup process. If you encounter any issues with the wizard, you can follow our manual installation steps instead.

Run installation wizard

Run Stack's installation wizard with the following command:

Terminal
npx @stackframe/init-stack@latest

Update API keys

Then, create an account on the Stack Auth dashboard, create a new project with an API key, and copy its environment variables into the .env.local file of your Next.js project:

.env.local
NEXT_PUBLIC_STACK_PROJECT_ID=<your-project-id>
NEXT_PUBLIC_STACK_PUBLISHABLE_CLIENT_KEY=<your-publishable-client-key>
STACK_SECRET_SERVER_KEY=<your-secret-server-key>

Done!

That's it! The following files should have been created or updated in your project:

  • app/handler/[...stack]/page.tsx: This file contains the default pages for sign-in, sign-out, account settings, and more. If you prefer, later you will learn how to use custom pages instead.
  • app/layout.tsx: The layout file was updated to wrap the entire body with StackProvider and StackTheme.
  • app/loading.tsx: If not yet found, Stack automatically adds a Suspense boundary to your app. This is shown to the user while Stack's async hooks, like useUser, are loading.
  • stack/server.ts: This file contains the stackServerApp which you can use to access Stack from Server Components, Server Actions, API routes, and middleware.
  • stack/client.ts: This file contains the stackClientApp which you can use to access Stack from Client Components

Post-setup

That's it! Stack is now configured in your Next.js project. If you start your Next.js app with npm run dev and navigate to http://localhost:3000/handler/signup, you will see the sign-up page.

SignIn

After signing up/in, you will be redirected back to the home page. We will show you how to add user information to it in the next section. You can also check out the http://localhost:3000/handler/account-settings page which looks like this:

Stack account settings page

Next steps

Next up, we will show you how to retrieve and update user information, and how to protect a page from unauthorized access.

Previous PageFAQ
Next PageComponents

Table of Contents

Navigate this page

On this page

SetupRun installation wizardUpdate API keysDone!Install npm packageCreate API keysCreate stack/server.ts fileCreate Stack handlerAdd StackProvider to layout.tsxAdd Suspense boundaryDone!Post-setupNext steps

Stack Auth AI

Documentation assistant

Experimental: AI responses may not always be accurate—please verify important details.

For the most accurate information, please join our Discord or email us.

How can I help?

Ask me about Stack Auth while you browse the docs.