Prerequisites for Running Archify: Complete Setup Guide

To run Archify, you need Node.js 18 or later and npm/npx installed; optional media tools like CairoSVG, FFmpeg, or Chrome are only required for specific export formats.

Archify is a Node.js-only architecture diagramming tool maintained in the tt-a1i/archify repository. Understanding the prerequisites for running Archify ensures a smooth installation whether you are generating simple HTML diagrams or exporting high-fidelity PNG and WebM assets.

Core Runtime Requirements

Node.js Version 18 or Later

The hard minimum for running Archify is Node.js ≥ 18. According to the tt-a1i/archify source code, the engines field in archify/package.json explicitly declares "node": ">=18" to enforce this constraint. Additionally, the documentation in docs/authoring-cookbook.md states that the tool "requires Node.js 18 or later" for stable operation.

npm or npx Access

Archify is distributed as a skill that installs via npm. The quick-start instructions in README.md demonstrate installation using npx skills add tt-a1i/archify …, which requires a functional npm or npx environment in your terminal.

Optional Dependencies for Advanced Exports

While the core renderer and validators are bundled in the skill zip and work out-of-the-box, certain export formats require additional system binaries. As detailed in docs/research-visual-evolution-round-14.md, these optional tools are only necessary if you plan to generate specific media types.

CairoSVG for PNG Generation

To export static PNG share-cards, you must install CairoSVG. This library handles the rasterization of SVG graphics when running the PNG export command.

FFmpeg and FFprobe for WebM Video

Generating animated WebM videos requires FFmpeg and FFprobe installed on your system path. The export pipeline invokes these binaries to encode frames into video containers.

Chrome or Chromium for Headless Rendering

Some advanced rendering paths rely on a headless browser environment. Install Google Chrome or Chromium if you need to execute browser-based rendering steps outside of the standard Node.js runtime.

Installation and Verification

Once Node.js and npm are ready, install Archify using the skill manager and verify your environment with the built-in doctor command.

Install the Archify skill globally:

npx skills add tt-a1i/archify -g

Run the environment self-check to validate prerequisites:

node archify/bin/archify.mjs doctor

Generate a simple architecture diagram from a JSON Intermediate Representation (IR) file:

node archify/bin/archify.mjs render architecture path/to/diagram.json diagram.html

Export a PNG share-card (requires CairoSVG):

node archify/bin/archify.mjs export png diagram.html diagram.png

Export a WebM video (requires FFmpeg):

node archify/bin/archify.mjs export webm diagram.html diagram.webm

All commands assume execution from the repository root where the archify folder resides. The entry point archify/bin/archify.mjs serves as the CLI handler for doctor, render, and export operations.

Summary

• Node.js ≥ 18 is mandatory, as declared in archify/package.json and docs/authoring-cookbook.md.
• npm/npx is required to install the skill via npx skills add.
• Core functionality works immediately after installation without additional runtime packages.
• Optional media tools (CairoSVG, FFmpeg, Chrome) are only needed for PNG, WebM, or headless rendering exports.
• Use node archify/bin/archify.mjs doctor to verify your environment before generating diagrams.

Frequently Asked Questions

What version of Node.js is required for Archify?

Archify requires Node.js 18 or later. The engines field in archify/package.json specifies "node": ">=18", and the docs/authoring-cookbook.md explicitly documents this minimum version requirement.

Do I need to install FFmpeg to use Archify?

Only for WebM exports. FFmpeg is an optional dependency required solely when running archify/bin/archify.mjs export webm. Basic HTML diagram generation and PNG exports (with CairoSVG) do not require FFmpeg.

Can I run Archify without npm?

No. Archify is distributed as an npm-based skill, and the installation workflow documented in README.md relies on npx skills add. You must have npm or npx available to install and manage the skill.

Where are the core renderer and validators located?

The core renderer and validators are bundled inside the skill zip and located within the archify/ directory. Once installed, the CLI entry point at archify/bin/archify.mjs provides access to all commands without requiring separate package installations.

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