Troubleshooting

Common issues and how to resolve them.

Installation Issues

Command not found

Problem: denji: command not found

Solution: Ensure Denji is installed and in your PATH:

npm install -D denji

npm run denji --version

Or use via package.json scripts:

{
  "scripts": {
    "icons:add": "denji add",
    "icons:list": "denji list"
  }
}

Configuration Issues

Config not found

Problem: Config file not found

Solution: Initialize config first:

denji init

Or create denji.json manually:

{
  "$schema": "./node_modules/denji/configuration_schema.json",
  "output": "./src/icons.tsx",
  "framework": "react",
  "typescript": true
}

Invalid config

Problem: Invalid configuration

Solution: Validate config against schema. Check:

• All required fields present (output, framework)
• Correct types for each field
• Valid enum values (e.g., a11y must be one of allowed values)

Icon Issues

Icon not found

Problem: Icon lucide:invalid-name not found

Solution:

1. Check icon exists on Iconify
2. Verify correct prefix and name format: prefix:name
3. Check for typos in icon name

Duplicate icons

Problem: Adding same icon multiple times

Solution: Denji automatically deduplicates. Re-adding an icon updates it.

Icons not updating

Problem: Changes not reflected in app

Solution:

1. Check output file was updated
2. Restart dev server
3. Clear build cache
4. Verify import path is correct

TypeScript Issues

Type errors

Problem: TypeScript errors when importing icons

Solution:

1. Ensure typescript: true in config
2. Check output file has .tsx extension
3. Verify TypeScript can resolve the file:

import { Icons } from "./icons"; // Should have auto-completion

Missing types

Problem: No auto-completion for icon names

Solution: The icons file exports typed components. Ensure:

• Using .tsx extension
• File is in TypeScript project
• Editor has loaded the file

Accessibility Issues

Wrong aria attributes

Problem: Icons have incorrect accessibility attributes

Solution: Set a11y strategy:

In config:

{
  "a11y": "hidden"
}

Per icon:

denji add lucide:check --a11y img

Per usage:

<Icons.Check aria-hidden="true" />

Hook Issues

Hooks not running

Problem: Lifecycle hooks don't execute

Solution:

1. Check hook commands are valid shell commands
2. Ensure hooks array syntax is correct:

{
  "hooks": {
    "postAdd": ["echo 'Done'"]
  }
}

3. Check command permissions
4. Verify output file path in hook matches config

Hook errors

Problem: Hook command fails

Solution:

1. Test command manually in terminal
2. Use absolute paths in hooks
3. Check command is installed
4. Add error handling to hook commands

Integration Issues

Bundler errors

Problem: Build fails with icon imports

Solution:

1. Ensure bundler can handle JSX/TSX
2. Check output file is included in build
3. Verify import path is correct

Framework compatibility

Problem: Icons don't work in framework

Solution: Denji supports React, Preact, Solid, Qwik, Vue, and Svelte. Ensure:

1. Your denji.json has the correct framework value
2. The output file extension matches the framework
3. Your project has the framework dependencies installed

Getting Help

Still stuck?

1. Check GitHub Issues
2. Search existing issues for similar problems
3. Create new issue with:
   • Denji version (denji --version)
   • Node/Bun version
   • Config file contents
   • Error messages
   • Steps to reproduce