---
name: nitro
description: Use when working with the Python "nitro" ecosystem - nitro-cli (static site generator), nitro-ui (HTML as Python classes), nitro-dispatch (plugin/hook system), nitro-validator (data validation), or nitro-image (Pillow pipeline). Covers imports, public API, and how the pieces compose.
---

# Nitro Python Ecosystem

Five small Python libraries that compose into a static-site stack. They are independent on PyPI but designed to fit together. nitro-cli pulls in nitro-ui, nitro-datastore, and nitro-dispatch automatically. nitro-validator and nitro-image are optional add-ons.

| Package | Install | Import | Role |
|---|---|---|---|
| nitro-cli | `pip install nitro-cli` | `nitro` | Static site generator. CLI command is `nitro`. |
| nitro-ui | `pip install nitro-ui` | `nitro_ui` | Build HTML with Python classes instead of templates. |
| nitro-dispatch | `pip install nitro-dispatch` | `nitro_dispatch` | Plugin/hook system. Powers nitro-cli's plugins. |
| nitro-validator | `pip install nitro-validator` | `nitro_validator` | Pipe-string data validation, zero deps. |
| nitro-image | `pip install nitro-image` | `nitro_img` | Chainable, lazy Pillow pipeline. Note the import name. |

Package name vs import name does not always match. The two that bite you: `nitro-ui` -> `nitro_ui`, `nitro-image` -> `nitro_img`.

All five require Python 3.7-3.9+ depending on the package. None require any non-Python services.

---

## nitro-cli (static site generator)

CLI tool plus a Python API for configuring builds. Pages are Python files in `src/pages/` that export a `render()` function returning a `Page` object built from nitro-ui elements.

### Project layout

```
my-site/
  nitro.config.py        # Config(...) instance, see below
  src/
    pages/               # *.py -> *.html (mirrors directory structure)
      index.py           # /index.html
      about.py           # /about.html
      blog/[slug].py     # dynamic route, needs get_paths()
    components/          # reusable functions returning nitro-ui elements
    styles/              # *.css -> /assets/styles/
    static/              # copied to build root as-is
    public/              # also copied to build root
    data/                # *.json / *.yaml, loaded with nitro-datastore
    plugins/             # local plugin files, auto-discovered
  build/                 # output, gitignored
  .nitro/cache.json      # incremental build hashes, gitignored
```

### Config

```python
# nitro.config.py
from nitro import Config

config = Config(
    site_name="My Site",
    base_url="https://mysite.com",
    build_dir="build",
    source_dir="src",
    renderer={"pretty_print": True, "minify_html": False},
    plugins=[],
)
```

The variable must be named `config` and be a `Config` instance.

### Public API

```python
from nitro import (
    Config, Page, env,
    ImageConfig, ImageOptimizer, OptimizedImage,
    Island, IslandConfig, IslandProcessor,
)
```

`env` lazy-loads `.env` (needs `pip install nitro-cli[dotenv]`) and exposes `env.SOMETHING`, `env.is_production()`, `env.is_development()`.

### A page

```python
# src/pages/index.py
from nitro_ui import HTML, Head, Body, Title, Meta, H1, Paragraph
from nitro import Page

def render():
    return Page(
        title="My Page",
        meta={"description": "Page description"},
        content=HTML(
            Head(Meta(charset="UTF-8"), Title("My Page")),
            Body(H1("Hello"), Paragraph("Welcome.")),
        ),
    )
```

`Page(title, content, meta=None, template=None, draft=False)`. Drafts render in `nitro dev` but are skipped in `nitro build` and excluded from the sitemap.

### Dynamic routes

```python
# src/pages/blog/[slug].py
def get_paths():
    return [{"slug": "hello-world", "title": "Hello"}, {"slug": "intro", "title": "Intro"}]

def render(slug, title):
    ...
    return Page(title=title, content=...)
```

