https://github.com/hideoo/starlight-better-auth-example

Demonstration project using the Better Auth library to add authentication to a Starlight project
https://github.com/hideoo/starlight-better-auth-example

astro authentication better-auth documentation starlight

Last synced: 11 months ago
JSON representation

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

• Host: GitHub
• URL: https://github.com/hideoo/starlight-better-auth-example
• Owner: HiDeoo
• License: mit
• Created: 2024-10-17T07:31:03.000Z (over 1 year ago)
• Default Branch: main
• Last Pushed: 2024-10-18T09:46:38.000Z (over 1 year ago)
• Last Synced: 2025-06-25T09:11:26.273Z (12 months ago)
• Topics: astro, authentication, better-auth, documentation, starlight
• Language: Astro
• Homepage:
• Size: 183 KB
• Stars: 25
• Watchers: 1
• Forks: 2
• Open Issues: 0
• Metadata Files:
  • Readme: README.md
  • License: LICENSE

Awesome Lists containing this project

README

          


  
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](https://www.better-auth.com/) 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](https://www.better-auth.com/) 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](https://docs.astro.build/en/guides/actions/).

- Authentication is handled by the [Better Auth](https://www.better-auth.com/) library.

  - Better Auth requires a [database](https://www.better-auth.com/docs/concepts/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](https://docs.astro.build/en/guides/server-side-rendering/) for all pages so that protected pages are not rendered when the user is not authenticated.

  - The Astro [Node.js adapter](https://docs.astro.build/en/guides/integrations-guide/node/) 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).

1. Install the dependencies using `pnpm install`.

1. 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`](https://github.com/dotenvx/dotenvx) package to load the environment variables from the `.env.development.local` file and then run the [Better Auth CLI](https://www.better-auth.com/docs/concepts/cli) which will create the database if needed, check and prompts you to add missing tables or update existing ones with new columns.

1. 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](https://docs.astro.build/en/guides/deploy/#building-your-site-locally) the project locally using `pnpm build` and then [start](https://docs.astro.build/en/guides/integrations-guide/node/#standalone) 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](https://docs.astro.build/en/guides/configuring-astro/).

  - Enables [on-demand rendering](https://docs.astro.build/en/guides/server-side-rendering/) for all pages including [documentation pages](https://starlight.astro.build/reference/configuration/#prerender) generated by Starlight.

  - Configures the Astro [Node.js adapter](https://docs.astro.build/en/guides/integrations-guide/node/).

  - Defines some Starlight component [overrides](https://starlight.astro.build/guides/overriding-components/) 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](https://www.better-auth.com/docs/reference/options) it with the SQLite adapter and email/password authentication.

- `src/middleware.ts`: Astro [middleware](https://docs.astro.build/en/guides/middleware/) ran on every request.

  - Checks if the user is authenticated and stores that information in the [`context`](https://docs.astro.build/en/guides/middleware/#the-context-object) 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](https://docs.astro.build/en/guides/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](https://starlight.astro.build/guides/pages/#custom-pages) for the sign-in, sign-up, and sign-out forms.

- `src/overrides/`: Directory containing Starlight [component overrides](https://starlight.astro.build/guides/overriding-components/) 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](https://github.com/HiDeoo/starlight-better-auth-example/blob/main/LICENSE) for more information.