Skip to main content

​
Configuration File

The Fumadocs CLI uses a cli.json configuration file to manage paths, aliases, and project settings.

​
Location

By default, the CLI looks for cli.json in the current directory. You can specify a custom location: 
npx fumadocs add search --config ./config/fumadocs-cli.json

​
Creating a Configuration

Initialize a new configuration file: 
npx fumadocs
This creates cli.json with defaults based on your project structure.

​
Configuration Schema

The CLI configuration supports the following options:

​
$schema

Type: string Description: JSON Schema reference for IDE autocomplete and validation. Auto-generated based on project structure:
  • With src directory: node_modules/@fumadocs/cli/dist/schema/src.json
  • Without src directory: node_modules/@fumadocs/cli/dist/schema/default.json
{
  "$schema": "node_modules/@fumadocs/cli/dist/schema/default.json"
}
The schema provides autocomplete in editors like VS Code, making configuration easier.

​
baseDir

Type: string Default: "" (root) or "src" (if src directory detected) Description: Base directory for your project files. All component paths are resolved relative to this directory. 
{
  "baseDir": "src"
}
Examples: 
{
  "baseDir": ""
}

// Components installed to:
// ./components/ui/button.tsx
// ./lib/utils.ts

​
aliases

Type: object Description: Configure where different types of files are installed.

​
aliases.uiDir

Type: string Default: "./components/ui" Description: Directory for UI components (e.g., buttons, cards, dialogs). 
{
  "aliases": {
    "uiDir": "./components/ui"
  }
}

​
aliases.componentsDir

Type: string Default: "./components" Description: Directory for regular components and blocks. 
{
  "aliases": {
    "componentsDir": "./components"
  }
}

​
aliases.blockDir

Type: string Default: "./components" Description: Directory for block components (larger, composed components). 
{
  "aliases": {
    "blockDir": "./components/blocks"
  }
}

​
aliases.cssDir

Type: string Default: "./styles" Description: Directory for CSS and style files. 
{
  "aliases": {
    "cssDir": "./styles"
  }
}

​
aliases.libDir

Type: string Default: "./lib" Description: Directory for utility functions and helper libraries. 
{
  "aliases": {
    "libDir": "./lib"
  }
}
Complete aliases example: 
{
  "aliases": {
    "uiDir": "./components/ui",
    "componentsDir": "./components",
    "blockDir": "./components/blocks",
    "cssDir": "./app/styles",
    "libDir": "./utils"
  }
}

​
uiLibrary

Type: "radix-ui" | "base-ui" Default: "radix-ui" Description: Which UI component library to use for Fumadocs UI components. 
{
  "uiLibrary": "radix-ui"
}
Registry: fumadocs/radix-uiDescription: Uses Radix UI primitives for accessible, unstyled components.Best for: Projects already using Radix UI or those wanting maximum accessibility.
{
  "uiLibrary": "radix-ui"
}

​
commands

Type: object Description: Configure CLI command behavior and post-processing.

​
commands.format

Type: string (optional) Description: Command to run for formatting generated code automatically after installation. 
{
  "commands": {
    "format": "prettier --write"
  }
}
Examples: 
{
  "commands": {
    "format": "prettier --write"
  }
}
The format command receives the file path as an argument automatically.

​
Complete Configuration Examples

​
Default Configuration

Generated for projects without a src directory:
cli.json
{
  "$schema": "node_modules/@fumadocs/cli/dist/schema/default.json",
  "aliases": {
    "uiDir": "./components/ui",
    "componentsDir": "./components",
    "blockDir": "./components",
    "cssDir": "./styles",
    "libDir": "./lib"
  },
  "baseDir": "",
  "uiLibrary": "radix-ui",
  "commands": {}
}

​
Source Directory Configuration

Generated for projects with a src directory:
cli.json
{
  "$schema": "node_modules/@fumadocs/cli/dist/schema/src.json",
  "aliases": {
    "uiDir": "./components/ui",
    "componentsDir": "./components",
    "blockDir": "./components",
    "cssDir": "./styles",
    "libDir": "./lib"
  },
  "baseDir": "src",
  "uiLibrary": "radix-ui",
  "commands": {}
}

​
Custom Configuration

Example with custom paths and formatters:
cli.json
{
  "$schema": "node_modules/@fumadocs/cli/dist/schema/src.json",
  "aliases": {
    "uiDir": "./ui",
    "componentsDir": "./components",
    "blockDir": "./blocks",
    "cssDir": "./app/styles",
    "libDir": "./utils"
  },
  "baseDir": "src",
  "uiLibrary": "base-ui",
  "commands": {
    "format": "biome format --write"
  }
}

​
Monorepo Configuration

