Contribution Guide [⌐■_■]

Hey there! We are really excited that you are interested in contributing. This is a general contribution guide for most of Nanoo Labs projects.

Before submitting your contribution, please make sure to take a moment and read through the following guide:

Using AI

You're welcome to use AI tools to help you contribute. But there are two important ground rules:

1. Never let an LLM speak for you

When you write a comment, issue, or PR description, use your own words. Grammar and spelling don't matter. Real connection does. AI-generated summaries tend to be long-winded, dense, and often inaccurate. Simplicity is an art. The goal is not to sound impressive, but to communicate clearly.

2. Never let an LLM think for you

No problem if you understand input => process => output from your model AI, and vice versa.

Feel free to use AI to write code, tests, or point you in the right direction. But always understand what it's written before contributing it. Take personal responsibility for your contributions. Don't say "ChatGPT says...". Tell us what you think.

PRs that we consider fully vibe coded may be closed without further explanation.

For more context, see Using AI in open source.

Repository Setup

Nanoo Labs uses pnpm by default. It's the best fit for our workspace setup, so prefer it unless a repo says otherwise.

Step	Command
1. Install Node.js, latest LTS	-
2. Enable Corepack	corepack enable pnpm
3. Install dependencies	pnpm install

Some repos need native build tools (esbuild, sharp, wrangler). They are allowlist in repos pnpm-workspace.yaml. If an install fails on a postinstall script, check that file before deleting anything.

Commands

Nanoo repos use pnpm scripts. Common ones (check the repo's package.json):

Step	Command
Dev server	pnpm dev
Build	pnpm build
Format	pnpm format (or pnpm format:check)
Test / typecheck	pnpm test / pnpm typecheck (when present)

Formatting: Prettier

Nanoo uses Prettier for formatting. With plugins it handles Astro, CSS, Tailwind, and Markdown/MDX, which is what our repos are mostly made of (sites and docs).

We considered Biome (fast, one tool for JS/TS and CSS linting/formatting) and ESLint-only (antfu/contribute). Both are great for pure JS/TS libraries, but neither formats .astro / .md / .mdx. Using either would mean a second tool for those files. So: keep Prettier for all formatting. A linter (Biome or ESLint) may be added later for lint rules only, never as formatter.

Sending a Pull Request

Discuss First

Before you start a big feature, open feature request issue first. Talk with the maintainers about the design. It saves time for everyone.

For typo fixes, batch a few fixes into one PR to keep the commit history clean.

Commit Convention

We use Conventional Commits for commit messages. This lets the changelog be generated automatically.

A commit looks like <type>(scope): message, for example fix(cdn): handle range request.

The type maps to a Nanoo kaomoji group in the changelog:

Type	Kaomoji group
feat	[ ^■^ ] Features
fix	[ ;■_■ ] Bug Fixes
perf	[ █_█ ] Performance
refactor	[⌐■_■] Refactoring
docs	[ ▦_▦ ] Documentation
style	[ ▣_▣ ] Styling & UI
ci	[ ☁_■ ] CI/CD
chore	[ ▓_▓ ] Maintenance
test	[ ¬■_■ ] Testing

Use docs: or chore: for typo / doc / non-code changes (not fix:):

• fix: typo -> docs: fix typo

If your PR fixes an issue, add this line to the PR description:

fix #123

It links the PR to the issue and auto-closes it when merged. See linking a PR to an issue.

Before Submitting

• Run pnpm format to match the code style.
• Run pnpm build (and pnpm test / typecheck when present) to make sure nothing breaks.
• Keep the PR small and focused.

Merge Style

It's okayy to have multiple commits in one PR. We use Squash and Merge, so no need to rebase or force push.

References

Ecosystem

• nanoolabs/.github : org-wide standards: contributing, code of conduct, issue/PR templates.
• nanoolabs/changelog : release notes, ADRs, and brand assets.

Design & Styling

• nanoolabs/css : @nlbs/css, the design system (design tokens, components).
• nanoolabs/theme : design tokens for the ecosystem.

Tooling

• nanoolabs/actions : shared release pipeline (git-cliff + kaomoji).
• nanoolabs/kaomoji : the kaomoji symbols used in changelogs.
• nanoolabs/webrings : the federation registry.
• nanoolabs/status : uptime and incident status.

Docs & Sites

• nanoolabs/docs : central technical docs.
• nanoolabs.dev : the main landing page.