components.json

The components.json file holds configuration for your project. It’s created when you run npx saastro init and tells the CLI where to install components and how to configure them.

Example

Here’s a typical components.json file:

{
  "$schema": "https://ui.saastro.io/schema.json",
  "style": "default",
  "tailwind": {
    "config": "tailwind.config.mjs",
    "css": "src/styles/globals.css",
    "baseColor": "slate",
    "cssVariables": true
  },
  "aliases": {
    "components": "@/components",
    "utils": "@/lib/utils",
    "ui": "@/components/ui"
  }
}

Options

$schema

The schema URL for IDE autocompletion and validation.

{
  "$schema": "https://ui.saastro.io/schema.json"
}

style

The style preset for your components. Currently available: default.

{
  "style": "default"
}

tailwind

Configuration for your Tailwind CSS setup.

{
  "tailwind": {
    "config": "tailwind.config.mjs",
    "css": "src/styles/globals.css",
    "baseColor": "slate",
    "cssVariables": true
  }
}

Property	Description
`config`	Path to your Tailwind config file
`css`	Path to your global CSS file where CSS variables are defined
`baseColor`	Base color for the theme: `slate`, `gray`, `zinc`, `neutral`, or `stone`
`cssVariables`	Whether to use CSS variables for colors (recommended: `true`)

aliases

Import aliases for your project. These should match your tsconfig.json paths.

{
  "aliases": {
    "components": "@/components",
    "utils": "@/lib/utils",
    "ui": "@/components/ui"
  }
}

Alias	Description
`components`	Base path for all components
`utils`	Path to your utility functions (cn, etc.)
`ui`	Path where UI components will be installed

TypeScript Configuration

Make sure your tsconfig.json has matching path aliases:

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["./src/*"]
    }
  }
}

For Astro projects, you might also need to configure the alias in astro.config.mjs:

import { defineConfig } from "astro/config";
import { fileURLToPath } from "node:url";

export default defineConfig({
  vite: {
    resolve: {
      alias: {
        "@": fileURLToPath(new URL("./src", import.meta.url)),
      },
    },
  },
});

Validation

The CLI validates your components.json on every command. If there’s an issue, you’ll see a helpful error message.

To manually validate:

npx saastro init --check

Multiple Projects (Monorepo)

In a monorepo, each package that uses Saastro UI should have its own components.json:

packages/
├── web/
│   └── components.json
├── docs/
│   └── components.json
└── shared/
    └── components.json

Run CLI commands from the package directory, or use the --cwd flag:

npx saastro add button --cwd packages/web