Configuration

Configuration is stored in denji.json at your project root.

Example Config

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

Options

output

Type: string | { type: "file" | "folder", path: string }
Required: Yes

Output path for generated icons. Accepts a string shorthand (defaults to file mode) or an object for explicit control.

File mode (default) — all icons in a single file:

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

Folder mode — one file per icon component + barrel export:

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

framework

Type: "react" | "preact" | "solid" | "qwik" | "vue" | "svelte"
Required: Yes

Target framework for generated components.

{
  "framework": "react"
}

typescript

Type: boolean
Default: true

Generate TypeScript or JavaScript output.

{
  "typescript": true
}

a11y

Type: "hidden" | "img" | "title" | "presentation" | false
Default: undefined

SVG accessibility strategy:

hidden

Adds aria-hidden="true" - for decorative icons that should be hidden from screen readers.

<svg aria-hidden="true">...</svg>

img

Adds role="img" with aria-label - for icons with semantic meaning.

<svg role="img" aria-label="Check">...</svg>

title

Adds <title> element inside SVG - provides accessible name.

<svg>
  <title>Check</title>
  ...
</svg>

presentation

Adds role="presentation" - marks icon as presentational.

<svg role="presentation">...</svg>

false

No accessibility attributes added.

denji add lucide:check --a11y img

trackSource

Type: boolean
Default: true

Add data-icon attribute with the original Iconify source name. Useful for debugging, identifying icon collections, and enabling future update command.

{
  "trackSource": true
}

When enabled, icons include the source attribute:

<svg data-icon="lucide:check">...</svg>

react

Type: object
Default: {}

React-specific options:

{
  "react": {
    "forwardRef": true
  }
}

forwardRef

Wrap icon components with forwardRef for ref forwarding support.

allowedLibraries

Type: string[] Default: undefined

Restrict icon additions to specific Iconify prefixes. When set, any denji add call with a prefix not in the list will fail immediately.

{
  "allowedLibraries": ["lucide"]
}

# Allowed
denji add lucide:check

# Rejected — error: Icon "mdi:home" is not allowed. Allowed libraries: lucide
denji add mdi:home

Omit the field (or set it to an empty array) to allow all libraries.

hooks

Type: object Default: {}

Lifecycle hooks to run shell commands at specific points:

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

Available hooks:

• preAdd - Before adding icons
• postAdd - After adding icons
• preRemove - Before removing icons
• postRemove - After removing icons
• preClear - Before clearing all icons
• postClear - After clearing all icons
• preList - Before listing icons
• postList - After listing icons

Common use cases:

• Format code after adding icons
• Run type checking
• Update icon registry
• Trigger builds

Schema Validation

The config includes JSON schema for editor validation and auto-completion.

If Denji is installed locally:

{
  "$schema": "./node_modules/denji/configuration_schema.json"
}

If using Denji without a local install (e.g., npx, bunx, pnpx, yarn dlx):

{
  "$schema": "https://denji-docs.vercel.app/configuration_schema.json"
}

This enables IntelliSense in VS Code and other editors.