forkready

Pre-flight checks for open source contributors. Clone a repo, run one command, know exactly how to get started.

The problem

You clone a repo to contribute. Now you need to figure out: which package manager? What Node version? Is there an .env.example to copy? A CLA to sign? What's the test command?

You end up opening 4 different files before writing a single line of code.

The fix

npx forkready

That's it. Run it in any cloned Node.js project and get a full report.

What it checks

• Package manager — detects from lockfile (package-lock.json, yarn.lock, pnpm-lock.yaml, bun.lockb) or packageManager field
• Node version — reads .nvmrc, .node-version, .tool-versions, or engines.node and compares against your current version
• Environment files — finds .env.example / .env.sample and tells you if you still need to create .env
• Contributing guide — checks for CONTRIBUTING.md in common locations
• CLA / DCO — detects Contributor License Agreements from config files, workflow files, and contributing docs
• Scripts — extracts the install, build, test, and lint commands from package.json
• Git hooks — detects husky, lefthook, lint-staged, simple-git-hooks
• License — identifies the project license

Example output

  forkready — contributor pre-flight check

  Project: express
  Path:    /home/user/dev/express

  ✓ Package manager: npm (from package-lock.json)
  ✓ Node version: >=18.0.0 required — you have v22.17.1 (from package.json engines.node)
  ⚠ Environment: .env.example found — copy to .env before starting
  ✓ Contributing guide: CONTRIBUTING.md
  ⚠ CLA signing may be required (mentioned in CONTRIBUTING.md)
  ✓ License: MIT
  → Git hooks: husky, lint-staged — will set up on install

  Quick start:
    npm install
    npm run build
    npm run test

  Read CONTRIBUTING.md before submitting a PR.
  Run: cp .env.example .env

Install

Run directly with npx (no install needed):

npx forkready

Or install globally:

npm install -g forkready

Usage

forkready [directory]

If no directory is given, it checks the current working directory.

Programmatic API

import { detectAll, formatResults } from 'forkready';

const results = detectAll('/path/to/repo');
console.log(formatResults(results, '/path/to/repo'));

Exit codes

• 0 — all checks passed
• 1 — problems found (missing package.json or wrong Node version)

Zero dependencies

forkready uses only Node.js built-in modules. No node_modules bloat.

Requirements

Node.js 18 or later.

License

MIT