create-packkit

# Packkit 📦

> A highly configurable scaffolder for modern **npm packages and CLIs** — pick your stack from a CLI **or** a web configurator, and get a ready-to-ship repo.

[![npm version](https://img.shields.io/npm/v/create-packkit?style=flat-square&logo=npm&color=cb3837)](https://www.npmjs.com/package/create-packkit)
[![npm downloads](https://img.shields.io/npm/dm/create-packkit?style=flat-square&logo=npm&color=cb3837&label=downloads)](https://www.npmjs.com/package/create-packkit)
[![CI](https://img.shields.io/github/actions/workflow/status/PackkitJS/create-packkit/ci.yml?style=flat-square&logo=github&label=CI&branch=main)](https://github.com/PackkitJS/create-packkit/actions/workflows/ci.yml)
[![install size](https://img.shields.io/badge/install%20size-tiny-44cc11?style=flat-square)](https://packagephobia.com/result?p=create-packkit)
[![License: MIT](https://img.shields.io/npm/l/create-packkit?style=flat-square&color=blue)](LICENSE)
<br/>
[![Configure on the web](https://img.shields.io/badge/⚙_configure-on_the_web-00e5ff?style=flat-square)](https://packkitjs.github.io/create-packkit/)
[![MCP server](https://img.shields.io/badge/MCP-packkit--mcp-8a5cf6?style=flat-square)](mcp)
[![llms.txt](https://img.shields.io/badge/llms.txt-✓-000000?style=flat-square)](https://packkitjs.github.io/create-packkit/llms.txt)
[![PRs welcome](https://img.shields.io/badge/PRs-welcome-brightgreen?style=flat-square)](CONTRIBUTING.md)

Most scaffolders lock you into one stack, one language, and the terminal. Packkit lets you **choose** — TypeScript or JavaScript, library or CLI, ESM/CJS/dual, your bundler, test runner, linter, git hooks, release flow, GitHub Actions and more — and it works from a CLI **or** a browser page that downloads your project as a zip.

## Quick start

```sh
# interactive wizard
npm create packkit@latest
# or with npx
npx create-packkit

# skip the wizard with a preset
npx create-packkit ts-lib my-lib
npx create-packkit cli my-tool
npx create-packkit --preset full my-pkg --pm pnpm
```

Then `cd`, and you already have a working project — `build`, `test`, and `lint` all pass out of the box.

## Create the repo, not just the folder

Packkit can create the remote and push the first commit, so you don't have to make an empty repo in a browser first:

```sh
# create it on GitHub (private) and push
npx create-packkit ts-lib my-lib --github

# public instead
npx create-packkit ts-lib my-lib --github --public

# any other host — GitLab, Bitbucket, Gitea, self-hosted
npx create-packkit ts-lib my-lib --git-remote git@bitbucket.org:me/my-lib.git
```

`--github` shells out to the [GitHub CLI](https://cli.github.com), so **Packkit never asks for, reads, or stores a token** — `gh` already holds your credentials. Created repos are **private unless you pass `--public`**.

This also fixes your links: the repository URL is baked into `package.json` and the README's CI badges when the files are generated, so letting Packkit resolve it up front means the badges point somewhere real from the first commit.

### Scaffolding into a repo you already have

Already cloned an empty repo, or started some work? `--merge` scaffolds around what's there:

```sh
git clone git@github.com:me/my-lib.git && cd my-lib
npx create-packkit ts-lib my-lib --here --merge
```

**Existing files are never overwritten.** Anything that collides is left alone and reported, so you can diff at your leisure. (A directory containing only `.git` counts as empty — a fresh clone scaffolds without needing `--merge` at all.)

## Keep a project current

Every scaffolded project records what it came from in `packkit.json`. Later, from
inside the project:

```sh
npx create-packkit upgrade          # dry run: what's changed since you scaffolded
npx create-packkit upgrade --apply  # bring in the additive changes, keep your edits
```

Upgrade regenerates the project Packkit would produce today and diffs it against
disk. **`--apply` is non-destructive**: it brings in *additions* and preserves
anything that already exists but differs — because without a stored baseline it
can't tell a template change from your own edit. Replacing differing values is
opt-in, per category:

| Change                | Default `--apply` | Explicit replacement       |
| --------------------- | ----------------- | -------------------------- |
| New file              | Applied           | Applied                    |
| Changed file          | Preserved         | `--replace-files` (or `--force`) |
| New script            | Applied           | Applied                    |
| Changed script        | Preserved         | `--update-scripts` (or `--force`) |
| New dependency        | Applied           | Applied                    |
| Changed dependency    | Preserved         | `--update-deps` (or `--force`) |
| Changed package field | Preserved         | `--force`                  |
| Removed template file | Reported          | No automatic deletion      |

Your own files, scripts, and dependencies are never touched by `--apply`. The
report lists everything preserved so you can review it and opt into replacement
where you want Packkit's version.

**Baseline-aware (new projects).** Projects scaffolded with Packkit 3.3+ record
a baseline of what was generated (in `packkit.json`), so upgrade can do a
three-way comparison and tell the difference between a change *you* made and one
the *template* made:

- **template-only change** (you didn't edit it) → applied by `--apply`, safely;
- **your edit** (the template didn't change) → preserved;
- **both changed** → flagged as a conflict to review.

**Older projects** without a baseline fall back to the conservative rule:
anything that differs is preserved for review.

Either way, `--apply` never overwrites your own edits or resolves conflicts for
you — those are always preserved. `--json` reports the classification and
`baselineAvailable` for automation.

**Honest provenance.** After an upgrade, `packkit.json` records what actually
happened rather than claiming the project is a fresh scaffold of the new
version. `version` (the version you generated with) is left untouched;
`lastUpgradeAppliedWith` records the version applied, and `upgradeStatus` is
`current` only when nothing was left behind — a partial upgrade that preserved
your edits is marked `partial` with an `unresolvedChanges` count.

## Or configure it on the web

No install needed: **[packkitjs.github.io/create-packkit](https://packkitjs.github.io/create-packkit/)** — tick the options, preview the file tree, and **download a zip** (or copy the equivalent `npx create-packkit` command). Everything runs in your browser.

## Options reference

Every flag, its values (**default** in bold), and what it's for. Prefer the interactive [web configurator](https://packkitjs.github.io/create-packkit/) — the same descriptions appear as you hover. _This table is generated from the schema (`npm run gen:reference`)._

<!-- OPTIONS:START -->

### Package

| Flag | Values | What it does |
|---|---|---|
| `--name` | — | The npm package name. Scoped names like `@you/pkg` are fine. |
| `--description` | — | One-line summary — used in package.json and the README heading. |
| `--author` | — | Your name (and optionally email/URL). Populates package.json + LICENSE. |
| `--keywords` | — | Comma-separated npm keywords to help people discover the package. |
| `--repo` | — | Git repository URL. Wires up repository/bugs/homepage links and CI badges. |

### Core

| Flag | Values | What it does |
|---|---|---|
| `--language` | **ts** · js | TypeScript (strict, recommended) or plain ESM JavaScript. TS gives you types, editor help, and generated .d.ts for consumers. |
| `--module` | **esm** · dual · cjs | How the package is consumed. ESM-only (default) is the modern, leanest choice — Node 20.19+/22.12+ can `require()` ESM. Pick dual only if you must support older CJS-only consumers; cjs-only is rarely needed. |
| `--server` | **hono** · fastify · express | For the service target: Hono (fast, web-standard, tiny — default), Fastify (batteries-included, plugins, schema validation), or Express (ubiquitous, huge ecosystem). |
| `--target` | **library** · cli · service · app | What you are building — mix and match: a library (importable package), a CLI (ships a bin), an HTTP service, or an app (Vite SPA). |
| `--monorepo` | on / off (default: **off**) | Generate a pnpm + Turborepo workspace with two linked example packages and Changesets. Only worth it when ≥2 packages share code. |
| `--monorepo-layout` | **libraries** · fullstack | What the workspace contains. "libraries" gives linked packages you publish (Changesets). "fullstack" gives apps/web (React+Vite) + apps/server (Hono by default; --server for Fastify/Express) + packages/shared, wired together, with the server serving the web build in production. |
| `--framework` | **none** · react · vue · svelte | UI framework for component libraries and apps: React, Vue, or Svelte (or none for a plain package). |
| `--pm` | **npm** · pnpm · yarn · bun | Which package manager the scripts, lockfile, and CI target: npm, pnpm, yarn, or bun. |
| `--node` | 22 · **24** · 26 | Minimum Node line to support. Choices track Node’s own release schedule (Active LTS is the default); this sets engines + .nvmrc. |

### Build

| Flag | Values | What it does |
|---|---|---|
| `--bundler` | **tsup** · tsdown · unbuild · rollup · none | How the library is built. tsup (default, esbuild-fast) and tsdown suit most libs; unbuild for zero-config; rollup for full control; none = tsc-only (or no build). |
| `--minify` | on / off (default: **off**) | Minify the build output. Best for CLIs and browser bundles; usually unnecessary for libraries (consumers minify). |
| `--no-sourcemaps` | on / off (default: **on**) | Ship source + JS/declaration maps so consumers can step into and go-to-definition on your original code when debugging. On by default for libraries. |

### Quality

| Flag | Values | What it does |
|---|---|---|
| `--tes