Configuration

How StarUI discovers and uses project configuration.

Project Configuration

pyproject.toml

StarUI reads its settings from the [tool.starui] section in your project's pyproject.toml.

[tool.starui]
component_dir = "components/ui"
css_output = "static/css/starui.css"
css_dir = "static/css"

component_dir

Directory where components are installed. Relative to project root.

css_output

Path for the generated CSS file.

css_dir

Directory containing input.css. Defaults to the parent directory of css_output.

Configuration Resolution

Priority Order

When resolving settings, StarUI checks these sources in order:

CLI flags

e.g. --component-dir, --output

pyproject.toml

[tool.starui] section

Auto-detection

Scans project structure for common patterns

Auto-Detection Defaults

When no explicit config is found, StarUI infers paths from your project layout:

component_dir

ui/ if it exists, otherwise components/ui/

css_output

static/css/starui.css if static/ exists, assets/starui.css if assets/ exists, otherwise starui.css

css_dir

Parent directory of css_output

Project Structure

What star init creates

Running star init scaffolds the following structure:

my-project/
├── pyproject.toml          # [tool.starui] section added
├── app.py                  # Starter StarHTML app
├── components/
│   └── ui/
│       ├── __init__.py
│       ├── utils.py        # cn() and shared utilities
│       └── theme_toggle.py # Theme toggle + dependencies
├── static/
│   └── css/
│       ├── input.css       # Tailwind v4 input
│       └── starui.css      # Generated output (git-ignored)
└── .starui/
    └── manifest.json       # Component tracking

input.css

The generated input.css uses Tailwind v4 syntax with the StarUI theme system:

@import "tailwindcss";
@plugin "@tailwindcss/typography";

@custom-variant dark (&:where(.dark, .dark *, [data-theme="dark"], ...));

@theme {
  --radius: 0.65rem;
  --font-sans: -apple-system, BlinkMacSystemFont, "Segoe UI", ...;
  --font-mono: ui-monospace, "SF Mono", "Monaco", ...;
}

:root {
  /* Light theme: background, foreground, primary, etc. */
}

.dark, [data-theme="dark"] {
  /* Dark theme overrides */
}

Colors use OKLch color space for perceptually uniform theming. Named theme variants like [data-theme="blue"] are included for easy customization.

Manifest

.starui/manifest.json

The manifest tracks every component and block installed in your project:

{
  "registry_version": "main",
  "components": {
    "button": {
      "version": "0.3.2",
      "checksum": "a1b2c3d4...",
      "file": "components/ui/button.py"
    }
  },
  "blocks": {
    "user_button_01": {
      "version": "0.3.2",
      "checksum": "e5f6a7b8...",
      "file": "blocks/user_button_01/user_button.py"
    }
  }
}

Checksums enable modification detection. When you edit a component locally, star status will flag it as modified and star update will skip it unless --force is used.

Cache

~/.starui/cache/

StarUI maintains a global cache for the Tailwind binary and registry index. Component sources are cached on-demand as you install them:

~/.starui/cache/
├── latest/                       # Tailwind binary version
│   └── tailwindcss-macos-arm64   # Platform-specific binary (~40 MB)
└── registry/
    ├── main/
    │   ├── index.json            # Component registry index
    │   ├── index.meta.json       # Cache timestamp
    │   ├── components/           # Sources fetched during star add
    │   └── blocks/               # Block sources fetched during star add
    └── v0.3.2/                   # Pinned version (immutable)
        └── ...