mongez-pkgist-overview

name	mongez-pkgist-overview
description	@mongez/pkgist — build, version, and publish tool for TypeScript/React npm packages. Powered by tsdown (Rolldown/Rust-based). Standalone packages or version-synchronised families, dual ESM+CJS, git tag+push automation, dry-run mode.

@mongez/pkgist — Overview

A build, version, and publish tool for TypeScript/React npm packages. Powered by tsdown (Rolldown/Rust-based bundler). Configure once, ship many packages — standalone with independent versioning or grouped into families with synchronised versioning. Dual ESM+CJS output, asset cloning, git tag + push automation, dry-run mode that touches nothing.

Highlighted features

tsdown-powered builds

Rolldown under the hood — Rust-fast compilation, dual ESM+CJS output, .d.ts emission, sub-path entries, zero per-package boilerplate.

Standalone or family

standalone[] bumps versions independently. families[] synchronises versions across grouped packages — one bump moves the whole family.

Auto-versioning

Defaults to patch bumps. Set version: "minor" or "major" per package or family. Source package.json updates in place, ready to commit.

Git tag + push automation

commit: true stages the version bump, tags v<version>, and pushes per repo. Custom commit message via commit: "Released <version>".

--dry-run mode

Inspect every step (snapshot, compile, clone, commit, publish) without touching disk, git, or npm. Catch surprises before they ship.

Asset cloning

clone: ["README.md", "LICENSE", "skills"] — whitelisted files copy verbatim into the build. Your published package always has its docs.

What pkgist does, per package

1. Reads source package.json, resolves the next version (auto-patch by default).
2. Compiles src/ with tsdown into esm/ + cjs/ + .d.ts.
3. Clones whitelisted assets (README, LICENSE, skills, llms.txt, etc.) into the build.
4. Writes a clean package.json for the build (no devDeps, no scripts).
5. Updates source package.json version in place.
6. Commits, tags v<version>, and pushes (when commit is set).
7. Publishes to npm with configured access.

Per-package pipelines run in parallel up to the configured concurrency.

Install

npm install -D @mongez/pkgist
# or: yarn add -D @mongez/pkgist
# or: pnpm add -D @mongez/pkgist

Prefer the dev-dep install — it pins the version per repo. Global install (npm install -g @mongez/pkgist) is also supported when you want one CLI binary across projects.

Add convenience scripts:

{
  "scripts": {
    "release":     "pkgist build:all",
    "release:dry": "pkgist build:all --dry-run"
  }
}

Quick peek

# Scaffold a pkgist.config.ts in the current directory
npx pkgist init

# Inspect every step without touching disk / git / npm
npx pkgist build:all --dry-run

# Real run: bumps versions, commits + tags + pushes per repo, publishes to npm
npx pkgist build:all

# Target one package
npx pkgist build @my-scope/utils

# Target a synchronized family (all members share the new version)
npx pkgist build:family core

Once a pkgist.config.ts exists, the release flow is two commands — dry-run first to inspect, then real build.

Minimum viable config

Run pkgist init, or create pkgist.config.ts by hand at the project root:

import { defineConfig } from "@mongez/pkgist";

export default defineConfig({
  settings: {
    buildDir: "../builds",
  },
  standalone: [
    {
      name: "@my-scope/utils",
      root: "../utils",
    },
  ],
});

That's the floor. From there:

• Add commit: true for auto-tagged git commits with Released <version> messages.
• Add clone: ["README.md", "LICENSE"] to ship docs.
• Add version: "minor" to bump beyond patch.
• Group related packages into families[] to share a version.

Where to go next

• CLI — every command + flag (build, build:all, build:family, validate, list)
• Configuration — full config shape, defineConfig, settings
• Package options — every per-package field
• Pipeline — what happens step-by-step per package
• Versioning — auto/patch/minor/major + family rules
• Git workflow — commit shapes (string / true / false), tagging, push
• Recipes — common patterns ready to copy