Example for a monorepo package:
packages/docs/cli.json
{
  "$schema": "../../node_modules/@fumadocs/cli/dist/schema/default.json",
  "aliases": {
    "uiDir": "./components/ui",
    "componentsDir": "./components",
    "blockDir": "./components/blocks",
    "cssDir": "./styles",
    "libDir": "./lib"
  },
  "baseDir": "app",
  "uiLibrary": "radix-ui",
  "commands": {
    "format": "pnpm format"
  }
}

​
Path Resolution

​
How Paths Work

The CLI resolves component installation paths using this formula: 
{baseDir}/{aliasDir}/{componentPath}
Example: 
{
  "baseDir": "src",
  "aliases": {
    "uiDir": "./components/ui"
  }
}
Installing a button component: 
src/components/ui/button.tsx

​
Relative vs Absolute Paths

All alias paths should be relative (starting with ./): 
{
  "aliases": {
    "uiDir": "./components/ui",
    "libDir": "./lib"
  }
}

​
Component Type Mapping

Components are installed to different directories based on their type:
Component TypeAliasExample
uiuiDircomponents/ui/button.tsx
componentscomponentsDircomponents/search.tsx
blockblockDircomponents/hero.tsx
liblibDirlib/utils.ts
csscssDirstyles/globals.css
routebaseDirapp/api/search/route.ts

​
IDE Integration

​
VS Code

The $schema field enables autocomplete and validation in VS Code:
  1. Open cli.json in VS Code
  2. Start typing to see autocomplete suggestions
  3. Hover over fields for documentation
  4. Get instant validation for invalid values

​
TypeScript Path Aliases

Ensure your tsconfig.json paths match your CLI configuration:
tsconfig.json
{
  "compilerOptions": {
    "paths": {
      "@/*": ["./src/*"],
      "@/components/*": ["./src/components/*"],
      "@/lib/*": ["./src/lib/*"],
      "@/styles/*": ["./src/styles/*"]
    }
  }
}
If your TypeScript paths don’t match CLI aliases, imports may break.

​
Environment Detection

The CLI automatically detects your project structure:

​
src Directory Detection

When you run npx fumadocs, the CLI:
  1. Checks if a src directory exists
  2. Sets baseDir to "src" if found, "" otherwise
  3. Uses the appropriate schema reference
Detection logic: 
const hasSrc = await fs.stat('./src').then(() => true).catch(() => false);
const baseDir = hasSrc ? 'src' : '';

​
Package Manager Detection

The CLI automatically detects your package manager for dependency installation:
  • Checks for pnpm-lock.yaml → uses pnpm
  • Checks for yarn.lock → uses yarn
  • Checks for package-lock.json → uses npm
  • Defaults to npm if none found

​
Migration Guide

​
Changing baseDir

If you need to move from a root-level to src-based structure:
1

Update baseDir

cli.json
{
  "baseDir": "src"
}
2

Move existing components

mkdir -p src
mv components src/
mv lib src/
mv styles src/
3

Update imports

Update import paths in your files to include src/ or use @/ alias.
4

Update schema reference

cli.json
{
  "$schema": "node_modules/@fumadocs/cli/dist/schema/src.json"
}

​
Switching UI Libraries

To switch from Radix UI to Base UI (or vice versa):
1

Update configuration

cli.json
{
  "uiLibrary": "base-ui"
}
2

Reinstall components

# Remove existing UI components
rm -rf src/components/ui

# Reinstall with new UI library
npx fumadocs add button card dialog
3

Update dependencies

Install the new UI library’s peer dependencies as prompted.

​
Troubleshooting

Problem: Components are being installed to unexpected locations.Solution: Check your baseDir and alias configuration:
# View current configuration
cat cli.json

# Verify paths are correct
# Remember: {baseDir}/{alias}/{component}
Problem: VS Code shows errors in cli.json.Solution: Ensure your schema reference matches your project structure:
// For projects with src directory:
{
  "$schema": "node_modules/@fumadocs/cli/dist/schema/src.json"
}

// For projects without src directory:
{
  "$schema": "node_modules/@fumadocs/cli/dist/schema/default.json"
}
Problem: TypeScript can’t find imported components.Solution: Ensure tsconfig.json paths match CLI aliases:
tsconfig.json
{
  "compilerOptions": {
    "paths": {
      "@/components/*": ["./src/components/*"],
      "@/lib/*": ["./src/lib/*"]
    }
  }
}
Problem: Code isn’t being formatted after installation.Solution: Ensure the format command is installed and accessible:
# Install formatter as dev dependency
npm install -D prettier

# Update config
{
  "commands": {
    "format": "prettier --write"
  }
}

​
Best Practices

Version control

Always commit cli.json to ensure consistent component paths across your team.

Match TypeScript paths

Keep tsconfig.json paths in sync with CLI aliases to avoid import errors.

Use auto-formatting

Configure commands.format to maintain consistent code style automatically.

Document customizations

Add comments to explain non-standard alias configurations for team members.

Build docs developers (and LLMs) love

Get started for freeTalk to us