@zokugun/artifact

artifact is a CLI for boilerplating your project by composing reusable config packages, merging overlapping files, and keeping every artifact in sync with a single update command.

Why artifact

• Compose curated configuration packages ("artifacts") published on npm and mix several of them into a single repo.
• Merge overlapping files intelligently using the built-in routes/steps pipeline.
• Keep artifacts synchronized by running artifact update, optionally in CI with --verbose for traceability.
• Support variant-aware installs and branch overlays so packages can expose multiple flavors while staying DRY.

Mergeable Files

• *.json (JSON or JSONC)
• *.yml
• *.yaml
• *ignore
• *rc (YAML, JSON or JSONC)
• *.config.ts

Installation

Choose the install mode that fits your workflow:

• Global CLI (recommended when you apply artifacts across many repos):

  npm install -g @zokugun/artifact

• Project-local CLI (handy for repo-specific automation):

  npm install -D @zokugun/artifact
  npx artifact --help

Quick Start

1. Install the CLI (globally or locally as shown in Installation).

2. Add the artifacts you want to compose:

   artifact add @daiyam/lang-js @daiyam/lang-ts @daiyam/npm @daiyam/npm-ts

   The command above installs the following packages:

   • @daiyam/artifact-lang-js
   • @daiyam/artifact-lang-ts
   • @daiyam/artifact-npm
   • @daiyam/artifact-npm-ts

3. Inspect the git diff created by the install. Keep overrides you like, discard unwanted changes, then rerun artifact update whenever upstream packages change.

Artifacts published to npm must be prefixed with artifact-.

Command Reference

artifact add

Registers and applies one or more artifacts in the current project.

• Syntax: artifact add <artifact...> [options]
• Useful flags: -v, --verbose to show detailed install output.
• Artifacts are stored in a .artifactrc* so subsequent updates know which packages to pull.

<artifact> can be name or name:variant.

artifact list / artifact l

Shows the artifacts currently tracked in .artifactrc*, including versions and, when available, requested variants.

• Syntax: artifact list
• Alias: artifact l
• Output: prints each artifact as name@version:variant.

artifact update / artifact up

Applies or refreshes the files provided by each installed artifact. Re-run it whenever upstream packages change.

• Syntax: artifact update [options]
• Alias: artifact up
• Advanced: pass -v, --verbose for an execution trace of routes, variants, and branches.
• Artifact authors can control how updates behave via .artifactrc files shipped inside their artifacts.

Best practices

Inspect the git diff after running to keep intentional overrides and drop unwanted changes.

Core Concepts

The next sections dive deeper into the primitives that make artifact powerful: templating, variants, and branch overlays.

Artifact Layout

The configuration/boilerplate files must be put inside the folder configs.

For example, the package @daiyam/artifact-npm-cli-ts:

npm-cli-ts/
  ├── configs/
  │  ├── bin/
  │  │  └── #[[package.json.name]]
  │  ├── bin/
  │  │  ├── command/
  │  │  │  └── hello.ts
  │  │  └── cli.ts
  │  ├── npmignore                  // => .npmignore
  │  ├── package.json
  ├── LICENSE
  ├── package.json
  └── README.md

Looking to build your own artifact? See Authoring artifacts for a step-by-step authoring guide.

Templating

During installs and updates, artifact runs every text file (and file name) through a template engine. Anywhere you place #[[path/to/file.ext.property]], the engine:

• loads that JSON/YAML file from the target project,
• reads the property,
• and substitutes the value—perfect for wiring the target's package.json.name, license, or runtime settings into generated files.

You can also emit timestamps with helpers like #[[date.utc]].

Read docs/templating.md for full syntax.

Variants

Variants let an artifact expose multiple named flavors of its configuration (for example 14, 20, stable, next). Consumers can request a variant in their install config, while package authors declare defaults and remap keys via .artifactrc.

See docs/variants.md for a full walkthrough, including examples of how to structure the variants folder.

Branches

Branches are lightweight conditional overlays that live under branches/[artifactName] (or [artifactName:variant]). They activate only when the matching artifact (and optional variant) is present, letting you ship targeted tweaks like per-language .nvmrc files without duplicating whole packages.

Learn more in docs/branches.md, including matching rules and best practices for layering branches after variants.

More Documentation

• Authoring artifacts
• Templating guide
• Variants guide
• Branches guide

Donations

Support this project by becoming a financial contributor.

License

Copyright © 2021-present Baptiste Augrain

Licensed under the MIT license.