Multiple params work the same way (`[category]/[slug].py` -> `get_paths()` returns dicts with both keys).

### CLI commands

| Command | What it does |
|---|---|
| `nitro new <name>` | Scaffold a project. `--no-git`, `--no-install`. |
| `nitro init` | Add Nitro to an existing dir. `--force` to overwrite. |
| `nitro dev` / `serve` | Dev server with WebSocket live reload. `--port`, `--host`, `--open`, `--no-reload`. |
| `nitro build` | Production build. `--clean`, `--force`, `--no-minify`, `--no-optimize`, `--no-fingerprint`, `--no-responsive`, `--no-islands`, `--output dist`. |
| `nitro preview` | Serve `build/` locally. `--port`, `--open`. |
| `nitro clean` | Remove `build/` and `.nitro/`. `--build`, `--cache`, `--all`, `--dry-run`. |
| `nitro routes` | List routes. `--json`. |
| `nitro check` | Validate without building. `--no-links`. |
| `nitro deploy` | Auto-detect Netlify/Vercel/Cloudflare. `--platform`, `--prod`, `--no-build`. |
| `nitro export` | Zip the build. `-o`, `--build-first`. |
| `nitro info` | Diagnostics. `--json`. |

All commands accept `--verbose` / `-v` and `--debug` (full tracebacks).

### Build cache

`nitro build` uses content hashes in `.nitro/cache.json`. Page changes rebuild only that page; component or data file changes rebuild everything; config changes trigger a full rebuild. `--force` bypasses; `nitro clean --cache` clears it.

### Islands (partial hydration)

Islands let specific components hydrate on the client while the rest stays static.

```python
from nitro import Island

island = Island(
    name="counter",
    component=Counter,            # function returning a nitro-ui element
    props={"count": 0},
    client="visible",             # load | idle (default) | visible | media | interaction | none
    client_only=False,
    media=None,                   # CSS media query, only with client="media"
)
```

Renders to a `<div data-island="counter" data-hydrate="visible" data-props="...">...</div>` with the server-side HTML inside. Register a JS hydrator with `window.__registerIsland("counter", function(props) { ... })` returning a string, or an object with `mount()` / `render()`.

Disable processing with `nitro build --no-islands`.

### Image optimisation

`ImageConfig` controls responsive image generation in `nitro build`. Defaults: sizes `[320, 640, 768, 1024, 1280, 1920]`, formats `["avif", "webp", "original"]`, quality `{avif: 80, webp: 85, jpeg: 85, png: 85}`. The bundler scans built HTML for `<img src=...>` and rewrites them as `<picture>` elements with srcsets.

External URLs, data URIs, and images smaller than `min_size` (default 1024 bytes) are skipped. Requires Pillow; AVIF requires `pip install nitro-cli[images]`.

### Plugins (built on nitro-dispatch)

```python
# src/plugins/analytics.py
from nitro.plugins import NitroPlugin, hook

class Plugin(NitroPlugin):
    name = "analytics"
    version = "1.0.0"

    @hook('nitro.post_generate', priority=50)
    def inject(self, data):
        data['output'] = data['output'].replace('</body>', '<script src="/a.js"></script></body>')
        return data
```

Add `"analytics"` to `config.plugins`. Discovery order: installed packages first, then `src/plugins/<name>.py`. The module must export `Plugin`.

Hooks: `nitro.init`, `nitro.pre_generate`, `nitro.post_generate` (`{output: html}`), `nitro.pre_build`, `nitro.post_build`, `nitro.process_data`, `nitro.add_commands`.

---

## nitro-ui (HTML as Python classes)

Zero-dependency HTML generation. Every element is a class. Children are positional args, attributes are keyword args. Call `.render()` to get HTML.

```python
from nitro_ui import Div, H1, Paragraph

Div(H1("Hi"), Paragraph("Hello"), cls="container").render()
# <div class="container"><h1>Hi</h1><p>Hello</p></div>
```

