Starlight Auth

Starlight Starter Kit: Auth is an Astro/Starlight boilerplate that adds Auth.js authentication and authorization to a documentation site in a single scaffold. It is built by TheOtterlord and installs via npm create astro@latest -- --template TheOtterlord/starlight-auth.

What is Starlight Auth?

Starlight Auth is a starter template for creating documentation websites with Starlight, the Astro documentation theme, with authentication built in. It connects Auth.js (the framework formerly known as NextAuth) to Starlight, handling sign-in, session management, and route protection. The template takes configuration from auth.config.js and environment variables, and produces a deployable Astro site where access to protected pages is controlled by an isAuthed function in src/lib/auth.ts. The project is maintained by GitHub user TheOtterlord and installs with npm create astro@latest -- --template TheOtterlord/starlight-auth.

Key Features

• Auth.js integration — Supports email sign-in, username/password credentials, and OAuth with more than 80 providers. GitHub OAuth is included as a working example.
• Authorization guard — The isAuthed function in src/lib/auth.ts decides whether a user can view a page; the sample logic restricts access to routes defined in the paths array above it.
• Environment variable support — A .env.example file shows exactly which variables to set. Replace the GitHub variables with your chosen provider's credentials.
• Multi-platform adapters — astro.config.ts ships with adapters for Node, Vercel, and Netlify. Comment out the ones you're not using, then deploy directly.
• One-command scaffold — The template is available through the official Astro CLI command, making setup fast.
• Instant playgrounds — The examples/basics folder works with StackBlitz and CodeSandbox, so you can try it in the browser without local install.
• Starlight UI — You get the full Starlight theme: sidebar navigation, search, and a clean docs layout out of the box.

Who is it for?

• Documentation maintainers who need to keep parts of their docs private, such as enterprise guides or early-access content.
• SaaS developers building a product with a docs site that requires authentication, avoiding duplicated auth code.
• Teams using OAuth providers who want a quick Starlight starter wired to their existing identity system (GitHub, Google, etc.).
• Hobbyists who want a personal docs site with a login screen.

What can you do with it?

• Private documentation — Protect pages so only signed-in users can read them, ideal for internal team wikis or client-facing documentation.
• Role-based access — Extend the isAuthed function to check user roles or claims from the session, enabling different permission tiers.
• Custom sign-in flows — Swap in any Auth.js provider, from email magic links to enterprise SAML, by editing auth.config.js.
• Serverless deployment — Use the Vercel or Netlify adapters to host authentication and docs together on a CDN with serverless functions.

How does it work?

1. Scaffold a new project with npm create astro@latest -- --template TheOtterlord/starlight-auth.
2. Create a .env file by copying .env.example and fill in your auth provider credentials.
3. Edit auth.config.js to enable the sign-in methods you want (email, credentials, OAuth).
4. Adjust src/lib/auth.ts to define your authorization rules inside isAuthed.
5. Run the dev server or build; for deployment, select the correct adapter in astro.config.ts.

Authentication is handled in src/server/index.ts for Node deployments or middleware.js for Vercel/Netlify. Any on-demand .astro page can also access the session, as shown in index.astro.

FAQ

Does this template support email login?

Yes. Auth.js provides an email sign-in method that sends a magic link to the user. You enable it in auth.config.js alongside the other providers.

How do I restrict access to specific routes?

The isAuthed function in src/lib/auth.ts is called to authorize requests. Modify it to return true for users you want to allow, and false otherwise. The example checks the requested path against a paths array.

Can I deploy to Vercel or Netlify?

Yes. The template includes adapters for both platforms, plus a Node adapter. In astro.config.ts, comment out the adapters you don't need, add your environment variables, and push to your host.

Which OAuth providers are supported?

Auth.js supports 80+ providers, including GitHub, Google, Twitter, Discord, and more. The template ships with GitHub OAuth as the default example; you can replace those credentials with any provider.