Build Directory Archiver

Common errors

• Error: Command failed with exit code 1: zip-build

  cause The `zip-build` command was invoked, but either the source `buildDir` did not exist, or the destination `zipDir` was invalid, or an existing archive prevented creation without the `--override` flag.
  fix Ensure the `buildDir` exists before running the command. Check that `zipDir` is a valid path. If an archive already exists at the target, add the `--override` flag (e.g., `zip-build my-build my-dist --override`).

• zip-build: command not found

  cause The `zip-build` package is not installed globally, or it's a local `devDependency` and the command is not being run from an npm script or via `npx`.
  fix Install it as a devDependency (`npm install --save-dev zip-build`) and then run it via an npm script (e.g., `"build": "zip-build"` in `package.json` then `npm run build`), or use `npx zip-build` to execute it directly.

• Error: EEXIST: file already exists, 'my-project_1.0.0_TIMESTAMP.zip'

  cause An archive with the generated filename already exists in the target `zipDir`, and the `--override` flag was not used to permit overwriting.
  fix To allow overwriting existing archives, add the `--override` flag to your `zip-build` command (e.g., `zip-build --override`). Alternatively, modify the `--template` option to ensure unique filenames.

Warnings

• gotcha By default, `zip-build` will not override an existing archive file. If an output file with the generated name already exists in the `zipDir`, the command will fail.
  Fix: To allow overwriting, always include the `--override` (or `-o`) flag when running `zip-build`, e.g., `zip-build build dist --override`.
• gotcha The default `buildDir` is `build` and `zipDir` is `dist`. If your project uses different directory names, `zip-build` will not find them or place the archive correctly.
  Fix: Always explicitly specify your source and destination directories, e.g., `zip-build output archives`. Alternatively, ensure your build output goes into a `build` directory and you want the archive in a `dist` directory.
• gotcha The `--name` option, which allows asking for a custom output archive filename, requires the `--interactive` flag to also be enabled. Using `--name` without `--interactive` will have no effect.
  Fix: To use the `--name` option, combine it with `--interactive`: `zip-build --interactive --name`.
• gotcha This package is designed as a Command-Line Interface (CLI) tool. It does not expose a stable or documented programmatic API for direct `import` or `require` into JavaScript/TypeScript modules. Attempts to use it this way are unsupported.
  Fix: Integrate `zip-build` into your project via npm `scripts` in `package.json`, or by invoking the CLI command directly using `child_process` functions (like `spawn` or `exec`) if programmatic execution within Node.js is necessary.

Install

• npm install zip-build npm
• yarn add zip-build yarn
• pnpm add zip-build pnpm

Imports

• zipBuild
  wrong:

  import { zipBuild } from 'zip-build';

  correct:

  This package is a CLI tool, primarily used via npm scripts or direct terminal execution. It does not expose a documented programmatic API for direct JavaScript/TypeScript imports.

  zip-build is intended for command-line usage. Attempts to import its functionality directly as a module will not work as expected for its core archiving features. To use its functionality programmatically, consider `child_process.spawn` or `exec` to invoke the CLI.
• Default Export
  wrong:

  import zipBuildCommand from 'zip-build';

  correct:

  This package is a CLI tool and does not provide a default export for programmatic use.

  There is no default export. The package's primary interface is the `zip-build` command available in your terminal after installation.
• CommonJS Require
  wrong:

  const zipBuild = require('zip-build');

  correct:

  This package is a CLI tool and does not expose a CommonJS module for requiring its core functionality.

  Attempting to `require('zip-build')` will likely provide access to its internal module structure, but not a stable or documented API for executing its archiving logic. Direct CLI invocation is the recommended approach.

Quickstart

Demonstrates how to integrate `zip-build` into an npm script workflow, showing installation, directory creation, and archiving with custom naming.

// package.json snippet to demonstrate integration into a build workflow
// Add this 'scripts' block to your project's package.json:
/*
  {
    "name": "my-project-name",
    "version": "1.2.3",
    "scripts": {
      "clean": "rm -rf dist build",
      "prebuild": "npm run clean",
      "build": "mkdir build && echo 'Hello, this is a build artifact!' > build/main.txt && zip-build build dist --format zip --template 'app_%VERSION%_release_%TIMESTAMP%.%EXT%' --override",
      "postbuild": "echo 'Build and archiving complete! Check the dist directory.'",
      "test-zip": "npm run build && ls dist"
    },
    "devDependencies": {
      "zip-build": "^1.8.0"
    }
  }
*/

// To run this quickstart example:
// 1. Ensure 'zip-build' is installed as a devDependency in your project:
//    npm install --save-dev zip-build
// 2. Add the provided 'scripts' block to your project's package.json file.
// 3. Open your terminal in the project root and run:
//    npm run build
// This will create a 'build' directory, place a dummy file inside, then archive
// that directory into a 'dist' folder with a name like 'app_1.2.3_release_1678886400000.zip'.
// The --override flag ensures it can run multiple times without error.