### Element name vs HTML tag

Most are obvious (`Div`, `H1`, `Header`). The non-obvious ones:

| nitro-ui | HTML | nitro-ui | HTML |
|---|---|---|---|
| `Paragraph` | `<p>` | `UnorderedList` | `<ul>` |
| `Anchor` (preferred) / `Href` | `<a>` | `OrderedList` | `<ol>` |
| `Link` | `<link>` (stylesheet/meta) | `ListItem` | `<li>` |
| `Image` | `<img>` | `TableHeader` / `TableBody` / `TableFooter` | `<thead>` / `<tbody>` / `<tfoot>` |
| `HorizontalRule` | `<hr>` | `TableRow` / `TableHeaderCell` / `TableDataCell` | `<tr>` / `<th>` / `<td>` |
| `DescriptionList` / `Term` / `Details` | `<dl>` / `<dt>` / `<dd>` | `Strikethrough` / `Bold` / `Italic` | `<s>` / `<b>` / `<i>` |

`Anchor` is preferred for `<a>`; `Href` is the legacy alias. Don't confuse `Link` (stylesheet) with `Anchor` (link).

### Attribute naming

- `cls=` or `class_name=` -> `class="..."`
- `for_element=` or `for_=` -> `for="..."`
- `data_value="x"` -> `data-value="x"` (underscores in `data_*` and `aria_*` become hyphens)
- `hx_get="/url"` -> `hx-get="/url"` (HTMX support is automatic)
- SVG attrs: snake_case kwargs convert to camelCase. `view_box="0 0 24 24"` -> `viewBox="0 0 24 24"`
- Boolean attrs (`disabled`, `checked`, `required`, `hidden`, `readonly`, `autofocus`, etc.): pass `True` to render bare, `False`/`None` to omit. `disabled="False"` (string) is still truthy and renders.

### Methods (all chainable except where noted)

```python
el.append(*children)            # add to end
el.prepend(*children)           # add to start
el.add_attribute(key, value)
el.add_attributes([(k, v), ...])
el.remove_attribute(key)
el.add_style(key, value)        # validates against javascript:, expression(), etc.
el.add_styles({...})
el.clone()                      # deep copy
el.render(pretty=False)         # to HTML string
el.to_dict() / to_json()
HTMLElement.from_dict(d) / from_json(s)

el.replace_child(i, new)        # returns None, NOT chainable
el.generate_id()                # returns None, NOT chainable
```

### Reusable components

Two ways. Function-style is fine for simple stuff:

```python
def Card(title, body, link=None):
    children = [H3(title), Paragraph(body)]
    if link:
        children.append(Anchor("Read more", href=link))
    return Div(*children, cls="card")
```

Class-style with `Component` + `Slot` for templated, slot-based composition:

```python
from nitro_ui import Component, Slot, H2, Paragraph, Div, Button

class Modal(Component):
    tag = "div"
    class_name = "modal"

    def template(self, title):
        return [
            Div(H2(title), Slot("actions"), cls="header"),
            Div(Slot(), cls="body"),                     # default slot
            Div(Slot("footer", default=Button("Close")), cls="footer"),
        ]

Modal("Confirm",
    Paragraph("Are you sure?"),
    actions=Button("X"),
    footer=[Button("Cancel"), Button("OK")],
    id="m1",
)
```

User-provided `cls` merges with the component's `class_name`. Slot kwargs accept a single element or a list.

### Fragment and Partial

`Fragment(...)` renders children with no wrapper tag. `Partial("<raw html>")` or `Partial(file="x.html")` embeds raw HTML, bypassing escaping. Only use `Partial` for trusted content.

### Form fields

`Field` generates inputs with HTML5 validation attrs:

