How to Configure ViewBox Sizing for Responsive Artifacts in Archify

Set the viewBox attribute explicitly on your SVG source, then use Archify's artifactViewBox configuration in archify.config.js to control fallback behavior and responsive scaling.

Archify is a static site generator that renders visual artifacts—typically SVG-based diagrams—inside responsive containers. Proper ViewBox sizing ensures these artifacts scale gracefully across devices without distortion or overflow. This guide explains how to configure ViewBox behavior using Archify's built-in options, based on the source implementation in tt-a1i/archify.

---

Understanding Archify's ViewBox Handling

Archify processes artifacts in two stages. First, it parses each SVG and extracts (or infers) a viewBox attribute that defines the coordinate system. Second, it wraps the SVG in a responsive container with CSS rules that scale the graphic to fit its parent.

The relevant configuration lives in archify.config.js, the central settings file for any Archify project. By default, Archify operates in "auto" mode, reading the viewBox directly from each SVG file. If that attribute is missing, Archify falls back to inferring dimensions from width and height attributes—a behavior that can produce inconsistent results on different screen sizes.

---

Method 1: Explicit ViewBox in SVG Source

The most reliable approach is to declare a proper viewBox attribute in every SVG artifact. This gives Archify a clear coordinate reference and ensures predictable scaling.

<svg
    xmlns="http://www.w3.org/2000/svg"
    width="800"
    height="600"
    viewBox="0 0 800 600">
  <!-- diagram elements -->
</svg>

• The viewBox="0 0 800 600" establishes a 800×600 coordinate system
• Archify detects this automatically and applies responsive CSS: width: 100%, height: auto
• Aspect ratio is preserved because the browser uses the viewBox dimensions for scaling calculations

Place your SVG files in the source directory configured in your build script (commonly ./src/artifacts), and Archify will process them during the build phase.

---

Method 2: Global Configuration via artifactViewBox

For projects with many artifacts or inconsistent source files, Archify provides a configuration option to enforce uniform ViewBox behavior. In archify.config.js, set the artifactViewBox object:

// archify.config.js
module.exports = {
  // ...other options

  artifactViewBox: {
    mode: "fixed",
    defaultBox: "0 0 1000 800",
  },

  cssVariables: {
    "--archify-artifact-max-width": "1200px",
  },
};

Property	Purpose
mode: "auto"	Use each SVG's native viewBox attribute (default)
mode: "fixed"	Apply defaultBox to all artifacts lacking a viewBox
defaultBox	Fallback coordinate string when mode is "fixed"
cssVariables	Global CSS custom properties controlling visual bounds

When to use "fixed" mode: If your SVG assets come from external tools that omit viewBox attributes, "fixed" prevents scaling glitches by standardizing the coordinate system across all artifacts.

---

Method 3: Per-Artifact CSS Overrides

Archify injects each artifact into a wrapper <div class="archify-artifact">. You can target individual artifacts with custom CSS to override global scaling behavior.

<div class="archify-artifact wide-diagram">
  <!-- Archify injects SVG here -->
</div>

/* styles/custom.css */
.wide-diagram {
  --archify-artifact-max-width: 900px;
}

.wide-diagram svg {
  max-height: 600px;
}

• The --archify-artifact-max-width variable is referenced by Archify's default stylesheet in scripts/start-template.html
• Additional rules like max-height prevent excessively tall diagrams on landscape-oriented viewports
• These overrides layer on top of the viewBox-derived scaling, preserving aspect ratio

This approach is ideal for edge cases—such as hero diagrams or mobile-optimized graphics—that need sizing exceptions without altering the global configuration.

---

Build Integration Example

Wire everything together in your build script:

// build.js
const archify = require("archify");
const config = require("./archify.config.js");

archify.build({
  src: "./src/artifacts",
  out: "./dist",
  config,
});

Archify's build process (implemented in the repository's core scripts) performs these steps:

1. Reads each SVG from src
2. Applies artifactViewBox rules to normalize or preserve viewBox attributes
3. Generates responsive wrappers using the template in scripts/start-template.html
4. Injects CSS custom properties from cssVariables
5. Writes final HTML to out

---

Method Comparison

Approach	Best For	Trade-off
Explicit SVG viewBox	Full control over each artifact	Requires editing source files
artifactViewBox config	Consistent behavior across many files	May mask intentional design variations in source SVGs
CSS overrides	One-off exceptions or responsive breakpoints	Adds maintenance overhead for large projects

For production sites, combine all three: explicit viewBox attributes for precision, "fixed" mode as a safety net, and CSS overrides for specific layout contexts.

---

Summary

• Add viewBox="0 0 W H" to every SVG artifact for reliable, native browser scaling
• Configure artifactViewBox in archify.config.js to set fallback dimensions when viewBox is absent
• Use CSS custom properties and wrapper classes to constrain maximum sizes without distorting aspect ratios
• Archify's responsive behavior is controlled through archify.config.js, scripts/start-template.html, and per-artifact CSS

---

Frequently Asked Questions

What happens if my SVG has no viewBox and I don't configure artifactViewBox?

Archify falls back to inferring dimensions from width and height attributes, then applies a default coordinate system. This often causes unexpected cropping or scaling on mobile devices. Set mode: "fixed" with a defaultBox to ensure consistent rendering.

Can I use different viewBox settings for different artifact categories?

Yes. Organize artifacts into subdirectories, create separate Archify build configurations for each, and run multiple builds with distinct artifactViewBox settings. Alternatively, use CSS overrides per class for simpler cases.

Where does Archify apply the responsive CSS?

The wrapper styles are defined in scripts/start-template.html, which serves as the HTML template for artifact injection. The .archify-artifact class receives width: 100% and height: auto, while CSS variables like --archify-artifact-max-width cap the visual size.

Does Archify support viewBox animations or JavaScript manipulation?

Archify processes artifacts at build time, so runtime JavaScript modifications to viewBox attributes require client-side code. The generated SVG elements are standard DOM nodes—you can target them with document.querySelector and update viewBox dynamically after page load.

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