Skip to main content

Installation & Setup

To get started with Stack, you need to create a Next.js project with the App router. If you are starting from scratch, run the following:

npx create-next-app@latest --app stack-example
cd stack-example

To add Stack to a newly created or an existing project, you can run Stack's installation wizard with the following command:

npx @stackframe/init-stack@latest

You will be guided through the installation process. To complete it, you must create an account on our dashboard, create a new project with an API key, and copy the project ID, publishable client key, and secret server key into the .env.local file in the root of your Next.js project:

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>

After that, you'll be able to see the Stack sign-up page at https://your-website.example.com/handler/signup.

Manual installation​

If the setup wizard doesn't work due to an unsupported project structure, you can also install Stack manually.

First, install Stack with npm, yarn, or pnpm:

npm install @stackframe/stack

  1. If you haven't already, register a new account on Stack. Create a project in the dashboard, create a new API key from the left sidebar, and copy the project ID, publishable client key, and secret server key into a new file called .env.local in the root of your Next.js project:

    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>

  2. Create a new file in lib/stack.ts and fill it with the following:

    import "server-only";
    import { StackServerApp } from "@stackframe/stack";

    export const stackApp = new StackServerApp({
      tokenStore: "nextjs-cookie", // storing auth tokens in cookies
    });

    This will read the environment variables automatically and create a server app that you can later use to access Stack from your Next.js server.

    Check out the StackServerApp documentation to learn more about its other options.

  3. Create a new file in app/handler/[...stack]/page.tsx and paste the following code:

    import { StackHandler } from "@stackframe/stack";
    import { stackApp } from "@/lib/stack";

    export default function Handler(props: any) {
      return <StackHandler app={stackApp} {...props} />;
    }

    This will create pages for sign-in, sign-up, password reset, and others. Additionally, it will be used as a callback URL for OAuth. You can replace them with your own pages later.

  4. In your app/layout.tsx, wrap the entire body with a StackProvider and StackTheme. Afterwards, it should look like this:

    import React from "react";
    import { StackProvider, StackTheme } from "@stackframe/stack";
    import { stackApp } from "@/lib/stack";

    export default function RootLayout({ children }: { children: React.ReactNode }) {
      return (
        <html lang="en">
          <body>
            <StackProvider app={stackApp}>
              <StackTheme>
                {children}
              </StackTheme>
            </StackProvider>
          </body>
        </html>
      );
    }

  5. By default, Stack uses Suspense to handle loading states. To show a loading indicator while Stack is fetching user data, make sure there is a loading.tsx file in your app directory:

    export default function Loading() {
      // You can use any loading indicator here
      return <>
        Loading...
      </>;
    }

  6. 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 Stack sign-up page!

    Stack sign up page

    After signing up/in, you will be redirected back to the home page, which is empty/default for now. We will add some useful information to it in the next section. You can also check out http://localhost:3000/handler/account-settings page which looks like this:

    Stack account settings page

Next steps​

Next, we will show you how to get user information, protect a page, and modify the user profile.