denji

name	denji
description	Manage SVG icons as framework components using Denji CLI. Use when the user needs to add, remove, list, export, import, or manage SVG icons in React, Preact, Solid, Qwik, Vue, or Svelte projects. Triggers include requests to "add an icon", "set up icons", "manage SVG icons", "remove an icon", "list icons", "export icons", "import icons", "dry-run icon add", or any task involving Iconify icons as framework components.
allowed-tools	Bash(npx denji:*)
metadata	{"author":"fellipeutaka","version":"1.0.0"}

Managing SVG Icons with Denji

Denji converts Iconify SVG icons into typed framework components. Icons are fetched, optimized (SVGO), and generated as native components for your framework.

Core Workflow

# 1. Initialize project
npx denji init --framework react --output ./src/icons.tsx

# 2. Add icons (prefix:name format from Iconify)
npx denji add lucide:check lucide:x lucide:arrow-right

# 3. Use in your code

import { Icons } from "./icons";

<Icons.Check className="size-4 text-green-500" />
<Icons.X className="size-4 text-red-500" />

Commands

denji init

Initialize a Denji project. Creates denji.json config and icons template.

npx denji init
npx denji init --framework react --output ./src/icons.tsx
npx denji init --framework svelte --output ./src/icons --output-type folder
npx denji init --framework react --no-typescript --output ./src/icons.jsx
npx denji init --a11y hidden --forward-ref

Flag	Description
--framework <name>	react, preact, solid, qwik, vue, svelte
--output <path>	Output path for icons file/folder
--output-type <type>	file (single file) or folder (one file per icon)
--typescript / --no-typescript	TypeScript or JavaScript (default: TS)
--a11y <strategy>	hidden, img, title, presentation, or false (no a11y attrs)
--forward-ref / --no-forward-ref	Use forwardRef (React/Preact only)
--track-source / --no-track-source	Track Iconify source via data-icon attr
-c, --cwd <path>	Working directory

Missing flags trigger interactive prompts.

denji add <icons...>

Add icons from Iconify. Icons use prefix:name format.

npx denji add lucide:check
npx denji add lucide:check mdi:home radix-icons:cross-2
npx denji add lucide:star --name FavoriteStar
npx denji add lucide:info --a11y img
# Preview without writing files
npx denji add lucide:check mdi:home --dry-run

Flag	Description
--name <name>	Custom component name (single icon only)
--a11y <strategy>	Override a11y strategy for this icon
--dry-run	Preview what would be generated without writing any files
-c, --cwd <path>	Working directory

Icon naming: lucide:arrow-right becomes ArrowRight (PascalCase). Override with --name.

Adding an existing icon updates it in place.

--dry-run skips file writes and hooks but still validates icon names, allowedLibraries, and config. Useful for CI checks and PR previews.

◇ denji add
│
○ [dry-run] Would add Check → ./src/icons.tsx
○ [dry-run] Would add Home → ./src/icons.tsx
│
◇ Dry run complete — 2 icon(s) previewed, no files written

denji remove <icons...>

Remove icons by component name. Aliases: rm, delete, del.

npx denji remove Check
npx denji rm Check Home ArrowRight

Flag	Description
-c, --cwd <path>	Working directory

denji list

List all icons in your project.

npx denji list
npx denji list --display json
npx denji list --display toon

Flag	Description
--display <mode>	Output mode: default (human-readable), json, or toon
-c, --cwd <path>	Working directory

Shows component names and Iconify source (if trackSource: true).

Default output:

Found 3 icon(s) in ./src/icons.tsx

Icons:
  • Check (lucide:check)
  • HomeOutline (mdi:home-outline)
  • ArrowRight (lucide:arrow-right)

JSON output (--display json):

{
  "count": 3,
  "output": "./src/icons.tsx",
  "icons": [
    { "name": "Check", "source": "lucide:check" },
    { "name": "HomeOutline", "source": "mdi:home-outline" },
    { "name": "ArrowRight", "source": "lucide:arrow-right" }
  ]
}

TOON output (--display toon) uses TOON format for machine-readable binary encoding.

denji export

Export a JSON manifest of all tracked icons.

npx denji export                    # print to stdout
npx denji export --output icons.json
npx denji export --output           # writes to denji-export.json

Flag	Description
--output [path]	Write to file (default: denji-export.json if no path given)
-c, --cwd <path>	Working directory

Output format:

{
  "version": 1,
  "framework": "react",
  "output": "./src/icons.tsx",
  "icons": [
    { "name": "Home", "source": "mdi:home" },
    { "name": "Check", "source": "lucide:check" }
  ]
}

source is included only when trackSource: true (the default).

