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.

What you'll learn

Getting started
Contribute
Development workflow

Getting Started

The following steps outline how to set up the local environment.

Fork the repository

The Aura Auth repository should be forked by clicking the "Fork" button in the top right corner.

Clone your fork

Clone your fork locally:

git clone https://github.com/YOUR_USERNAME/auth.git
cd auth

If you're new to contributing on GitHub, see Contributing to a project.

Add upstream remote

An upstream remote repository should be configured to keep the fork in sync. See GitHub docs.

git remote add upstream https://github.com/aura-stack-ts/auth.git

Install dependencies

Aura Auth uses pnpm as its package manager.

pnpm install

Contribute

Once the scope of the contribution is defined, changes can be implemented.

Create a new branch

Always keep your fork synced with upstream before starting new work:

# 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

Changes are implemented in the development environment.

Packages server:

pnpm dev

Documentation server

pnpm dev:docs

Write or update tests

Tests must be written or updated to ensure changes are covered.

# Run tests
pnpm test

# Run tests with coverage
pnpm test:coverage

Code style

Type checking and formatting must be verified.

pnpm type-check

Format codebase:

# format code
pnpm format

# check formating
pnpm format:check

Commit changes

Changes should be committed following the Conventional Commits specification.

git commit -m "feat(auth): add support for OAuth 2.0 PKCE flow"

Push to the fork:

git push origin feature/your-feature-name

Open a pull request

Go to GitHub and open a Pull Request with:

Clear and descriptive title
Reference to related issues
Comprehensive description of changes
Screenshots or GIFs for UI changes (if applicable)

Development Workflow

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

# Run all tests
pnpm test

# Run tests in watch mode
pnpm test:watch

# Run tests with coverage
pnpm test:coverage

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 ?

If you're unsure where to start:

Browse the issue tracker
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.

Contributing to Aura Auth

On this page