# vp pack Build Output Differences: npm Publishing vs Standalone Binaries

> Understand vp pack output differences for npm publishing vs standalone binaries. Explore how vite-plus creates JS libraries for npm and native executables with the experimental --exe flag.

- Repository: [VoidZero/vite-plus](https://github.com/voidzero-dev/vite-plus)
- Tags: deep-dive
- Published: 2026-03-16

---

**`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`](https://github.com/voidzero-dev/vite-plus/blob/main/package.json):

```bash
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`](https://github.com/voidzero-dev/vite-plus/blob/main/vite.config.ts) under the `pack` key, parsed by [`packages/cli/src/pack-bin.ts`](https://github.com/voidzero-dev/vite-plus/blob/main/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).

```bash
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`](https://github.com/voidzero-dev/vite-plus/blob/main/rfcs/pack-command.md), this mode bypasses the generation of `.js`, [`.d.ts`](https://github.com/voidzero-dev/vite-plus/blob/main/.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`](https://github.com/voidzero-dev/vite-plus/blob/main/.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`](https://github.com/voidzero-dev/vite-plus/blob/main/crates/vite_install/src/commands/pack.rs)) creates the final **`.tgz` tarball** that npm expects for registry uploads.

```bash

# 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`](https://github.com/voidzero-dev/vite-plus/blob/main/vite.config.ts), controlling entry points, formats (`esm`, `cjs`), and TypeScript declaration generation. The CLI implementation in [`packages/cli/src/pack-bin.ts`](https://github.com/voidzero-dev/vite-plus/blob/main/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

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

```

```bash
vp pack

# Outputs distributable library to dist/

```

### Creating a CLI Binary

```bash
vp pack src/cli.ts --exe

# Outputs dist/my-cli (executable)

```

### Packaging for npm Registry

```bash
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`](https://github.com/voidzero-dev/vite-plus/blob/main/.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`](https://github.com/voidzero-dev/vite-plus/blob/main/vite.config.ts) and implemented in [`packages/cli/src/pack-bin.ts`](https://github.com/voidzero-dev/vite-plus/blob/main/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`](https://github.com/voidzero-dev/vite-plus/blob/main/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`](https://github.com/voidzero-dev/vite-plus/blob/main/.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`](https://github.com/voidzero-dev/vite-plus/blob/main/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`.