Configuration
Configure @saas-js/iconify with icons.json
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
houseicon from the API - Generate a component named
home-icon.tsx(using the alias) - Export
HomeIconcomponent
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 userFramework-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 linkedinTeam 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