Stati Documentation

Scaffolder (create-stati)

The create-stati package provides an interactive scaffolding tool to quickly set up new Stati projects with styling options.

Quick Start

# Interactive setup
npm create stati my-site

# Non-interactive with options
npm create stati my-site --template=blank --styling=tailwind

# With TypeScript support
npm create stati my-site --typescript

Running the scaffolder will:

  • Create a new project directory
  • Copy the blank starter template files into that directory
  • Update package.json with your project name and Stati metadata
  • Set up optional styling scripts based on the chosen styling option
  • Initialize a Git repository by default (use --no-git to skip)
  • Install dependencies by default (use --no-install to skip)

Note: You can skip automatic dependency installation with --no-install and install them manually later.

Non-Interactive Mode: When all required options are provided via CLI flags, dependencies are installed automatically by default using npm. Use --package-manager to specify a different package manager (yarn, pnpm, or bun).

Interactive Setup

The scaffolder will prompt you for:

  1. Project name - Name for your new Stati site
  2. Styling solution - Choose between CSS, Sass, or Tailwind CSS
  3. TypeScript support - Whether to enable TypeScript compilation
  4. Git initialization - Whether to initialize a Git repository
  5. Dependency installation - Whether to install dependencies automatically
  6. Package manager - Which package manager to use (if multiple are detected)

Command Line Options

npx create-stati <project-name> [options]

Options:
  --template <name>        Template to use (currently: blank)
  --styling <type>         CSS solution (css|sass|tailwind)
  --typescript, --ts       Enable TypeScript support
  --no-git                 Skip git initialization (default: initializes Git)
  --no-install             Skip dependency installation (default: installs dependencies)
  --package-manager <pm>   Package manager to use (npm|yarn|pnpm|bun)
  --help, -h               Show help message

Project Templates

Blank Template

Currently, Stati provides one template:

  • blank - Minimal starter with basic structure and example content

What’s included:

  • Basic site structure (site/, public/)
  • Example homepage and layout
  • Configuration file with sensible defaults
  • Package.json with development scripts

Styling Solutions

Choose your preferred styling approach:

CSS (Default)

  • Basic CSS file in public/styles.css
  • No preprocessing or build step required

Sass

  • Creates src/styles.scss for SCSS source
  • SCSS support with build scripts
  • Automatic compilation during development and build
  • Scripts added: build:css, watch:css
  • Modified scripts: build and dev to include CSS compilation

Tailwind CSS

  • Generates tailwind.config.js with content paths for site/**/*.{md,eta,html} and .stati/tailwind-classes.html
  • Creates source stylesheet at src/styles.css compiled directly to dist/styles.css
  • Scripts added: build:css
  • Modified scripts:
    • dev: Uses Stati’s built-in Tailwind integration (single process)
    • build: Runs Stati build, then CSS compilation

Post-Creation Setup

After creating your site:

cd my-site
npm install  # Skip if you installed dependencies during setup
npm run dev

Package Scripts

All created projects include these base scripts:

{
  "scripts": {
    "dev": "stati dev",
    "build": "stati build",
    "preview": "stati preview",
    "clean:dist": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\"",
    "clean:cache": "node -e \"require('node:fs').rmSync('.stati',{recursive:true,force:true})\"",
    "clean": "npm run clean:dist && npm run clean:cache"
  }
}

Note: When using Sass or Tailwind CSS, the build and dev scripts are automatically modified to include CSS compilation steps. See the Styling Solutions section for details.

Generated Project Structure

Plain CSS (Default)

my-site/
├── site/
│   ├── index.md          # Homepage content
│   └── layout.eta        # Main layout template
├── public/
│   ├── styles.css        # Stylesheet
│   └── favicon.svg       # Site icon
├── stati.config.js       # Stati configuration
├── package.json          # Node.js project file
└── README.md            # Getting started guide

With Sass

my-site/
├── site/
│   └── ...
├── src/
│   └── styles.scss       # Sass source file
├── public/
│   └── favicon.svg       # Site icon
├── stati.config.js
└── package.json          # Includes sass scripts

With Tailwind CSS

my-site/
├── site/
│   └── ...
├── src/
│   └── styles.css        # Tailwind source file
├── public/
│   └── favicon.svg       # Site icon
├── tailwind.config.js    # Tailwind configuration
├── stati.config.js
└── package.json          # Includes Tailwind scripts

With TypeScript Enabled

When using --typescript, additional files are created:

my-site/
├── src/
│   └── main.ts           # TypeScript entry point
├── site/
│   └── ...
├── stati.config.ts       # TypeScript configuration (replaces .js)
├── tsconfig.json         # TypeScript compiler configuration
└── ...

The typecheck script is added to package.json for validating your TypeScript code.

Requirements

  • Node.js 22+
  • npm, yarn, pnpm, or bun

Next Steps

  • Start the development server: npm run dev
  • Add content to the site/ directory
  • Customize the layout in site/layout.eta
  • Configure your site in stati.config.js (or stati.config.ts for TypeScript projects)
  • Learn more about TypeScript support