📦️ packlet

What is Packlet?

packlet is the primary command-line interface of the Packlet toolkit, designed to provide a unified, predictable, and developer-friendly workflow for building modern JavaScript/TypeScript packages. It bundles your project, emits type declarations, validates your output, and generates deterministic artifacts that are ready for distribution.

At its core, Packlet is built to be simple: one CLI, one configuration model, and one consistent experience. Whether you are publishing libraries, internal modules, CLI tools, or SDKs, packlet offers a streamlined build-and-prepare pipeline you can rely on.

Why Packlet?

The JavaScript ecosystem offers many build tools, but very few aim to simplify the entire lifecycle of producing a clean, distribution-ready package. Packlet fills this gap by delivering a focused set of features designed for reliability, repeatability, and minimal configuration:

• One command to build, validate, and prepare artifacts—without juggling multiple tools.
• Modern output by default: ESM-first with optional CJS, fully typed, and ready for node and bundlers.
• Deterministic release artifacts (via npm pack) tailored for GitHub Packages (GPR) or any npm registry.
• Clear validation to ensure your dist/ directory contains everything your consumers expect.
• Universal: works with Bun, Node.js, or any toolchain that interoperates with npm packages.
• Zero lock-in: Packlet does not manage your release pipeline; it integrates with your workflow.

If you want a minimal, predictable, and automation-friendly path from src/ to publish-ready artifacts, Packlet is designed for you.

Installation

Install Packlet as a development dependency:

# with bun
bun add -D packlet

# with npm
npm install -D packlet

You may also install it globally:

bun add -g packlet
# or
npm install -g packlet

Quick start

Once installed, the packlet command becomes available:

# build your package (ESM by default; add CJS via --cjs)
packlet build

# create a GPR-ready variant and write a JSON manifest
packlet gpr --root . --json

# list generated tarball artifacts
packlet list-artifacts --artifacts .artifacts

# validate dist contents
packlet validate --root . --json

Or through package.json scripts:

{
  "scripts": {
    "build": "packlet build",
    "build:cjs": "packlet build --cjs",
    "gpr": "packlet gpr --root . --json",
    "validate": "packlet validate --root . --json"
  }
}

CLI commands

packlet build

Builds your package using sensible defaults:

• ESM output (dist/index.mjs)
• Optional CJS output via --cjs
• Type declarations emitted to dist/

Common options:

• --entry <file>: entry point (default: src/index.ts)
• --outdir <dir>: output directory (default: dist)
• --formats <list>: esm,cjs, etc.
• --cjs: shorthand to enable CJS output
• --sourcemap <mode>: external or none
• --types / --no-types: enable or disable .d.ts
• --target <target>: build target (default: node)
• --exec-js: mark output as an executable script
• --minify / --no-minify: minification control
• --external <packages>: treat specific packages as external
• --external-auto: externalize deps and peerDeps automatically

packlet gpr

Stages a GitHub Packages–compatible variant of your package and generates .tgz artifacts.

Key options:

• --root <path>: project root
• --dist <path>: dist directory (default: dist)
• --gpr-dir <path>: staging directory (default: .gpr)
• --artifacts <path>: output directory (default: .artifacts)
• --scope <scope>: npm scope
• --registry <url>: registry URL
• --name <name>: override package name
• --include-readme / --no-include-readme
• --include-license / --no-include-license
• --json: print manifest to stdout
• --manifest <file>: write manifest to file

Packlet copies your build output, adjusts metadata, and uses npm pack to produce deterministic release tarballs.

packlet validate

Ensures your dist/ output contains the expected entry files:

• index.mjs (ESM)
• index.d.ts
• index.js (optional, when CJS is enabled)

Options:

• --root <path>
• --dist <path>
• --json: output as JSON

packlet list-artifacts

Lists .tgz artifacts generated by npm pack.

Options:

• --artifacts <path>
• --json

Configuration

Packlet supports a unified configuration model via package.json.packlet. This allows you to define defaults for all commands in one place.

Example:

{
  "packlet": {
    "distDir": "dist",
    "artifactsDir": ".artifacts",
    "gprDir": ".gpr",

    "build": {
      "entry": "src/index.ts",
      "outdir": "dist",
      "formats": ["esm"],
      "sourcemap": "none",
      "types": true,
      "target": "node",
      "execJs": false,
      "minify": true,
      "external": [],
      "externalAuto": true
    },

    "gpr": true,
    "gprName": "your-package-name",
    "scope": "your-scope",
    "registry": "https://npm.pkg.github.com/",
    "includeReadme": true,
    "includeLicense": true,

    "validate": { "dist": "dist" },
    "listArtifacts": { "artifactsDir": ".artifacts" }
  }
}

Configuration precedence:

1. CLI flags
2. Environment variables (PACKLET_*, GPR_*)
3. package.json.packlet
4. Built-in defaults

For advanced configuration and environment variable behavior, see the @packlet/core.

Programmatic API

Packlet exposes a focused API surface suitable for embedding in your own tools, build scripts, or CI pipelines:

import {
  listArtifacts,
  writeArtifactsManifest,
  validateDist,
  deriveScopedName,
  awakenGpr
} from "packlet"

const result = validateDist({ distDir: "dist" })
const artifacts = listArtifacts(".artifacts")

const manifest = writeArtifactsManifest(".artifacts", {
  packageName: "my-lib",
  scopedName: "@acme/my-lib",
  version: "1.2.3"
})

const gpr = awakenGpr({ rootDir: process.cwd() })
console.log(gpr.scopedName, gpr.version)

Types are also exported:

import type {
  ArtifactEntry,
  ArtifactsManifestV1,
  ValidateDistOptions,
  ValidateDistResult,
  DeriveNameInput
} from "packlet"

License

MIT © KazViz