Skip to content

Latest commit

 

History

History
226 lines (171 loc) · 11.2 KB

README.md

File metadata and controls

226 lines (171 loc) · 11.2 KB
Raw

Stack Logo

📘 Docs | ☁️ Hosted Version | ✨ Demo | 🎮 Discord

Stack Auth: Open-source Clerk/Auth0 alternative

Stack Auth is a managed user authentication solution. It is developer-friendly and fully open-source (licensed under MIT and AGPL).

Stack gets you started in just five minutes, after which you'll be ready to use all of its features as you grow your project. Our managed service is completely optional and you can export your user data and self-host, for free, at any time.

We support Next.js frontends, along with any backend that can use our REST API. Check out our setup guide to get started.

Stack Setup

Table of contents

How is this different from X?

Ask yourself about X:

  • Is X open-source?
  • Is X developer-friendly, well-documented, and lets you get started in minutes?
  • Besides authentication, does X also do authorization and user management (see feature list below)?

If you answered "no" to any of these questions, then that's how Stack Auth is different from X.

✨ Features

To get notified first when we add new features, please subscribe to our newsletter.

<SignIn/> and <SignUp/>

Authentication components that support OAuth, password credentials, and magic links, with shared development keys to make setup faster. All components support dark/light modes.		 Sign-in component

Idiomatic Next.js APIs

We build on server components, React hooks, and route handlers.		 Dark/light mode

User dashboard

Dashboard to filter, analyze, and edit users. Replaces the first internal tool you would have to build.		 User dashboard

Account settings

Lets users update their profile, verify their e-mail, or change their password. No setup required.		 Account settings component

Multi-tenancy & teams

Manage B2B customers with an organization structure that makes sense and scales to millions.		 Selected team switcher component

Role-based access control

Define an arbitrary permission graph and assign it to users. Organizations can create org-specific roles.		 RBAC

OAuth Connections

Beyond login, Stack can also manage access tokens for third-party APIs, such as Outlook and Google Calendar. It handles refreshing tokens and controlling scope, making access tokens accessible via a single function call.		 OAuth tokens

Passkeys

Support for passwordless authentication using passkeys, allowing users to sign in securely with biometrics or security keys across all their devices.		 OAuth tokens

Impersonation

Impersonate users for debugging and support, logging into their account as if you were them.		 Webhooks

Webhooks

Get notified when users use your product, built on Svix.		 Webhooks

Automatic emails

Send customizable emails on triggers such as sign-up, password reset, and email verification, editable with a WYSIWYG editor.		 Email templates

User session & JWT handling

Stack manages refresh and access tokens, JWTs, and cookies, resulting in the best performance at no implementation cost.		 User button

M2M authentication

Use short-lived access tokens to authenticate your machines to other machines.		 M2M authentication

📦 Installation & Setup

  1. Run Stack’s installation wizard with the following command: 
    npx @stackframe/init-stack@latest
  2. 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: 
    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>
  3. That's it! You can run your app with npm run dev and go to http://localhost:3000/handler/signup to see the sign-up page. You can also check out the account settings page at http://localhost:3000/handler/account-settings.

Check out the documentation for a more detailed guide.

🌱 Some community projects built with Stack

Have your own? Happy to feature it if you create a PR or message us on Discord.

Templates

Examples

🏗 Development & Contribution

This is for you if you want to contribute to the Stack project or run the Stack dashboard locally.

Important: Please read the contribution guidelines carefully and join our Discord if you'd like to help.

Requirements

  • Node v20
  • pnpm v9
  • Docker

Setup

Pre-populated .env files for the setup below are available and used by default in .env.development in each of the packages. (Note: If you're creating a production build (eg. with pnpm run build), you must supply the environment variables manually.)

In a new terminal:

pnpm install

# Run build to build everything once
pnpm run build:dev

# reset & start the dependencies (DB, Inbucket, etc.) as Docker containers, seeding the DB with the Prisma schema
pnpm run start-deps
# pnpm run restart-deps
# pnpm run stop-deps

# Start the dev server
pnpm run dev

# In a different terminal, run tests in watch mode
pnpm run test

You can now open the dashboard at http://localhost:8101, API on port 8102, demo on port 8103, docs on port 8104, Inbucket (e-mails) on port 8105, and Prisma Studio on port 8106. See the section below on more information on the ports of the running services.

Your IDE may show an error on all @stackframe/XYZ imports. To fix this, simply restart the TypeScript language server; for example, in VSCode you can open the command palette (Ctrl+Shift+P) and run Developer: Reload Window or TypeScript: Restart TS server.

You can also open Prisma Studio to see the database interface and edit data directly:

pnpm run prisma studio

Development environment port mapping

8101: Dashboard apps/dashboard (equivalent to https://app.stack-auth.com)
8102: Backend apps/backend (equivalent to https://api.stack-auth.com)
8103: Demo app examples/demo (equivalent to https://demo.stack-auth.com)
8104: Docs docs (equivalent to https://docs.stack-auth.com)
8105: Inbucket (e-mails)
8106: Prisma Studio
8107: Jaeger UI/OpenTelemetry (for performance tracing)
8108: examples/docs-examples
8109: examples/partial-prerendering
8110: examples/cjs-test
8111: examples/e-commerce
8112: examples/middleware
8113: Svix server (for webhooks)
8114: OAuth mock server
8115: examples/supabase

Database migrations

If you make changes to the Prisma schema, you need to run the following command to create a migration:

pnpm run prisma migrate dev

Chat with the codebase

Storia trained an AI on our codebase that can answer questions about using and contributing to Stack.

Architecture overview

  graph TB
      Website[Your Website]
      User((User))
      Admin((Admin))
      subgraph "Stack Auth System"
          Dashboard[Stack Dashboard<br/>/apps/dashboard]
          Backend[Stack API Backend<br/>/apps/backend]
          Database[(PostgreSQL Database)]
          EmailService[Email Service<br/>Inbucket]
          WebhookService[Webhook Service<br/>Svix]
          StackSDK[Client SDK<br/>/packages/stack]
          subgraph Shared
              StackUI[Stack UI<br/>/packages/stack-ui]
              StackShared[Stack Shared<br/>/packages/stack-shared]
              StackEmails[Stack Emails<br/>/packages/stack-emails]
          end
      end
      Admin --> Dashboard
      User --> Website
      Website --> StackSDK
      Backend --> Database
      Backend --> EmailService
      Backend --> WebhookService
      Dashboard --> Shared
      Dashboard --> StackSDK
      StackSDK --HTTP Requests--> Backend
      StackSDK --> Shared
      Backend --> Shared
      classDef container fill:#1168bd,stroke:#0b4884,color:#ffffff
      classDef database fill:#2b78e4,stroke:#1a4d91,color:#ffffff
      classDef external fill:#999999,stroke:#666666,color:#ffffff
      classDef deprecated stroke-dasharray: 5 5
      class Dashboard,Backend,EmailService,WebhookService,Website container
      class Database database
Loading

Thanks to CodeViz for generating the diagram!

❤ Contributors