# Setup
URL: /docs/getting-started/setup
Source: /vercel/path0/docs/content/docs/(guides)/getting-started/setup.mdx



***

## title: Setup

### Prerequisites

Before getting started, make sure you have a project set up for your chosen platform:

* **Next.js**: A [Next.js project](https://nextjs.org/docs/getting-started/installation) using the app router (Stack Auth does not support the pages router on Next.js)
* **React**: A [React project](https://react.dev/learn/creating-a-react-app) (we show examples with Vite)
* **JavaScript**: A Node.js project with Express
* **Python**: A Python environment with your chosen framework (Django, FastAPI, or Flask)

We recommend using our **setup wizard** for JavaScript frameworks for a seamless installation experience. For Python, we recommend using the REST API approach.

### Setup Wizard / Manual Installation

<Tabs defaultValue="wizard">
  <TabsList>
    <TabsTrigger value="wizard">Setup wizard (recommended for JS)</TabsTrigger>
    <TabsTrigger value="manual">Manual installation</TabsTrigger>
  </TabsList>

  <TabsContent value="wizard">
    <Steps>
      <Step>
        ### Run installation wizard
      </Step>

      <Info>
        The setup wizard is available for JavaScript/TypeScript frameworks. For Python projects, please use the manual installation method.
      </Info>

      Run Stack's installation wizard with the following command:

      ```sh title="Terminal"
      npx @stackframe/init-stack@latest
      ```

      <Step>
        ### Update API keys
      </Step>

      Create an account on [the Stack Auth dashboard](https://app.stack-auth.com/projects), create a new project with an API key, and copy its environment variables into the appropriate configuration file:

      <PlatformCodeblock document="setup/setup" examples={["env-wizard"]} title="Environment Configuration" />

      <Step>
        ### Done!
      </Step>

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

      **For Next.js:**

      * `app/handler/[...stack]/page.tsx`: Default pages for sign-in, sign-out, account settings, and more
      * `app/layout.tsx`: Updated to wrap the entire body with `StackProvider` and `StackTheme`
      * `app/loading.tsx`: Suspense boundary for Stack's async hooks
      * `stack/server.ts`: Contains the `stackServerApp` for server-side usage
      * `stack/client.ts`: Contains the `stackClientApp` for client-side usage

      **For React:**

      * `stack/client.ts`: Contains the `stackClientApp` configuration
      * Your app should be wrapped with `StackProvider` and `StackTheme`

      **For Node.js/Express:**

      * `stack/server.ts`: Contains the `stackServerApp` configuration
    </Steps>
  </TabsContent>

  <TabsContent value="manual">
    <Info>
      Note: The setup wizard also supports existing, complicated projects. Cases where manual installation is necessary are rare for JavaScript frameworks.
    </Info>

    <Steps>
      <Step>
        ### Install package
      </Step>

      First, install the appropriate Stack package:

      <PlatformCodeblock document="setup/setup" examples={["install-package"]} title="Package Installation" />

      <Step>
        ### Create API keys
      </Step>

      [Register a new account on Stack](https://app.stack-auth.com/handler/sign-up), create a project in the dashboard, create a new API key from the left sidebar, and copy the project ID, publishable client key, and secret server key.

      <Step>
        ### Configure environment variables
      </Step>

      Set up your environment variables or configuration:

      <PlatformCodeblock document="setup/setup" examples={["env-config"]} title="Environment Configuration" />

      <Step>
        ### Create Stack configuration
      </Step>

      Create the Stack app configuration:

      <PlatformCodeblock document="setup/setup" examples={["stack-config"]} title="Stack Configuration" />

      <Step>
        ### Set up authentication handlers (Frontend frameworks only)
      </Step>

      For JavaScript frameworks, create the authentication handler:

      <PlatformCodeblock document="setup/setup" examples={["auth-handlers"]} title="Authentication Handlers" />

      <Step>
        ### Add providers (Next.js and React only)
      </Step>

      For Next.js and React, wrap your app with Stack providers:

      <PlatformCodeblock document="setup/setup" examples={["app-providers"]} title="App Providers" />

      <Step>
        ### Add loading boundary (Next.js only)
      </Step>

      For Next.js, add a Suspense boundary:

      <PlatformCodeblock document="setup/setup" examples={["loading-boundary"]} title="Loading Component" />

      <Step>
        ### Add suspense boundary (React only)
      </Step>

      For React, add a suspense boundary:

      <PlatformCodeblock document="setup/setup" examples={["suspense-boundary"]} title="Suspense Boundary" />

      <Step>
        ### Done!
      </Step>
    </Steps>
  </TabsContent>
</Tabs>

## Post-setup

That's it! Stack is now configured in your project.

### Testing your setup

<PlatformCodeblock document="setup/setup" examples={["test-setup"]} title="Testing Your Setup" />

### What you'll see

For JavaScript frameworks with built-in UI components, you'll see the Stack Auth sign-up page:

<img src="/imgs/sign-in.png" alt="Stack sign-in page" width={350} height={350} className="mx-auto block rounded-lg" />

After signing up/in, you will be redirected back to the home page. You can also check out the account settings page.

<img src="/imgs/account-settings.png" alt="Stack account settings page" className="mx-auto block rounded-lg" />

For Python and backend-only JavaScript setups, you'll interact with Stack Auth through the REST API.

## Example usage

Here are some basic usage examples for each platform:

<PlatformCodeblock document="setup/setup" examples={["basic-usage"]} title="Basic Usage Examples" />

## Next steps

Next up, we will show you how to [retrieve and update user information](./users.mdx), and how to [protect a page](./users.mdx#protecting-a-page) from unauthorized access.

For Python developers, check out the [REST API documentation](../rest-api/overview.mdx) to learn more about the available endpoints and how to use them in your Python application.