```python
from nitro_ui import Form, Button, Field

Form(
    Field.email("email", label="Email", required=True),
    Field.password("password", label="Password", min_length=8),
    Field.select("country", ["USA", "Canada"], value="Canada"),
    Field.checkbox("terms", label="I agree", required=True),
    Field.radio("plan", [("free", "Free"), ("pro", "Pro")], value="free"),
    Button("Submit", type="submit"),
    action="/submit", method="post",
)
```

Available: `text`, `email`, `password`, `url`, `tel`, `search`, `textarea`, `number`, `range`, `date`, `time`, `datetime_local`, `select`, `checkbox`, `radio`, `file`, `hidden`, `color`. All take an optional `wrapper="form-field"` (or dict) to wrap in a div, and forward extra kwargs (including `hx_*`) to the underlying input.

### Stylesheet system (optional)

```python
from nitro_ui.styles import CSSStyle, StyleSheet, Theme

ss = StyleSheet(theme=Theme.modern())
btn = ss.register("btn-primary", CSSStyle(
    background_color="#007bff", color="white",
    _hover=CSSStyle(background_color="#0056b3"),   # pseudo-selector
    _md=CSSStyle(padding="15px 30px"),             # breakpoint
))
# pseudo: _hover, _active, _focus, _visited, _link, _first_child, _last_child, _nth_child, _before, _after
# breakpoints: _xs (0), _sm (640), _md (768), _lg (1024), _xl (1280), _2xl (1536)

ss.register_bem("card", element="header", style=CSSStyle(font_weight="bold"))  # -> "card__header"
ss.register_bem("card", modifier="featured", style=CSSStyle(border="2px"))     # -> "card--featured"

Style(ss.render())   # put inside <head>
```

`Theme.modern()`, `Theme.classic()`, `Theme.minimal()` are presets.

---

## nitro-dispatch (plugins, hooks, events)

Framework-agnostic. Three pieces: `PluginBase` (subclass for your plugin), `PluginManager` (orchestrator), and `@hook` (decorator on plugin methods).

```python
from nitro_dispatch import PluginManager, PluginBase, hook

class WelcomePlugin(PluginBase):
    name = "welcome"               # required
    version = "1.0.0"
    dependencies = []

    @hook('user.login', priority=100, timeout=5.0)
    def greet(self, data):
        data['greeted'] = True
        return data

manager = PluginManager()
manager.register(WelcomePlugin)
manager.load_all()
result = manager.trigger('user.login', {'username': 'Alice'})
```

### How hooks behave

- Higher `priority` runs first (default 50). Each hook receives data, mutates it, returns it. The return value flows to the next hook.
- Wildcards: `user.*` matches `user.login`, `user.logout`. `db.before_*` matches `db.before_save`. `*` matches one segment, separated by `.`.
- `raise StopPropagation("reason")` halts the chain.
- Async hooks: `async def` is auto-detected. `await manager.trigger_async('event', data)` runs them natively. Sync hooks called via `trigger_async` run in a worker thread.
- Timeouts are thread-based (`concurrent.futures`). Don't try to use `signal` here; it crashed previously.
- Error strategies: `manager.set_error_strategy('log_and_continue' | 'fail_fast' | 'collect_all')`.

### Discovery and lifecycle

```python
manager.discover_plugins('~/.app/plugins', pattern='*_plugin.py', recursive=True)
manager.reload('my_plugin')        # importlib.reload + re-instantiate
manager.disable_plugin('cache')    # hooks won't fire
manager.enable_plugin('cache')
```

Built-in lifecycle events you can hook: `nitro.plugin.registered`, `nitro.plugin.loaded`, `nitro.plugin.unloaded`, `nitro.plugin.error`, `nitro.app.startup`, `nitro.app.shutdown`. Available as `PluginManager.EVENT_PLUGIN_LOADED`, etc.

### Common gotchas

- `PluginBase.__init__` collects `@hook`-decorated methods into `self._hooks`. If you override `__init__`, call `super().__init__()`.
- A plugin's `name` class attribute must be unique within the manager.
- Discovery instantiates the class once during `register()`. Don't put side effects in `PluginBase.__init__`.

