Configuration

@saas-js/iconify uses an icons.json configuration file to store project settings. This file is created automatically when you run icons init.

Configuration File

The configuration file is located at the root of your project:

your-project/
├── icons.json
├── package.json
└── src/

Schema

The configuration file uses a JSON schema for validation and IDE support:

{
  "$schema": "https://saas-js.dev/icons/schema.json",
  "outputDir": "/src/components/icons",
  "defaultIconSet": "lucide",
  "iconSize": "1em",
  "aliases": {}
}

Configuration Options

`outputDir`

Type: string
Default: "/src/components/icons"

Directory where icon components will be generated, relative to your project root.

{
  "outputDir": "/src/components/icons"
}

Examples:

{
  "outputDir": "./components/icons"    // Relative path
}

{
  "outputDir": "/app/components/icons" // Absolute path from project root
}

{
  "outputDir": "./src/assets/icons"    // Alternative location
}

`defaultIconSet`

Type: string
Default: "lucide"

Default icon set to use when not specified in commands.

{
  "defaultIconSet": "lucide"
}

Popular options:

"lucide" - Modern, clean icons
"heroicons" - Tailwind CSS icons
"tabler" - Free SVG icons
"feather" - Simple, beautiful icons
"phosphor" - Flexible icon family
"mdi" - Material Design Icons
"fa-solid" - Font Awesome Solid
"fa-regular" - Font Awesome Regular
"fa-brands" - Font Awesome Brands

`iconSize`

Type: string | number
Default: "1em"

Default size for generated icons. Can be overridden at runtime.

{
  "iconSize": "1em"
}

Examples:

{
  "iconSize": "16px"    // Pixels
}

{
  "iconSize": "1.5rem"  // Rem units
}

{
  "iconSize": 24        // Number (pixels)
}

{
  "iconSize": "2em"     // Em units
}

`aliases`

Type: object
Default: {}

Icon name aliases for better naming conventions.

{
  "aliases": {
    "house": "home",
    "cog": "settings",
    "user-circle": "profile"
  }
}

How it works:

When you run icons add house, it will:

Fetch the house icon from the API
Generate a component named home-icon.tsx (using the alias)
Export HomeIcon component

Complete Example

{
  "$schema": "https://saas-js.dev/icons/schema.json",
  "outputDir": "./src/components/icons",
  "defaultIconSet": "lucide",
  "iconSize": "20px",
  "aliases": {
    "house": "home",
    "cog": "settings",
    "user-circle": "profile",
    "envelope": "mail",
    "magnifying-glass": "search"
  }
}

Environment-Specific Configuration

You can create different configurations for different environments:

Development

{
  "$schema": "https://saas-js.dev/icons/schema.json",
  "outputDir": "./src/components/icons",
  "defaultIconSet": "lucide",
  "iconSize": "1em"
}

Production

{
  "$schema": "https://saas-js.dev/icons/schema.json",
  "outputDir": "./dist/icons",
  "defaultIconSet": "lucide",
  "iconSize": "16px"
}

Use different config files:

# Development
icons add --config icons.dev.json home user

# Production
icons add --config icons.prod.json home user

Framework-Specific Examples

Next.js

{
  "$schema": "https://saas-js.dev/icons/schema.json",
  "outputDir": "./components/icons",
  "defaultIconSet": "lucide",
  "iconSize": "1em",
  "aliases": {
    "house": "home",
    "cog": "settings"
  }
}

Vite + React

{
  "$schema": "https://saas-js.dev/icons/schema.json",
  "outputDir": "./src/components/icons",
  "defaultIconSet": "heroicons",
  "iconSize": "24px"
}

Create React App

{
  "$schema": "https://saas-js.dev/icons/schema.json",
  "outputDir": "./src/components/icons",
  "defaultIconSet": "feather",
  "iconSize": "1.2em"
}

Advanced Configuration

Project-Specific Icon Sets

{
  "defaultIconSet": "lucide",
  "aliases": {
    "brand-github": "github",
    "brand-twitter": "twitter",
    "brand-linkedin": "linkedin"
  }
}

Then use specific icon sets for different types:

# UI icons (using default lucide)
icons add home user settings

# Brand icons (using fa-brands)
icons add --set fa-brands github twitter linkedin

Team Configuration

{
  "$schema": "https://saas-js.dev/icons/schema.json",
  "outputDir": "./src/shared/icons",
  "defaultIconSet": "lucide",
  "iconSize": "1rem",
  "aliases": {
    "house": "home",
    "cog": "settings",
    "user-circle": "profile",
    "envelope": "mail",
    "magnifying-glass": "search",
    "trash-2": "delete",
    "edit-3": "edit",
    "check-circle": "success",
    "x-circle": "error",
    "alert-triangle": "warning",
    "info": "info"
  }
}

Configuration Validation

The configuration file is validated against a JSON schema. Common validation errors:

Invalid Output Directory

{
  "outputDir": "src/icons"  // ❌ Missing leading slash or dot
}

{
  "outputDir": "./src/icons"  // ✅ Correct relative path
}

Invalid Icon Set

{
  "defaultIconSet": "invalid-set"  // ❌ Icon set doesn't exist
}

Invalid Icon Size

{
  "iconSize": "invalid"  // ❌ Invalid size format
}

{
  "iconSize": "16px"  // ✅ Valid size
}

IDE Integration

VS Code

Add to your .vscode/settings.json:

{
  "json.schemas": [
    {
      "fileMatch": ["icons.json"],
      "url": "https://saas-js.dev/icons/schema.json"
    }
  ]
}

This provides:

Auto-completion for configuration options
Validation and error highlighting
Hover documentation

WebStorm/IntelliJ

WebStorm automatically detects the schema from the $schema field.

Best Practices

1. Use Consistent Paths

{
  "outputDir": "./src/components/icons"  // ✅ Consistent with project structure
}

2. Choose One Primary Icon Set

{
  "defaultIconSet": "lucide"  // ✅ Stick to one set for consistency
}

3. Use Meaningful Aliases

{
  "aliases": {
    "house": "home",           // ✅ Clear mapping
    "cog": "settings",         // ✅ Better name
    "user-circle": "profile"   // ✅ More descriptive
  }
}

4. Document Team Conventions

{
  "_comment": "Team conventions: Use lucide for UI icons, fa-brands for social icons",
  "defaultIconSet": "lucide",
  "aliases": {
    "house": "home",
    "cog": "settings"
  }
}

Migration

From v0.0.1 to v0.0.2

If you're upgrading from an older version:

Update the schema URL:

{
  "$schema": "https://saas-js.dev/icons/schema.json"
}

Check for new configuration options in the documentation

Next Steps

CLI Reference - Complete command reference
Icon Sets - Browse available icon sets
TypeScript - TypeScript integration

Configuration

On this page