Contributing

Prerequisites

You need two things installed. That is it.

• •Bun 1.3.10 or newer. Grab it from bun.sh.
• •Git. Most machines already have it.

Clone and install

Fork the repo on GitHub, clone your fork, then install. Bun workspaces link all 46+ packages and the example app together automatically, so you never need to npm link anything.

git clone https://github.com/YOUR_USERNAME/tekir.git
cd tekir
bun install

Repo layout

It is a Turbo monorepo. Three top-level directories, that is it:

tekir/
├── packages/          # All 46+ @tekir/* packages (the framework itself)
│   ├── tekir-core/    # Router, kernel, DI container, server bootstrap
│   ├── tekir-db/      # ORM
│   ├── tekir-auth/    # Auth guards
│   └── ...            # Everything else
├── apps/              # Sample apps used for integration tests
│   ├── minimal/       # Smallest possible tekir app
│   ├── api/           # Full REST API surface
│   └── ...            # Stack-specific examples (Vite, Next, etc.)
└── example/           # The contributor playground — boots on :5001
    ├── server.ts      # One-file demo with routes, DB, swagger
    └── tests/         # HTTP tests via @tekir/testing

Running things locally

The example app is the fastest way to try a change end to end. From the repo root:

bun run dev   # boots example/ on http://localhost:5001

Edit any package under packages/ and the example will hot-reload — workspace links point straight at the source. The apps under apps/ are runnable too if you want to exercise a specific stack (cd apps/with-vite && bun run dev, etc.).

Running tests

Every package has its own tests and they all run under Bun's test runner. Run them before you open a PR.

bun run test            # Packages + example
bun run test:packages   # Just the packages
bun run test:example    # Just the example app
bun run lint            # ESLint across packages
bun run check           # Lint + tests (run this before pushing)

Making a change

1. 1
   Create a branch off main. Name it something like fix/auth-session-ttl or feat/mail-mailgun-driver.
2. 2
   Write the code. If you are adding behavior, add a test for it. If you are fixing a bug, add a test that would have caught it.
3. 3
   Run bun run check. If it passes, you are good.
4. 4
   Commit with a message that explains why, not just what. Short is fine.
5. 5
   Push to your fork and open a pull request against main.

Code style

ESLint enforces the rules, so you do not need to memorize them. A few things that are not in the linter:

• •Prefer clear names over clever ones. userById beats getU.
• •No any unless it is truly unavoidable. Use generics or unknown first.
• •Keep packages focused. If a helper does not belong in the package you are editing, put it somewhere it does.
• •Public APIs need a short JSDoc comment. Internals can stay as they are.

Reporting bugs or asking for features

Open an issue on GitHub. For bugs include the tekir version, Bun version, and a snippet that reproduces the problem. For feature requests describe the actual use case: we care more about what you are trying to build than the exact shape of the API.

Found a security issue?

Please do not open a public GitHub issue for security vulnerabilities. Filing it in the open puts every tekir user at risk until a patch ships. Instead, email [email protected] with the details and, if you can, a proof of concept. We read these the moment they come in, respond within 24 hours, and coordinate a fix and disclosure window with you before going public.

Thanks

Every contribution, a typo fix, a new driver, a better error message, moves tekir a little closer to being the framework people actually want to use. So thank you for being here.