### Exceptions

All inherit from `NitroPluginError`: `PluginLoadError`, `PluginRegistrationError`, `PluginNotFoundError`, `PluginDiscoveryError`, `DependencyError`, `HookError`, `HookTimeoutError`, `ValidationError`, `StopPropagation`.

---

## nitro-validator (data validation)

Pipe-string rules, zero dependencies. The library is also exported under shorter aliases (`Validator`, `Rule`, `ValidationError`, `RuleRegistry`); both naming schemes are first-class.

```python
from nitro_validator import NitroValidator, NitroValidationError

v = NitroValidator()
data  = {'email': 'a@b.com', 'age': '25', 'password': 's3cret!!', 'password_confirmation': 's3cret!!'}
rules = {
    'email': 'required|email',
    'age': 'required|integer|min:18',
    'password': 'required|min:8|confirmed',
}

try:
    validated = v.validate(data, rules)
except NitroValidationError as e:
    print(e.errors)   # {'field': ['msg', ...]}
```

Or non-throwing:

```python
if not v.is_valid(data, rules):
    print(v.get_errors())        # dict
    print(v.get_errors_flat())   # flat list
```

### Rule syntax

`'required'`, `'min:18'`, `'between:1,100'`, `'in:admin,user,guest'`. Pipe to combine: `'required|email|max:255'`. Args are always strings to the rule's `__init__`; cast inside the rule.

### Built-in rules (selected)

Basic: `required`, `optional`.

String: `alpha`, `alphanumeric`, `alpha_dash`, `lowercase`, `uppercase`, `email`, `url`, `uuid`, `ip` / `ipv4` / `ipv6`, `json`, `slug`, `ascii`, `base64`, `hex_color`, `credit_card` (Luhn), `mac_address`, `timezone`, `locale`, `regex:pattern`, `starts_with:str`, `ends_with:str`, `contains:str`.

Numeric: `numeric`, `integer`, `positive`, `negative`, `min:n`, `max:n`, `between:lo,hi`, `divisible_by:n`. For strings/arrays, `min`/`max`/`between` check length.

Comparison: `same:field`, `different:field`, `in:a,b,c`, `not_in:a,b,c`.

Boolean: `boolean` (accepts true/false, 1/0, yes/no, on/off).

Date: `date`, `before:YYYY-MM-DD`, `after:YYYY-MM-DD`, `date_equals:YYYY-MM-DD`, `date_format:%Y-%m-%d`. The first four only accept ISO 8601. For regional formats use `date_format` with a `strptime` string. Don't try to "fix" the strict ISO behaviour - it's intentional.

Convenience: `confirmed` (matches `<field>_confirmation`), `accepted` (true/yes/1/on), `declined` (false/no/0/off).

Length/size/collection: `length:n`, `size:n`, `array`, `distinct`.

### Custom rules

```python
from nitro_validator import NitroValidationRule, NitroValidator

class StrongPasswordRule(NitroValidationRule):
    name = "strong_password"
    message = "The {field} must contain upper, lower, digit, and symbol."

    def validate(self, field, value, data):
        if not value:
            return True   # let `required` handle empties
        return (any(c.isupper() for c in value)
                and any(c.islower() for c in value)
                and any(c.isdigit() for c in value)
                and any(c in '!@#$%^&*' for c in value))

v = NitroValidator()
v.register_rule(StrongPasswordRule)
v.validate({'password': 'Abc1!def'}, {'password': 'required|strong_password'})
```

Rule of thumb: every rule except `required`, `accepted`, `declined` returns `True` for empty values. This is what makes `'email'` (without `'required'`) work for optional fields.

### Custom messages

```python
v.validate(data, rules, messages={
    'email': 'Please enter a valid email',          # one msg for all rules on field
    'password': {                                   # per-rule
        'required': 'Password is required',
        'min': 'Password must be at least 8 characters',
    },
})
```

