Quick start

Initialize SimpleAuth in a React or Next.js app and add a sign-in form in minutes.

1. Prerequisites

You already have a React or Next.js project with a package.json at the repository root you target.
The CLI installs @simpleauthjs/core for you unless you pass --no-install.

2. Initialize SimpleAuth

From your app root:

npx @simpleauthjs/react init

You should see log lines confirming files were written under components/simpleauth/, followed by:

SimpleAuth init complete.
Next steps:
1) Add your public key in .env.local:
   NEXT_PUBLIC_SIMPLEAUTH_PUBLIC_KEY=sa_live_your_public_key
2) Wrap your app with `SimpleAuthProvider` and use generated hooks/components as needed.

(Vite projects use .env and VITE_SIMPLEAUTH_PUBLIC_KEY instead; see the tab below.)

3. Configure environment variables

The generated browser client talks to the hosted API at https://simpleauth.net by default. You only need your app’s public key from the dashboard. Never put a secret key in client-side env vars.

Add to .env.local:

NEXT_PUBLIC_SIMPLEAUTH_PUBLIC_KEY=sa_live_your_public_key

Add to .env:

VITE_SIMPLEAUTH_PUBLIC_KEY=sa_live_your_public_key

Local development of SimpleAuth

If you are running this repository (or another SimpleAuth API) on your machine, point the SDK at it by editing components/simpleauth/client.ts and passing baseUrl: 'http://localhost:3000' into createSimpleAuthClient, or set SIMPLEAUTH_BASE_URL when you construct the client yourself.

4. Wrap the app with SimpleAuthProvider

In a Next.js App Router layout:

import type { ReactNode } from "react"
import { SimpleAuthProvider } from "@/components/simpleauth/provider"

export default function RootLayout({ children }: { children: ReactNode }) {
  return (
    <html lang="en">
      <body>
        <SimpleAuthProvider>{children}</SimpleAuthProvider>
      </body>
    </html>
  )
}

npx @simpleauthjs/react add sign-in

6. Render the form

import { SignInForm } from "@/components/simpleauth"

export default function LoginPage() {
  return <SignInForm />
}

What is next

In the Components and Hooks sections, each reference page ends with a Source panel: it shows the TypeScript and CSS the CLI would write into components/simpleauth/, so you can compare or copy without leaving the docs.

Components

Reference for every scaffolded component.

Hooks

Reference for generated hooks and return values.

Recipes

Common patterns such as protected routes and sign-out.

You own the generated files

Everything scaffolded lives under components/simpleauth/ in your repo. Edit anything freely; the CLI will not overwrite files unless you pass --force.