nitrosh/nitro-cli
Overview
This skill provides a concise guide to nitro-cli, a Python static site generator that builds sites by writing pages as Python code using nitro-ui for programmatic HTML. It covers installation, CLI workflows, project layout, page and component patterns, dynamic routes, and build/deploy commands. The material focuses on practical usage to scaffold, develop, build, and deploy static sites with incremental builds and image optimization.
How this skill works
nitro-cli scaffolds a Python project and runs a dev server with live reload, then produces optimized static output via a production build. Pages are Python modules that return a Page object containing nitro-ui elements; dynamic routes are generated from get_paths() functions. The build pipeline supports image optimization, responsive images, partial hydration (islands), cache-based incremental builds, and platform-aware deploys.
When to use it
- You prefer writing HTML programmatically in Python instead of using templates.
- You need incremental builds and quick local dev with live reload.
- You want responsive image optimization and build-time asset processing.
- You plan to include interactive islands (partial hydration) for small client-side components.
- You need a deploy flow that targets Netlify, Vercel, or Cloudflare with auto-detection.
Best practices
- Organize pages under src/pages and components under src/components for clear separation of concerns.
- Return a nitro.Page from each page module with title and content; mark work-in-progress pages draft=True to exclude them from production builds.
- Use get_paths() for dynamic routes and load data through a datastore to keep page rendering deterministic.
- Keep nitro.config.py minimal and version control config while ignoring .nitro/ and build/ directories.
- Leverage the incremental cache for fast builds; use --force for full rebuilds when needed.
Example use cases
- Create a blog where each post is a dynamic route generated from a JSON/YAML data file.
- Build a documentation site with programmatic navigation and reusable components for code samples and API references.
- Develop a marketing site with responsive images and optimized assets produced at build time.
- Prototype interactive widgets as islands to hydrate only the parts of the page that need JavaScript.
- Deploy the built site to Netlify or Vercel using nitro deploy with auto-detected platform settings.
FAQ
Install via pip: pip install nitro-cli. Then run nitro new to scaffold a project or nitro init in an existing directory.
How are dynamic routes generated?
Create page modules named with [param].py and implement get_paths() to return parameter dicts. The render() function receives params and returns a Page for each generated path.
