{"id":15069,"library":"zip-build","title":"Build Directory Archiver","description":"zip-build is a specialized Node.js command-line utility designed for automating the archival of project build artifacts. It streamlines the process of zipping or tarring a specified output directory, making it particularly useful for deployment pipelines or versioned backups. The package automatically generates archive filenames based on the project's `name` and `version` fields extracted from `package.json`, and can optionally include a timestamp for uniqueness. Currently, at version 1.8.0, it demonstrates active maintenance through its GitHub repository, though a formal release cadence is not explicitly defined. Its key differentiators include flexible output formatting (supporting both `.zip` and `.tar`), customizable filename templating, and an optional interactive mode for guided execution. It primarily serves as a `devDependency` to be integrated into `npm scripts` for an automated build workflow, rather than offering a direct programmatic API for `import` into JavaScript or TypeScript modules.","status":"active","version":"1.8.0","language":"javascript","source_language":"en","source_url":"https://github.com/tribal2/zip-build","tags":["javascript","zip","build","npm","zip-build","zip-dist","zip-folder"],"install":[{"cmd":"npm install zip-build","lang":"bash","label":"npm"},{"cmd":"yarn add zip-build","lang":"bash","label":"yarn"},{"cmd":"pnpm add zip-build","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"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.","wrong":"import { zipBuild } from 'zip-build';","symbol":"zipBuild","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."},{"note":"There is no default export. The package's primary interface is the `zip-build` command available in your terminal after installation.","wrong":"import zipBuildCommand from 'zip-build';","symbol":"Default Export","correct":"This package is a CLI tool and does not provide a default export for programmatic use."},{"note":"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.","wrong":"const zipBuild = require('zip-build');","symbol":"CommonJS Require","correct":"This package is a CLI tool and does not expose a CommonJS module for requiring its core functionality."}],"quickstart":{"code":"// package.json snippet to demonstrate integration into a build workflow\n// Add this 'scripts' block to your project's package.json:\n/*\n  {\n    \"name\": \"my-project-name\",\n    \"version\": \"1.2.3\",\n    \"scripts\": {\n      \"clean\": \"rm -rf dist build\",\n      \"prebuild\": \"npm run clean\",\n      \"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\",\n      \"postbuild\": \"echo 'Build and archiving complete! Check the dist directory.'\",\n      \"test-zip\": \"npm run build && ls dist\"\n    },\n    \"devDependencies\": {\n      \"zip-build\": \"^1.8.0\"\n    }\n  }\n*/\n\n// To run this quickstart example:\n// 1. Ensure 'zip-build' is installed as a devDependency in your project:\n//    npm install --save-dev zip-build\n// 2. Add the provided 'scripts' block to your project's package.json file.\n// 3. Open your terminal in the project root and run:\n//    npm run build\n// This will create a 'build' directory, place a dummy file inside, then archive\n// that directory into a 'dist' folder with a name like 'app_1.2.3_release_1678886400000.zip'.\n// The --override flag ensures it can run multiple times without error.","lang":"javascript","description":"Demonstrates how to integrate `zip-build` into an npm script workflow, showing installation, directory creation, and archiving with custom naming."},"warnings":[{"fix":"To allow overwriting, always include the `--override` (or `-o`) flag when running `zip-build`, e.g., `zip-build build dist --override`.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"To use the `--name` option, combine it with `--interactive`: `zip-build --interactive --name`.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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`).","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.","error":"Error: Command failed with exit code 1: zip-build"},{"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.","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`.","error":"zip-build: command not found"},{"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.","cause":"An archive with the generated filename already exists in the target `zipDir`, and the `--override` flag was not used to permit overwriting.","error":"Error: EEXIST: file already exists, 'my-project_1.0.0_TIMESTAMP.zip'"}],"ecosystem":"npm"}