starlight-better-auth-example 🔐

Demonstration project using the Better Auth library to add authentication to a Starlight project.

Note

This repository is shared for demonstration purposes only, written in a limited amount of time, and is not intended to be used as a production-ready application.

The goal is to demonstrate how one might use the Better Auth library in a Starlight application to add authentication and secure some content behind a login form.

Note

The Better Auth library is still in beta and not yet production-ready.

Features

This repository contains a basic example of a Starlight project with authentication implemented using the Better Auth library.

Users can create an account, sign in, and sign out. Some pages are protected and require the user to be authenticated to access them or even be visible in the documentation sidebar.

• All forms are implemented using Astro Actions.
• Authentication is handled by the Better Auth library.
  • Better Auth requires a database connection to store data like users, sessions, and more. This example uses SQLite for simplicity but can be replaced with any other database, dialect or adapter supported by Better Auth.
• The project use on-demand rendering for all pages so that protected pages are not rendered when the user is not authenticated.
  • The Astro Node.js adapter is used in this example.

Run the example

1. The project requires various environment variables to be set. Duplicate the .env.example file and rename it to .env.development.local (the example file contains links to the documentation for each variable).
2. Install the dependencies using pnpm install.
3. Run the necessary database migrations using pnpm dlx @dotenvx/dotenvx run -f .env.development.local -- pnpm dlx @better-auth/cli migrate which will uses the dotenvx package to load the environment variables from the .env.development.local file and then run the Better Auth CLI which will create the database if needed, check and prompts you to add missing tables or update existing ones with new columns.
4. Run the example using pnpm dev.

To run the example in production mode, start by duplicating the .env.development.local file to .env.production.local, build the project locally using pnpm build and then start the server using node ./dist/server/entry.mjs.

Project Structure

Here is an overview of the various directories and files modified or added to the project to implement authentication to give you a better understanding of how it works:

• .env.development.local: contains the environment variables required by the Better Auth library used during development.
• astro.config.ts: Astro configuration file.
  • Enables on-demand rendering for all pages including documentation pages generated by Starlight.
  • Configures the Astro Node.js adapter.
  • Defines some Starlight component overrides used to filter out protected pages from the sidebar when the user is not authenticated and display authentication links in the navigation bar.
• auth.db: SQLite database file used to store users, sessions, and other data required by the Better Auth library.
• src/auth.ts: Creates a Better Auth instance and configures it with the SQLite adapter and email/password authentication.
• src/middleware.ts: Astro middleware ran on every request.
  • Checks if the user is authenticated and stores that information in the context object.
  • If the user is not authenticated and tries to access a protected page, the middleware will redirect them to the sign-in page.
• src/actions/index.ts: Defines all the Astro Actions which are backend functions used to handle form submissions to create an account, sign in, and sign out.
• src/pages/: Directory containing custom pages for the sign-in, sign-up, and sign-out forms.
• src/overrides/: Directory containing Starlight component overrides used to filter out protected pages from the sidebar when the user is not authenticated and display authentication links in the navigation bar.

License

Licensed under the MIT License, Copyright © HiDeoo.

See LICENSE for more information.