Output layouts

The four layouts

per-spec (default) — one tarball per requested package, each with its own complete closure. Shared dependencies repeat, so the total is larger, but every tarball imports, rolls back and hands off on its own.

packall react@19.2.8 react-dom@19.2.8 --out ./bundles

  ./bundles/react@19.2.8.tgz  26 KB  (1 package)
  ./bundles/react-dom@19.2.8.tgz  1.3 MB  (3 packages)

  2 artifacts in ./bundles (1.3 MB total)

react appears in both, because react-dom needs it and each tarball carries its own complete closure.

single — one tarball for everything, deduplicated. Smallest output and a single import step; all-or-nothing to roll back.

packall react@19.2.8 react-dom@19.2.8 --layout single --out ./bundles

  ./bundles/bundle.tgz  1.3 MB  (3 packages)

  1 artifact in ./bundles (1.3 MB total)

Three packages rather than four: react is in there once.

--archive-name renames it.

dir — the unpacked tree, ready for jf rt upload or rsync. No archive step.

packall react@19.2.8 --layout dir --out ./bundles

flat — every tarball in one directory, nothing nested. No archive step. For tooling that globs *.tgz rather than walking a registry tree.

packall react@19.2.8 react-dom@19.2.8 --layout flat --out ./bundles

./bundles/
  IMPORT.md
  bundle-manifest.json
  react-dom@19.2.8.tgz
  react@19.2.8.tgz
  scheduler@0.27.0.tgz

File names keep the scope — @types/node is @types-node@20.11.0.tgz, not node-20.11.0.tgz. Dropping it, as the registry file name does, would put @types/node and node on the same file and lose one of them. Nothing reads the name on the way back in: npm publish takes a package's name and version from the package.json inside the tarball, and the tarballs here are the registry's own, unmodified.

Being asked

Leave --layout off and you are asked once, but only when it would matter: more than 20 archives, or duplication of 2× or worse.

? This will write 2 archives holding 2 entries in total, but only 1 distinct
 package (~2.0× duplication). How should it be laid out? ›
  per-spec — 2 tarballs, import and roll back one at a time
❯ single — one tarball, 1 packages, deduplicated
  dir — unpacked tree, no archive
  flat — every tarball in one directory, no archive

Transitive dependencies inflating the entry count is not a reason to ask — a handful of packages pulling in hundreds of distinct dependencies is just what a dependency tree looks like.

In CI, behind a pipe, or with --yes, the default stands and nothing blocks. --layout-threshold N answers the question in advance: switch to single at N archives without asking. --layout-threshold 0 neither asks nor switches.

Where it goes

--out names the directory, creating it if needed. Without it, bundles are written to the current directory.

Nothing is ever written outside --out. Intermediate files live in a scoped temporary directory that is removed on success, on failure, and on Ctrl-C.

Overwriting

By default, a run that would replace an existing file asks about it per file. Two flags settle it up front:

--force-spec composes with --force rather than overriding it, so --no-force --force-spec tsdown means "refuse, except tsdown".