Contributing

Contributions are what makes the open source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated. To ensure the best possible outcome for everyone, please read this guide carefully before starting work.

Before You Contribute

To make contributing a great experience for everyone and avoid wasted effort, please follow these important steps:

Public Discussion Required

All contribution discussions MUST happen in public channels:
- GitHub Issues/Discussions
- Public Discord channels
Do not send Direct Messages (DMs) to team members about contributions!
- DMs will be redirected to public channels
- This ensures transparency and helps others learn from the discussion

Getting Started

For Existing Issues:
- Look for issues labeled good first issue or help wanted
- Comment on the issue to express your interest
- Wait for a core team member to assign the issue to you
- Only begin work after receiving confirmation
For New Ideas:
- Do not start coding immediately
- Discuss your idea first in our public channels:
  - Create a GitHub issue
  - Start a discussion in our Discord
- Wait for feedback from a core team member
- Only proceed with development after receiving explicit approval

This process helps ensure your contribution aligns with our roadmap and prevents duplicate or conflicting work.

House Rules

Issue and PR Guidelines

Before submitting a new issue or PR, check if it already exists in issues or PRs
Always create an issue before starting development
Reference the issue in your PR using fixes #XXX or refs #XXX

Approval Process

All new issues get a needs-approval label automatically
What Needs Prior Approval:
- New features (large or small)
- Refactoring work
- Changes to core functionality
- UI/UX changes
What Can Start Immediately:
- Bug fixes
- Security improvements
- Documentation updates
- Typo corrections

Prerequisites

You need the following services to run Unkey:

We're currently working on making this optional.

Clerk: Authentication

You also need the following tools installed.

Developing Unkey

Repository

Clone the repo

git clone https://github.com/unkeyed/unkey

Install

cd unkey
corepack enable
pnpm install

Setup local development

Unkey provides a CLI to setup our local development environment. Run the following command in your terminal:

pnpm local

Docker must be running for us to spin up the databases and supporting services.

You will be prompted to enter the following values:

CLERK_SECRET_KEY: Your Clerk secret key.
NEXT_PUBLIC_CLERK_PUBLIC_KEY: Your Clerk public key.

We will create the required .env files depending on the selection you've made.

About pnpm local command

If you have already set up Unkey locally once and wish to bypass the manual input questions the next time, you can do so by using flags with the pnpm local command.

pnpm local [options]

List of available options:

--service=<service>: Specifies which part of the application to develop. The values are dashboard, api, or www
--skip-env: Skips the environment setup prompt if specified.

Example:

pnpm local --service=dashboard --skip-env

Contributing

On this page