Contributing

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/auth0/nextjs-auth0/llms.txt

Use this file to discover all available pages before exploring further.

​

Code of Conduct

​

Our Standards

• Using welcoming and inclusive language
• Being respectful of differing viewpoints and experiences
• Gracefully accepting constructive criticism
• Attempting collaboration before conflict
• Focusing on what is best for the community
• Showing empathy towards other community members

• Violence, threats of violence, or inciting self-harm
• Sexualized language or imagery and unwelcome sexual attention
• Trolling, spreading misinformation, insulting/derogatory comments
• Public or private harassment
• Publishing others’ private information without permission
• Abuse of the reporting process
• Other conduct inappropriate in a professional setting

​

Reporting Issues

​

Getting Started

​

Prerequisites

• Node.js: Version 20 LTS or newer
• pnpm: Package manager (install via npm install -g pnpm)
• Git: Version control

​

Environment Setup

1. Fork the repository Fork auth0/nextjs-auth0 to your GitHub account.
2. Clone your fork
   git clone https://github.com/YOUR_USERNAME/nextjs-auth0.git
   cd nextjs-auth0
   
3. Install dependencies
   pnpm install
   
4. Create a branch
   git checkout -b feature/my-feature
   

​

Development Workflow

​

Available Commands

​

Building the Project

pnpm run build

pnpm run build:watch

​

Running Tests

pnpm test:unit

pnpm run test:coverage

# Set up Auth0 test credentials
export TEST_USER_PASSWORD=your-test-password

pnpm run test:e2e

​

Linting and Type Checking

pnpm run lint

pnpm run lint:fix

​

Generating Documentation

pnpm run docs

npx http-server docs

​

Project Structure

src/
├── client/           # React hooks, Auth0Provider, client getAccessToken
│   ├── hooks/        # useUser
│   ├── helpers/      # getAccessToken, withPageAuthRequired
│   └── providers/    # Auth0Provider
├── server/           # Auth0Client (public API), AuthClient (internal)
│   ├── session/      # Stateless (cookie) + Stateful (external store)
│   ├── helpers/      # withPageAuthRequired, withApiAuthRequired
│   ├── client.ts     # Auth0Client - main public class
│   └── auth-client.ts # Internal route handling + OAuth flows
├── errors/           # SdkError hierarchy (catch by error.code)
├── types/            # SessionData, User, TokenSet, AuthorizationParameters
├── utils/            # Internal: dpop, paths, scopes, urls
└── testing/          # generateSessionCookie for test session setup

​

Making Changes

​

Coding Standards

• TypeScript: Use TypeScript for all source files
• Formatting: Code is automatically formatted with Prettier
• Linting: Follow ESLint rules
• Tests: Write tests for new features and bug fixes
• Documentation: Update documentation for API changes

​

Commit Messages

feat: add support for custom transaction cookies

fix: resolve state validation error with parallel auth flows

docs: update configuration options table

test: add flow tests for DPoP key generation

• feat: New feature
• fix: Bug fix
• docs: Documentation changes
• test: Test changes
• refactor: Code refactoring
• chore: Build/tooling changes

​

Testing Guidelines

• Test individual functions and classes
• Mock external dependencies
• Co-locate tests with source files (*.test.ts)

• Test end-to-end authentication flows
• Use MSW for HTTP mocking
• No other mocks unless absolutely necessary
• Name files *.flow.test.ts

// src/server/client.test.ts
import { describe, it, expect } from "vitest";
import { Auth0Client } from "./client";

describe("Auth0Client", () => {
  it("should instantiate with valid config", () => {
    const client = new Auth0Client({
      domain: "test.auth0.com",
      clientId: "test-client-id",
      clientSecret: "test-secret",
      secret: "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
    });
    
    expect(client).toBeDefined();
  });
});

​

Documentation

• New configuration options
• New public APIs
• Breaking changes
• New features

• README.md: Getting started guide
• EXAMPLES.md: Usage examples and patterns
• API documentation: Generated from JSDoc comments

​

Submitting Changes

​

Pull Request Process

1. Ensure all tests pass
   pnpm run test:coverage && pnpm run prepack && pnpm run lint:fix
   
2. Update documentation Add or update relevant documentation files.
3. Create a pull request Push your branch and create a PR against main:
   git push origin feature/my-feature
   
   Go to github.com/auth0/nextjs-auth0 and click “New Pull Request”.
4. Describe your changes Provide a clear description of:
   • What the change does
   • Why it’s needed
   • How to test it
   • Breaking changes (if any)
5. Wait for review Maintainers will review your PR and may request changes.

​

Pull Request Checklist

• All tests pass (pnpm run test:coverage)
• Linting passes (pnpm run lint)
• Build succeeds (pnpm run build)
• Documentation updated
• Commit messages follow conventions
• Changes are backwards compatible (or breaking changes documented)
• Added tests for new features
• PR description is clear and complete

​

Breaking Changes

1. Mark it clearly in the PR title: [BREAKING] feat: ...
2. Document migration steps in the PR description
3. Update CHANGELOG.md with breaking change notes
4. Consider deprecation before removing features

​

Reporting Issues

​

Bug Reports

• Description: Clear description of the issue
• Reproduction: Steps to reproduce the behavior
• Expected behavior: What you expected to happen
• Actual behavior: What actually happened
• Environment:
  • SDK version (@auth0/nextjs-auth0 version)
  • Next.js version
  • Node.js version
  • Browser (if applicable)
• Code sample: Minimal reproduction code
• Error messages: Full error messages and stack traces

## Description
Session cookie not persisting after login

## Reproduction
1. Configure Auth0Client with default settings
2. Navigate to /auth/login
3. Complete authentication
4. Redirect to callback
5. Session is not available

## Expected
Session should be available after successful authentication

## Actual
getSession() returns null

## Environment
- @auth0/nextjs-auth0: 3.5.0
- Next.js: 14.1.0
- Node.js: 20.10.0
- Browser: Chrome 120

## Code
\`\`\`typescript
const auth0 = new Auth0Client({
  domain: "test.auth0.com",
  clientId: "...",
  // ...
});
\`\`\`

## Error
\`\`\`
No error, session is simply not set
\`\`\`

​

Feature Requests

• Use case: Describe your use case
• Proposed solution: How you envision it working
• Alternatives: Other solutions you’ve considered
• Additional context: Any other relevant information

​

Security Vulnerabilities

​

Additional Resources

​

Contributing Guidelines

• Auth0’s General Contribution Guidelines
• Auth0’s Code of Conduct
• This repo’s contribution guide

​

Documentation

• README.md: Getting started
• EXAMPLES.md: Usage examples
• API Reference: Generated API docs
• Auth0 Docs: Auth0 platform documentation

​

Community

• GitHub Issues: Bug reports and feature requests
• Auth0 Community: Ask questions and get help
• GitHub Discussions: Discussions and ideas

​

License

​

Thank You!