---

## nitro-image (image pipeline)

Pillow wrapper with a chainable, lazy pipeline. Nothing runs until an output method is called. Import as `nitro_img` (note the underscore-i).

```python
from nitro_img import Image

Image("photo.jpg").resize(800).webp(quality=80).save("out.webp")
```

### Loaders

```python
Image("photo.jpg")             # path
Image.from_bytes(raw)
Image.from_base64(b64)         # handles "data:image/...;base64," prefix
Image.from_file(file_obj)
Image.from_url("https://...")  # needs `pip install nitro-image[url]`
```

### Properties (read from original, ignore pipeline)

`img.width`, `img.height`, `img.size`, `img.source_format`, `img.get_metadata()` (dict with width/height/mode/format/exif).

### Deferred (chainable) operations

Resize and crop:

```python
img.resize(width=800)
img.resize(800, allow_upscale=True)
img.thumbnail(200, 200)                 # fit within box
img.cover(400, 400)                     # fill exact, center-crop overflow
img.contain(400, 400, bg="white")       # fit and pad
img.crop(400, 300, anchor="top-left")
```

Anchors: `center` (default), `top-left`, `top-right`, `bottom-left`, `bottom-right`, `top`, `bottom`, `left`, `right`.

Transforms and effects:

```python
img.rotate(90, expand=True, fill="black")
img.flip()                # vertical
img.mirror()              # horizontal
img.grayscale()
img.strip_metadata()
img.brightness(1.2)       # >1 brighter
img.contrast(1.1)
img.saturation(1.3)
img.sharpen(1.5)          # default 2.0
img.blur(3.0)             # gaussian radius
img.sepia()
img.rounded_corners(20)   # produces alpha channel
```

Overlays:

```python
img.watermark("logo.png", position="bottom-right", opacity=0.3, scale=0.2, margin=10)
img.watermark("logo.png", position="tiled")
img.text_overlay("Sample", position="center", font_size=48, color="white")
```

Format setters (deferred):

```python
img.jpeg(quality=90)
img.png()
img.webp(quality=80)
img.gif()
img.format("WEBP")        # or Format.WEBP
img.auto_format()          # picks best at output time
```

### Immediate methods (run the pipeline)

```python
img.save("out.webp")                         # returns Path
img.to_bytes()
img.to_base64()
img.to_data_uri()                            # "data:image/webp;base64,..."
img.to_response()                            # {body, content_type, content_length}
img.to_django_response(filename=...)
img.to_flask_response(filename=...)
img.to_fastapi_response(filename=...)

img.responsive([400, 800, 1200])             # -> {400: bytes, 800: bytes, ...}
img.save_responsive("out/", [400, 800], name="hero")  # -> {400: Path, ...}
img.optimize(target_kb=200)                  # binary-search quality, returns bytes

img.lqip()                                   # 20px base64 data URI placeholder
img.dominant_color()                         # "#3a6b8c"
img.color_palette(count=5)                   # list of hex
img.svg_placeholder(width=800, height=600)
img.blurhash()                               # needs `pip install nitro-image[blur]`
```

### Format resolution priority

When an output method runs and no format is set:

1. Explicit setter (`.jpeg()`, `.webp()`, etc.)
2. `.auto_format()` flag
3. `.save()` path extension
4. Source image format
5. Raises `ImageFormatError`

`.to_bytes()` can't use #3 (no path), so set a format explicitly.

### Batch

```python
from nitro_img import BatchImage

(BatchImage("photos/*.jpg")
    .resize(800).brightness(1.05).webp(quality=82)
    .save("out/{name}.webp", parallel=True, max_workers=4))
```

`{name}` is the source filename stem. Raises `ImageLoadError` if no files match. BatchImage records operations and replays them per file - it doesn't share an Image instance.

### Presets

