# Contributing to Aura Auth Thank you for considering contributing to Aura Stack Auth! It's people like you that make this project such a great tool for the community. Getting Started [#getting-started] The following steps outline how to set up the local environment. Fork the repository [#fork-the-repository] The [Aura Auth repository](https://github.com/aura-stack-js/auth) should be forked by clicking the "Fork" button in the top right corner. Clone your fork [#clone-your-fork] Clone your fork locally: ```bash git clone https://github.com/YOUR_USERNAME/auth.git cd auth ``` If you're new to contributing on GitHub, see [Contributing to a project](https://docs.github.com/en/get-started/exploring-projects-on-github/contributing-to-a-project). Add upstream remote [#add-upstream-remote] An upstream remote repository should be configured to keep the fork in sync. See [GitHub docs](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/configuring-a-remote-repository-for-a-fork). ```bash git remote add upstream https://github.com/aura-stack-ts/auth.git ``` Install dependencies [#install-dependencies] Aura Auth uses [pnpm](https://pnpm.io/) as its package manager. ```bash pnpm install ``` Contribute [#contribute] Once the scope of the contribution is defined, changes can be implemented. Create a new branch [#create-a-new-branch] Always keep your fork synced with upstream before starting new work: ```bash # syncronize the repo git switch master && git pull upstream master # create a new branch to work in. git switch -c feature/your-feature-name ``` implement changes [#implement-changes] Changes are implemented in the development environment. Packages server: ```bash pnpm dev ``` Documentation server ```bash pnpm dev:docs ``` Write or update tests [#write-or-update-tests] Tests must be written or updated to ensure changes are covered. ```bash # Run tests pnpm test # Run tests with coverage pnpm test:coverage ``` Code style [#code-style] Type checking and formatting must be verified. ```bash pnpm type-check ``` Format codebase: ```bash # format code pnpm format # check formating pnpm format:check ``` Commit changes [#commit-changes] Changes should be committed following the [Conventional Commits](https://www.conventionalcommits.org/) specification. ```bash git commit -m "feat(auth): add support for OAuth 2.0 PKCE flow" ``` Push to the fork: ```bash git push origin feature/your-feature-name ``` Open a pull request Go to GitHub and open a [Pull Request](https://github.com/aura-stack-ts/auth/pulls) with: * Clear and descriptive title * Reference to related issues * Comprehensive description of changes * Screenshots or GIFs for UI changes (if applicable) Development Workflow [#development-workflow] Project Structure [#project-structure] ``` auth/ ├── packages/ │ ├── core/ # Main authentication library │ │ ├── src/ # Source code │ │ └── test/ # Tests │ └── jose/ # JOSE utilities │ ├── src/ # Source code │ └── test/ # Tests ├── docs/ # Documentation site (Fumadocs) ├── apps/ # Example applications └── turbo.json # Turborepo configuration ``` Running Tests [#running-tests] ```bash # Run all tests pnpm test # Run tests in watch mode pnpm test:watch # Run tests with coverage pnpm test:coverage ``` Best practices [#best-practices] * TypeScript should be used for all new code. * Variable and function names should be meaningful. * TSDoc comments should be added for public APIs. * Functions should be kept small and focused. * Tests must be written for new features. * Existing code patterns should be followed. Your contributions help make authentication easier and more secure for developers everywhere. Need help ? [#need-help-] If you're unsure where to start: * Browse the [issue tracker](https://github.com/aura-stack-ts/auth/issues) * Look for labels: * good first issue * help wanted * Open a new issue if you have questions or suggestions. Thank you again for contributing to Aura Auth. # FAQ Frequently Asked Questions [#frequently-asked-questions] Why does Aura Auth exist? [#why-does-aura-auth-exist] Aura Auth exists thanks to Auth.js, which has been one of the most important and useful authentication libraries for JavaScript applications in recent years, providing a wide range of authentication methods for modern web apps, especially for `OAuth 2.0` and `OpenID Connect` flows. However, on September 22, 2025, it was announced that the core maintainer team would be stepping away from Auth.js, which has now become a side project of Better Auth (an authentication framework for TypeScript). Consequently, as a previous Developer Experience contributor to Auth.js, the decision was made to create a new alternative authentication library for TypeScript applications, inspired by Auth.js. Aura Auth is the spiritual successor to Auth.js — designed for the next generation of TypeScript applications. Secure by default (Philosophy) [#secure-by-default-philosophy] Aura Auth is built on a simple philosophy: > Provide a framework-agnostic, secure, and ergonomic authentication system — powered by open web standards like **OAuth 2.0** and **OpenID Connect**. Security is not optional. Aura Auth enforces best practices by default: * PKCE on all supported OAuth flows * Mandatory state parameters * Cookie security (HTTP-only, Secure, SameSite) * CSRF protection via JWS * Verified redirect URLs * Strong cryptographic guarantees Aura Auth lets developers focus on building products — not re-implementing the same security layers again and again. # Astro This example demonstrates how to use Aura Auth with Astro. It includes a simple authentication flow using GitHub as an OAuth provider, showcasing how to integrate Aura Auth into an Astro application. Open this example in StackBlitz: [Open in StackBlitz](https://stackblitz.com/github.com/aura-stack-ts/auth/tree/master/apps/astro) and [GitHub](https://github.com/aura-stack-ts/auth/tree/master/apps/astro)