vp pack Build Output Differences: npm Publishing vs Standalone Binaries

vp pack generates compiled JavaScript libraries in a dist/ directory for npm distribution, while the experimental --exe flag produces a single native executable binary using Node.js SEA instead of distributable source files.

In the voidzero-dev/vite-plus ecosystem, the vp pack command serves dual purposes for package authors. Depending on your deployment target—registry publication or command-line distribution—the tool emits fundamentally different artifacts with distinct runtime requirements and file structures.

Standard Library Bundles for npm Publishing

When you run vp pack without the executable flag, it invokes tsdown to create a production-ready library bundle. This output is designed for consumption via npm install and import statements in other projects.

The build process emits multiple formats and type declarations into a dist/ directory placed adjacent to your package.json:

vp pack src/index.ts

Typical output structure:

dist/
├─ index.esm.js      # ES Module build

├─ index.cjs.js      # CommonJS build  

├─ index.d.ts        # TypeScript declarations

└─ index.esm.js.map  # Source maps (if enabled)

These files represent the runtime-oriented distribution that library consumers execute directly. The configuration driving this output lives in vite.config.ts under the pack key, parsed by packages/cli/src/pack-bin.ts before delegation to the bundler.

Standalone Binary Generation

Adding the --exe flag transforms the build target from a distributable library into a single-executable application (SEA). This experimental feature compiles your entry point into a native binary that requires no Node.js installation on the target machine (requires Node.js ≥ 25.7.0).

vp pack src/cli.ts --exe

Resulting artifact:

dist/
└─ my-cli        # Native executable (platform-specific)

Unlike the multi-file library output, this produces a solitary binary file capable of direct execution. As documented in rfcs/pack-command.md, this mode bypasses the generation of .js, .d.ts, and .map files entirely, replacing them with the compiled executable.

Key Differences in Output Structure

Characteristic	Library Bundle (npm)	Standalone Binary (--exe)
Primary artifact	Multiple .js, .mjs, or .cjs files	Single native executable
Type definitions	.d.ts declaration files included	None generated
Source maps	.map files (optional)	Not applicable
Runtime dependency	Requires Node.js on target system	Self-contained (Node.js SEA)
Typical use case	SDKs, UI libraries, shared modules	CLI tools, DevOps utilities
Distribution method	Published to npm registry via vp pm pack	Direct download or system package managers

The Role of vp pm pack in npm Distribution

A critical distinction exists between building and packaging. While vp pack creates the compiled library in dist/, the vp pm pack command (implemented in crates/vite_install/src/commands/pack.rs) creates the final .tgz tarball that npm expects for registry uploads.

# Create the library artifacts

vp pack

# Create the publishable archive

vp pm pack --out ./releases/my-lib-1.0.0.tgz

This command bundles your source tree, the compiled dist/ folder, and metadata into a gzip-compressed archive. Unlike vp pack, it never invokes the SEA builder or produces binaries; it strictly prepares files for npm publish.

Configuration and Implementation Details

Library bundling relies on the pack configuration object in vite.config.ts, controlling entry points, formats (esm, cjs), and TypeScript declaration generation. The CLI implementation in packages/cli/src/pack-bin.ts processes these options and orchestrates the tsdown invocation.

Binary generation requires no additional configuration keys—only the --exe flag. However, because it produces a fundamentally different output format, it cannot be combined with standard library distribution in the same build step.

Practical Examples

Bundling a TypeScript Library

// vite.config.ts
export default {
  pack: {
    entry: 'src/index.ts',
    format: ['esm', 'cjs'],
    dts: true,
    minify: true
  },
}

vp pack

# Outputs distributable library to dist/

Creating a CLI Binary

vp pack src/cli.ts --exe

# Outputs dist/my-cli (executable)

Packaging for npm Registry

vp pack              # Build library

vp pm pack           # Create package.tgz for publishing

Summary

• vp pack (standard mode) emits a dist/ directory containing JavaScript modules (.js, .mjs, .cjs), TypeScript declarations (.d.ts), and source maps intended for npm publication and import by other projects.
• vp pack --exe generates a single native executable via Node.js SEA, eliminating the need for Node.js on end-user machines but producing no library files.
• vp pm pack creates a .tgz tarball from your package contents (including the dist/ folder), conforming to npm registry specifications for distribution.
• Library output is configured via the pack key in vite.config.ts and implemented in packages/cli/src/pack-bin.ts, while binary generation is handled by native compilation pipelines.

Frequently Asked Questions

What is the difference between vp pack and vp pm pack?

vp pack compiles your TypeScript into distributable JavaScript bundles (or standalone binaries with --exe), outputting to dist/. vp pm pack creates a .tgz archive of your entire package—including source files, dist/, and metadata—for uploading to the npm registry. As defined in rfcs/pm-command-group.md, the latter mimics npm pack behavior.

Can I generate both library files and a standalone binary in one command?

No. The --exe flag is mutually exclusive with standard library output. When building a binary, vp pack skips the generation of .js, .d.ts, and source map files entirely, producing only the native executable. You must run separate build commands to generate both artifacts.

What Node.js version is required for standalone binaries?

Standalone executable generation requires Node.js ≥ 25.7.0 to utilize the Single Executable Application (SEA) feature. The resulting binary embeds the Node.js runtime, allowing execution on systems without Node.js installed.

Where does vp pack place its output files?

By default, both library bundles and standalone binaries are written to the dist/ directory relative to your package.json. You can customize this location using the --out-dir CLI flag or the outDir option in the pack configuration. vp pm pack writes the resulting .tgz to the current working directory unless you specify --out or --pack-destination.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}