How to Contribute to the Logto Project: A Complete Developer's Guide

To contribute to Logto, clone the monorepo, install dependencies with pnpm, configure a PostgreSQL database via the CLI, and submit changes through the standard GitHub pull request workflow outlined in the official CONTRIBUTING guide.

Logto is an open-source identity and authentication platform organized as a monorepo. This guide explains how to contribute to the Logto project by setting up the development environment, understanding the package structure, and following the testing protocols defined in the source code.

Understanding the Logto Monorepo Architecture

Logto is organized as a monorepo that uses pnpm for package management. The codebase consists of many independent packages that are built and tested together, including:

• packages/core – The core authentication server
• packages/api – API design and OpenAPI specifications
• packages/experience – The sign-in experience front-end
• packages/connectors – Third-party service integrations (SMS, email, social logins)
• packages/elements – Shared UI components

The primary entry point for contribution guidelines is the [.github/CONTRIBUTING.md](https://github.com/logto-io/logto/blob/master/.github/CONTRIBUTING.md) file, which details the workflow for bug fixes, core features, and new connectors.

Prerequisites and Environment Setup

Contributing to Logto requires Node.js 18+, pnpm 9+, and PostgreSQL 14+. Ensure these are installed on your system before proceeding.

Clone the Repository and Install Dependencies

After cloning the repository, install dependencies and generate type declarations using the following commands:

git clone https://github.com/logto-io/logto.git
cd logto
pnpm i && pnpm prepack

The pnpm prepack command is essential as it generates necessary type declarations across the monorepo.

Configure the PostgreSQL Database

Create a .env file in the root directory with your database connection string:

echo "DB_URL=postgresql://postgres:p0stgr3s@localhost:5432/logto" > .env

Seed the database using the Logto CLI:

pnpm cli db seed

If you encounter "undeployed database alterations" errors during development, deploy pending migrations before starting the server:

pnpm alteration deploy

Development Workflow and Testing

Logto emphasizes quick feedback loops during development while requiring comprehensive testing before merge.

Starting the Development Server

Run the following command to start the development server with file watching:

pnpm dev

This monitors packages and automatically restarts services as files change, providing immediate feedback on your modifications.

Testing Your Changes

Testing is split between unit and integration tests. Unit tests validate individual packages, while integration tests verify end-to-end functionality using Docker Compose.

Run unit tests across the entire monorepo:

pnpm ci:test

Or run tests for a specific package by navigating to its directory and executing:

pnpm test

Integration tests require Docker and are executed with:

pnpm test:integration api
pnpm test:integration experience

To collect coverage reports during integration testing, prefix the command:

COVERAGE=1 pnpm test:integration api

Contributing Connectors

Connectors are the extensibility points for third-party authentication services. Official connectors reside in packages/connectors, and new implementations should follow the architectural patterns documented in that directory.

To test a local connector during development, link it to your local Logto instance:

logto connector link -p .

Alternatively, install connectors from NPM:

logto connector add <name> -p .

Submitting Your Contribution

Once your changes are complete and tested, follow the standard Git workflow to submit your contribution. The [.github/CONTRIBUTING.md](https://github.com/logto-io/logto/blob/master/.github/CONTRIBUTING.md) file contains specific guidelines for commit message formatting, branch naming conventions, and pull request descriptions.

git checkout -b your-username/feature-name
git add .
git commit -m "feat: brief description"
git push origin your-username/feature-name

Open a pull request on GitHub and reference any related issues.

Summary

• Logto is a pnpm-managed monorepo requiring Node.js 18+, pnpm 9+, and PostgreSQL 14+
• Initialize the environment with pnpm i && pnpm prepack followed by pnpm cli db seed
• Use pnpm dev for development and pnpm ci:test to validate changes across all packages
• Connectors are located in packages/connectors and can be linked locally using logto connector link
• Follow the contribution workflow defined in .github/CONTRIBUTING.md when submitting pull requests

Frequently Asked Questions

What are the minimum system requirements to contribute to Logto?

You need Node.js version 18 or higher, pnpm version 9 or higher, and PostgreSQL version 14 or higher. These versions ensure compatibility with the monorepo's build tools and database schemas.

How do I resolve "undeployed database alterations" errors when starting the dev server?

Run pnpm alteration deploy before starting the development server. This command applies pending database migrations that are required for the current version of the codebase.

Where are authentication connectors located in the Logto source code?

Official connectors are maintained in the packages/connectors directory. This directory contains implementations for SMS, email, and social login providers, along with documentation for creating custom connectors.

How do I run integration tests locally for the Logto API?

Integration tests require Docker Compose. Execute pnpm test:integration api to run API-specific tests, or pnpm test:integration experience to test the sign-in experience SPA. These commands spin up isolated environments to verify end-to-end functionality.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}