denji import

Bulk-add icons from a manifest JSON file, a plain text file, or stdin.

npx denji import icons.json         # from denji export manifest
npx denji import icons.txt          # one prefix:name per line
echo "mdi:home\nlucide:check" | npx denji import   # from stdin
npx denji import icons.json --dry-run

Flag	Description
--dry-run	Preview without writing files
-c, --cwd <path>	Working directory

Icons without prefix:name format are skipped with a warning. JSON manifest entries without a source field are also skipped.

denji clear

Remove all icons. Aliases: clr, reset.

npx denji clear
npx denji clear --yes

Flag	Description
-y, --yes	Skip confirmation prompt
-c, --cwd <path>	Working directory

Config (denji.json)

The $schema field depends on how Denji is installed:

• Locally installed (npm i -D denji): "./node_modules/denji/configuration_schema.json"
• Not installed (using npx, bunx, pnpx, yarn dlx): "https://denji-docs.vercel.app/configuration_schema.json"

{
  "$schema": "./node_modules/denji/configuration_schema.json",
  "framework": "react",
  "output": "./src/icons.tsx",
  "typescript": true,
  "a11y": "hidden",
  "trackSource": true,
  "allowedLibraries": ["lucide"],
  "react": {
    "forwardRef": true
  },
  "hooks": {
    "postAdd": ["npx biome check --write ./src/icons.tsx"],
    "postRemove": ["npx biome check --write ./src/icons.tsx"]
  }
}

Key fields:

Field	Type	Description
framework	string	Required. react, preact, solid, qwik, vue, svelte
output	string or object	Required. Path string or { type: "file"|"folder", path: "..." }
typescript	boolean	Default: true
a11y	string or false	hidden, img, title, presentation, false
trackSource	boolean	Default: true. Adds data-icon attr
allowedLibraries	string[]	Restrict to specific Iconify prefixes. Empty/omitted = all allowed
hooks	object	Lifecycle hooks (see below)

Output Modes

File mode (default for React, Preact, Solid, Qwik, Vue): All icons in one file.

{ "output": "./src/icons.tsx" }

Folder mode (required for Svelte, optional for others): One file per icon + barrel export.

{ "output": { "type": "folder", "path": "./src/icons" } }

Hooks

Run shell commands at lifecycle points:

{
  "hooks": {
    "preAdd": ["echo 'Adding icons...'"],
    "postAdd": ["npx prettier --write ./src/icons.tsx"],
    "preRemove": [],
    "postRemove": [],
    "preClear": [],
    "postClear": [],
    "preList": [],
    "postList": []
  }
}

Common Patterns

Dynamic Icons

import { Icons, type IconName, type IconProps } from "./icons";

function DynamicIcon({ name, ...props }: { name: IconName } & IconProps) {
  const Icon = Icons[name];
  return <Icon {...props} />;
}

<DynamicIcon name="Check" className="size-4" />

Accessibility

// Decorative icon (hidden from screen readers)
<button>
  <Icons.Check aria-hidden="true" />
  Save
</button>

// Semantic icon (announced by screen readers)
<Icons.Check role="img" aria-label="Success" />

// Icon-only button
<button aria-label="Close">
  <Icons.X aria-hidden="true" />
</button>

Restricting Icon Sources

{
  "allowedLibraries": ["lucide"]
}

npx denji add lucide:check   # ✓ allowed
npx denji add mdi:home       # ✗ Error: Icon "mdi:home" is not allowed. Allowed libraries: lucide

Formatting with Hooks

{
  "hooks": {
    "postAdd": ["npx biome check --write ./src/icons.tsx"],
    "postRemove": ["npx biome check --write ./src/icons.tsx"]
  }
}

Using forwardRef (React/Preact)

{
  "framework": "react",
  "react": { "forwardRef": true }
}

const ref = useRef<SVGSVGElement>(null);
<Icons.Check ref={ref} className="size-4" />

Framework Quick Reference

Framework	Extensions	Default Output	Config Key	Notes
React	.tsx/.jsx	file	react	forwardRef option
Preact	.tsx/.jsx	file	preact	forwardRef option (via preact/compat)
Solid	.tsx/.jsx	file	solid	Refs work natively as props
Qwik	.tsx/.jsx	file	qwik	Uses component$() in folder mode
Vue	.ts/.js	file	vue	Uses h() render functions
Svelte	.svelte	folder (only)	svelte	Svelte 5 $props() runes

Deep-Dive References

Reference	Content
references/configuration.md	Full config schema, all framework options, output normalization
references/framework-patterns.md	Per-framework code examples, file vs folder imports, TypeScript types