We appreciate your interest in contributing to observerly, and your contributions are integral to enhancing this project. Whether you are addressing a bug, implementing new features, or suggesting improvements, your involvement is highly valued and essential.
orderly is middleware for Cloudflare Queues. It runs on workerd, not Node, and this shapes almost everything below.
- No Node built-ins.
node:fs,node:pathand friends are unavailable at runtime. The TypeScript configuration deliberately omits the DOM library for the same reason: browser-only APIs are not there either. - Tests execute inside workerd, not Node, through
@cloudflare/vitest-pool-workers. A test that passes under Node proves nothing about the runtime orderly ships on. - Node is used only to run the toolchain.
- oxfmt for formatting.
- oxlint for linting, including type-aware rules.
- Conventional Commits for commit messages.
- Semantic Versioning for versioning.
Formatting and linting are not matters of taste here — they are enforced, and a pre-commit hook applies them to staged files automatically.
Every TypeScript file opens and closes with a banner, and separates top-level declarations with the same banner:
/*****************************************************************************************************************/
// @author Michael Roberts <michael@observerly.com>
// @package @observerly/orderly
// @license Copyright © 2026 observerly
/*****************************************************************************************************************/
export const example = (): void => {};
/*****************************************************************************************************************/The banner is exactly 115 characters. @package is the bare package name in src/index.ts, and the
module path elsewhere, such as @observerly/orderly/middleware. Copy an existing file rather than
retyping it.
git clone https://github.com/<REPLACE_WITH_YOUR_USERNAME>/orderly.git
cd orderlyThe quickest route is the development container. Open the repository in an editor that supports Dev Containers and it arrives with the pinned Node and pnpm already in place, with dependencies installed. Nothing else in this section applies.
To work on the host instead, you need Node and pnpm:
nvm install
npm install -g pnpm
pnpm installnvm install reads .nvmrc, so it installs and selects the pinned Node. Any recent pnpm will do:
managePackageManagerVersions is set, so pnpm reads the packageManager field and switches itself
to the pinned version rather than running whatever you happen to have.
pnpm install refuses to run on a Node version below the engines floor, and installs the
pre-commit hook for you. No further setup step is needed.
| Command | What it does |
|---|---|
pnpm build |
Bundles to dist/ with rolldown |
pnpm test |
Runs the suite once, inside workerd |
pnpm test:watch |
Same, in watch mode |
pnpm typecheck |
Typechecks the library and the tests |
pnpm lint |
Fast syntactic lint |
pnpm lint:types |
Type-aware lint, including no-floating-promises |
pnpm lint:package |
Validates the published package shape |
pnpm format |
Formats in place |
Tests live in tests/ and use the .spec.ts suffix.
main is the default branch and the most recent canary version of the codebase. All development
work happens on a separate branch, using a trunk-based workflow.
git checkout -b <COMMIT_TYPE>/<SCOPE>/branch-nameFor example, chore/configuration/oxlint or fix/middleware/retry-delay.
Write clear, concise commits following Conventional Commits.
If your change is one a consumer of the package would notice, it also needs a changeset:
pnpm changesetCommit the generated file alongside your change. Nothing enforces this, so a pull request that needs a changeset and lacks one will merge cleanly and quietly miss the next release. See RELEASING.md for the full process.
Open the pull request against main. CI runs formatting, both lint passes, typechecking, the test
suite, the build and the package checks. All of them must pass.
Reviews are about the change, not the person making it. Expect questions; ask them freely in return.
Open an issue. A report is most useful when it includes the queue configuration involved, the batch or message that triggered it, and what you expected to happen instead.
Also an issue. Describe the queue behaviour you are trying to achieve rather than the API you imagine; there may be a simpler route to it.
This project is governed by the Code of Conduct.