How to Use the archify preview Command for Live Rendering During Authoring

The archify preview command launches a local development server that automatically refreshes your architecture diagram in the browser whenever you save changes to the source file.

The archify preview command eliminates manual regeneration cycles when authoring diagrams in the tt-a1i/archify repository. This built-in CLI tool starts a lightweight HTTP server, renders your .archify definition to HTML, and watches for file changes to provide immediate visual feedback.

Starting the Live Preview Server

Navigate to the directory containing your .archify file and run the preview command. You can invoke it via npx without installing the package globally, or use the global archify binary if you have installed it.

# Using npx (no installation required)

npx archify preview examples/web-app.archify.json

# Using global installation

archify preview examples/web-app.archify.json

By default, the server initializes on port 3000 and automatically opens your default browser to http://localhost:3000. The preview UI loads immediately, displaying the rendered diagram based on the current state of your source file.

Customizing the Preview Configuration

The archify preview command accepts several flags to adjust server behavior and appearance. These options let you resolve port conflicts, include additional assets in the watch cycle, or enforce a specific color scheme.

Specifying a Custom Port

Use the --port flag to bind the server to an alternative port when 3000 is unavailable.

npx archify preview examples/web-app.archify.json --port 8081

Watching Additional Files

By default, the watcher monitors the main .archify source file. Use --watch to specify glob patterns for supplementary files such as external stylesheets or shared configuration modules.

npx archify preview examples/web-app.archify.json --watch "styles/**/*.css"

Forcing a Preview Theme

The --theme flag accepts dark or light values to override the default toggle-able UI theme. Without this flag, the preview interface renders with a theme switcher that lets you alternate between modes manually.

npx archify preview examples/web-app.archify.json --theme light

How Live Reload Works Behind the Scenes

According to the tt-a1i/archify source code, the preview command generates a temporary HTML page using the template defined in scripts/start-template.html. This template embeds the diagram via an iframe using query parameters ?embed=1&theme=… to isolate the rendering context while maintaining communication with the parent UI for theme controls. The scripts/gallery-template.html file demonstrates similar embedding patterns used for gallery builds, providing a reference for how the preview system handles multiple diagram displays.

The build logic in scripts/build-gallery.mjs demonstrates how the server constructs these embeddable snippets, injecting the current diagram state into the iframe source. When you save changes to the watched .archify file or any matched glob pattern, the development server triggers a page refresh that preserves your current viewport state unless you perform a full browser reload.

The CLI definition in archify/package.json maps the preview subcommand to this server implementation, ensuring consistent behavior across local and global installations.

Stopping the Preview Server

To terminate the live preview session, focus the terminal running the server and press Ctrl+C. This sends the interrupt signal to shut down the HTTP server and release the bound port.

Summary

• archify preview starts a development server on port 3000 with automatic browser opening and live reload capabilities.
• The command watches .archify source files and optionally additional glob patterns specified via --watch.
• Configuration flags include --port for custom ports, --theme for forced color schemes, and --open to control automatic browser launching.
• The implementation uses scripts/start-template.html to generate an iframe-based preview UI that refreshes automatically on file changes.
• Terminate the server at any time using Ctrl+C in the terminal.

Frequently Asked Questions

What is the default port for archify preview?

The preview server binds to port 3000 by default, accessible at http://localhost:3000. You can override this using the --port flag followed by your desired port number.

Can I watch multiple file types with archify preview?

Yes. While the server automatically watches the main .archify file, you can monitor additional assets using the --watch flag with a glob pattern. For example, --watch "styles/**/*.css" ensures CSS changes also trigger reloads.

How does archify preview handle theme switching?

The preview UI includes a theme toggle button unless you specify --theme dark or --theme light. According to scripts/start-template.html, the diagram renders inside an iframe that receives theme parameters via query string, allowing the parent page to communicate theme changes without reloading the entire diagram context.

Does archify preview require a global installation?

No. You can run npx archify preview <file> to execute the command without installing the package globally. However, if you have installed Archify globally via npm install -g archify, you can omit the npx prefix and run archify preview directly.

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