create-oss-monorepo

A Vite-style scaffolding CLI: one interactive command generates a new open-source monorepo — apps/ + packages/ workspaces, GitHub community health files, CI, licensing, and contributor docs — instead of you assembling them by hand.

The layout it produces (workspaces under apps//packages/, docs/adr/, .github/workflows, AGENTS.md for AI coding agents, etc.) is modeled on real-world open-source repos of this shape.

Usage

npm create oss-monorepo my-project
# or
npx create-oss-monorepo my-project

Answer the prompts and a ready-to-push repository is generated in my-project/.

Non-interactive usage

Every prompt can be supplied as a flag instead, which also skips that question:

npm create oss-monorepo my-project -- \
  --description="A thing that does stuff" \
  --github-owner=my-org \
  --repo-name=my-project \
  --author-name="Ada Lovelace" \
  [email protected] \
  --author-github=ada \
  --license=apache-2.0 \
  --runtime=pnpm \
  --features=ci,issueTemplates,prTemplate,contributing,security,coc,renovate,agentsFile

Run npm create oss-monorepo -- --help for the full flag list.

What gets asked

• Project name & short description

• GitHub org/username that will own the repo, and the repo name

• Your name, email, and personal GitHub username — used for copyright notices, SECURITY.md contact, and .github/CODEOWNERS

• License — MIT, Apache-2.0, BSD-3-Clause, ISC, Unlicense (embedded verbatim), or GPLv3/AGPLv3 (fetched from GitHub's Licenses API at generation time so the text is always the canonical, current version)

• Package manager / runtime — npm, pnpm, yarn, bun, or Deno (workspaces configured accordingly — package.json workspaces for the Node.js family, deno.json "workspace" for Deno)

• Which OSS files to include (multi-select, sensible defaults preselected):

  | Feature | What it adds | | --- | --- | | ci | GitHub Actions workflow: install, lint, test | | issueTemplates | Bug report + feature request issue forms | | prTemplate | Pull request template | | contributing | CONTRIBUTING.md | | security | SECURITY.md with private vulnerability reporting | | coc | CODE_OF_CONDUCT.md (Contributor Covenant) | | codeql | CodeQL security scanning workflow | | renovate | Automated dependency update config | | gitleaks | Secret-scanning config + CI workflow | | cla | CLA.md + CLA-assistant bot workflow | | agentsFile | AGENTS.md — a guide for AI coding agents working in the repo | | funding | .github/FUNDING.yml |

Adopting an existing repo

Already have a repo and just want the missing community-health files — CONTRIBUTING.md, SECURITY.md, CI, issue templates, etc. — without restructuring your project into apps/+packages/? Run with --adopt:

cd my-existing-repo
npx create-oss-monorepo --adopt

--adopt behaves differently from a normal scaffold:

• It never touches your source tree — the apps//packages/ workspace layout and starter app/library are not copied, and nothing in package.json/deno.json is modified.
• It never overwrites a file that already exists (README, .gitignore, LICENSE, .github/CODEOWNERS, etc. are left untouched if present).
• Prompt defaults are pre-filled from your existing repo where possible (package manager from your lockfile, name/description/license from package.json, owner/repo from git remote origin) — you can still edit any of them, or override with the same flags as a normal scaffold.
• It prints which files were added vs. skipped, and suggests reviewing + committing rather than git init/gh repo create.

Since it doesn't restructure anything, the generated CI workflow's install/ lint/test commands still assume your existing package.json scripts follow the shape described above (e.g. npm run lint --workspaces --if-present) — adjust .github/workflows/ci.yml by hand if your repo doesn't match.

What you get

my-project/
├── apps/
│   └── example-app/       # starter app wired to example-lib — replace or delete
├── packages/
│   └── example-lib/       # starter shared library, with a passing test
├── docs/adr/               # architecture decision record template
├── .github/                 # workflows + templates for the features you picked
├── LICENSE
├── README.md
└── <workspace root config for your chosen runtime>

The starter app and library are wired together and runnable immediately — npm install && npm run build (or the pnpm/yarn/bun/deno equivalent) works out of the box, so you have something real to delete pieces of rather than an empty shell.

Development

This CLI itself has no build step — it's plain ESM Node.js.

npm install
node index.js /tmp/some-test-dir --name=test --github-owner=me ...

Templates live under templates/:

• templates/base/ — always included
• templates/runtime/<npm|pnpm|yarn|bun|deno>/ — workspace root config
• templates/starter/<node|deno>/ — the example app + library
• templates/optional/<feature>/ — one directory per toggle in the features list above

Files are copied with {{PLACEHOLDER}} tokens substituted (see src/generate.js); a leading underscore in a template filename (e.g. _gitignore, _github) becomes a leading dot in the generated project, so dotfiles survive npm packaging.

License

MIT