Stati Documentation

Core Concepts in Stati

Stati is built on several key concepts that work together to create a powerful yet simple static site generation experience. Understanding these concepts will help you make the most of Stati’s features.

Overview

Stati combines modern web development tools with proven static site generation patterns:

The Stati Philosophy

TypeScript-First

Stati is built with TypeScript from the ground up, providing:

  • Full type safety for configuration with stati.config.ts
  • IntelliSense in your editor for all configuration options
  • Built-in esbuild compilation for your client-side TypeScript code
  • Multiple bundles with per-page targeting via include/exclude patterns
  • Automatic script tag injection during dev and build (no template changes needed)
  • Bundle paths available via stati.assets for preloading or custom use
  • Development mode with source maps; production mode with minification and hashing

Minimal Dependencies

Stati keeps its dependency footprint small by:

  • Using modern build tools for development and bundling
  • Leveraging proven libraries like Markdown-It and Eta
  • Avoiding heavy frameworks and unnecessary abstractions
  • Focusing on core functionality that most sites need

Developer Experience

Great DX is at the heart of Stati:

  • Zero-config setup that works out of the box
  • Intuitive file-based routing system
  • Live reload during development
  • Clear error messages and debugging information
  • Flexible enough for any use case

How It All Works Together

Here’s how these concepts combine when you’re working with Stati:

1. Content Creation

You write content in Markdown files with front matter metadata. The file location determines the URL structure.

2. Template Processing

Stati uses Eta templates to render your content, with support for:

  • Layout inheritance
  • Partial templates
  • Custom filters and helpers
  • Dynamic content generation

3. Asset Processing

Stati copies everything from your configured staticDir into the output folder. For preprocessing (Sass, Tailwind, etc.), use project-level scripts or the options generated by create-stati.

4. Smart Caching

ISG tracks dependencies and only rebuilds what’s necessary:

  • Content changes trigger targeted rebuilds
  • Template changes rebuild affected pages
  • Asset changes update only impacted files
  • Time-based cache expiration for dynamic content

5. Output Generation

The final result is a fully static site optimized for:

  • Static delivery (no server-side rendering needed)
  • SEO-friendly URLs
  • Modern web standards
  • Easy deployment anywhere

Getting Deeper

Each core concept builds on the others to create Stati’s unique approach to static site generation. As you dive deeper into each topic, you’ll discover how they work together to create a powerful and flexible system.

Start with Filesystem-based Routing to understand how Stati maps your content to URLs, then explore the other concepts to master the full Stati workflow.