Config & Lockfile

The CLI writes two files at the project root. Commit both.

iconforge.json

The user-editable config file. Tracks your preferences and which packs you’ve installed.

{
  "$schema": "https://iconforge.ai/schemas/config-v1.json",
  "outputDir": "src/components/icons",
  "framework": "vue",
  "packs": {
    "acme/brand/core-icons": "latest",
    "acme/brand/navigation-icons": "hash:8f3a9c2d14be"
  },
  "packDirs": {
    "acme/brand/core-icons": "core",
    "acme/brand/navigation-icons": "nav"
  }
}

Field	Meaning
outputDir	Base directory for all pack folders
framework	react, vue, or react-native — shared across the project
packs	Version intent for each pack: latest or hash:<12-char-hash>
packDirs	Optional per-pack folder name overrides

What gets saved automatically

On the first successful install, the CLI persists the framework, output directory, pack entry, and any folder override you used. On subsequent installs, these are reused — you just run the install command without extra flags.

The API URL (--api-url / ICONFORGE_API_URL) is never persisted. It only affects that run.

iconforge-lock.json

The machine-written install record. Don’t hand-edit this.

{
  "lockVersion": 1,
  "packs": {
    "acme/brand/core-icons": {
      "versionHash": "8f3a9c2d14be",
      "publishedAt": "2026-03-14T10:00:00Z",
      "slotCount": 42,
      "framework": "vue",
      "outputDir": "src/components/icons/core",
      "manifestSchemaVersion": "1",
      "files": [
        {
          "path": "src/components/icons/core/ArrowLeft.vue",
          "slotName": "arrow-left",
          "componentName": "ArrowLeft",
          "svgHash": "sha256:abc123..."
        }
      ],
      "barrelFile": "src/components/icons/core/index.ts",
      "installedAt": "2026-03-16T20:00:00Z"
    }
  }
}

The lockfile records which release was installed, which files the CLI owns, and when it happened. This is how the CLI knows which files to replace cleanly on the next install.

Project root detection

The CLI uses the nearest package.json to find the project root. That’s where it reads and writes iconforge.json, iconforge-lock.json, and resolves relative output paths.

Nested directories

If you run the CLI inside a subdirectory of an existing app, it’ll reuse the parent app’s config unless that subdirectory has its own package.json.

Multiple packs

You can install multiple packs into the same project. Each gets its own entry in config, its own lockfile record, and its own folder under the output directory:

src/components/icons/
├── core/
│   ├── Check.vue
│   └── index.ts
└── nav/
    ├── ChevronLeft.vue
    └── index.ts

All packs in a project share the same framework.

Editing guidance

Safe to edit:

• iconforge.json — framework, output dir, pack versions, folder overrides
• Changing a pack from latest to hash:... (or vice versa)

Don’t hand-edit:

• iconforge-lock.json — if it looks wrong, rerun the install or delete it and reinstall