`Image.preset.thumbnail`, `.avatar`, `.avatar_placeholder`, `.og_image` (1200x630), `.banner` (1920x400), `.responsive`. All return bytes (or `{width: Path}` for `.responsive`), not Image instances.

```python
Image.preset.og_image("photo.jpg", quality=85)
Image.preset.avatar_placeholder("SN", size=256, bg="#E74C3C")
```

### Config

```python
from nitro_img import config
config.update(
    default_jpeg_quality=85, default_webp_quality=80, default_png_compression=6,
    allow_upscale=False, auto_orient=True, strip_metadata=False,
    max_input_size=50_000_000, max_output_dimensions=10_000,
    url_timeout=30.0, url_max_size=50_000_000,
)
```

### Gotchas

- JPEG has no alpha. Rounded corners + `.jpeg()` flattens onto white. Use `.png()` or `.webp()` for transparency.
- No upscale by default. `resize(1600)` on an 800px source is a no-op without `allow_upscale=True`. Same for `cover`/`contain`/`thumbnail`.
- Responsive dedupes when not upscaling. `[800, 1200, 1600]` on an 800px source -> `{800: bytes}`.
- The pipeline runs on every output call. Multiple outputs from the same `Image` re-execute the full chain. The original is never mutated.

### Errors

All inherit from `NitroImgError`: `ImageLoadError`, `ImageFormatError`, `ImageSizeError`, `ImageProcessingError`, `ImageOutputError`.

---

## How they compose

A typical nitro-cli site uses all four siblings:

```python
# src/pages/blog/[slug].py
from nitro import Page
from nitro_ui import HTML, Head, Body, Title, Meta, H1, Article, Image, Div
from nitro_datastore import NitroDataStore
from nitro_validator import NitroValidator, NitroValidationError
from nitro_img import Image as Img
from pathlib import Path

posts = NitroDataStore.from_file("src/data/posts.json")

def get_paths():
    return [{"slug": p.slug, "title": p.title, "body": p.body, "hero": p.hero}
            for p in posts.items]

def render(slug, title, body, hero):
    Img(f"src/static/{hero}").save_responsive(
        "build/_img/", [400, 800, 1200], name=Path(hero).stem,
    )

    return Page(
        title=title,
        meta={"description": body[:140]},
        content=HTML(
            Head(Meta(charset="UTF-8"), Title(title)),
            Body(
                Article(
                    H1(title),
                    Image(src=f"/_img/{Path(hero).stem}_800.webp", alt=title),
                    Div(body),
                ),
            ),
        ),
    )
```

A plugin that uses nitro-validator on form submissions during build:

```python
# src/plugins/validate_data.py
from nitro.plugins import NitroPlugin, hook
from nitro_validator import NitroValidator, NitroValidationError

class Plugin(NitroPlugin):
    name = "validate_data"

    @hook('nitro.process_data', priority=100)
    def check(self, data):
        v = NitroValidator()
        for entry in data.get('items', []):
            try:
                v.validate(entry, {'email': 'required|email', 'name': 'required'})
            except NitroValidationError as e:
                print(f"Bad entry: {e.errors}")
        return data
```

---

## House style for output

When generating prose (commit messages, docs, copy, CLI output) for these projects:

- Hyphens only. No em-dashes or en-dashes.
- No emojis.
- No inline code comments unless absolutely necessary.
- Don't make output read like an LLM wrote it. Natural rhythm, contractions where they fit, no boilerplate hedging.

---

## When to look deeper

Each package ships its own SKILL.md inside the repo (`nitro-cli/SKILL.md`, `nitro-ui/SKILL.md`, etc.). They're long-form references with the complete element/method/rule tables. Check them when the surface here isn't enough - especially nitro-ui's full tag list, nitro-validator's exact rule semantics, and nitro-image's preset parameter tables.

The READMEs on the pinned PyPI versions are the user-facing docs. CLAUDE.md inside each repo covers internal architecture and contributor conventions; ignore unless you're modifying the library.