Installation

Prerequisites

  • Node.js 22.20 or later on the 22.x line, or 24 and later
  • A package manager: npm, pnpm, yarn or bun

Interactive scaffolder

The easiest way to get started with Stati is using the create-stati interactive scaffolder.

npx create-stati

This command will launch an interactive setup wizard that guides you through creating a new project. You’ll be prompted for:

  • Project name: The directory for your new site.
  • Template: Start from the blank, blog, docs or news template.
  • Styling solution: Choose between plain CSS, Sass, or Tailwind CSS.
  • TypeScript: On by default, with a typed stati.config.ts and esbuild-compiled client code. Answer no for a JavaScript project.
  • Image tools: Off by default. Answer yes to add @stati/images for responsive images and link preview cards.
  • Agent skill: Optionally install the Stati agent skill for AI coding assistants.
  • Git initialization: Optionally initialize a new Git repository.
  • Dependency installation: Choose whether to install dependencies automatically.
  • Package manager: Select your preferred package manager (npm, yarn, pnpm, or bun) if multiple are available.

Command-line options

You can also pass command-line arguments to pre-configure the scaffolder and skip some interactive prompts.

npx create-stati my-site --styling tailwind

This creates a project in my-site with Tailwind CSS and asks only the remaining questions (template, TypeScript, image tools, agent skill, Git, dependency installation and, when several are detected, the package manager). To skip every prompt, see Running without prompts. See Command line options for every flag.

TypeScript by default

New projects use TypeScript unless you opt out:

npx create-stati my-site

This creates a project with:

  • stati.config.ts - Type-safe configuration file
  • tsconfig.json - TypeScript compiler configuration
  • src/main.ts - Entry point for client-side TypeScript code

Stati compiles your TypeScript files from src/ using esbuild. Run npm run typecheck to validate your TypeScript code. Learn more in the TypeScript configuration guide.

For a JavaScript project instead, pass --no-typescript (you get stati.config.js and no src/ entry point).

Tip: If you choose Tailwind CSS, the scaffolder sets up Stati’s built-in Tailwind integration in the dev and build scripts. stati dev and stati build run Tailwind themselves, so you need no separate CSS scripts. See Tailwind CSS.

Manual installation

If you prefer to set up Stati manually:

# Create a new directory
mkdir my-stati-site
cd my-stati-site

# Initialize npm as an ES module package
npm init -y
npm pkg set type=module

# Install Stati
npm install --save-dev @stati/cli @stati/core

# Create basic structure
mkdir site public
echo '# Hello Stati' > site/index.md

Create site/layout.eta, the layout every page uses:

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <title><%= stati.page.title || stati.site.title %></title>
  </head>
  <body>
    <main><%~ stati.content %></main>
  </body>
</html>

Create a stati.config.js file:

import { defineConfig } from '@stati/core';

export default defineConfig({
  site: {
    title: 'My Stati Site',
    baseUrl: 'https://example.com',
  },
});

Add scripts to your package.json:

{
  "type": "module",
  "scripts": {
    "dev": "stati dev",
    "build": "stati build",
    "preview": "stati preview"
  }
}

Optional: image tools

Stati sizes and lazy-loads Markdown images without extra packages. For responsive AVIF and WebP images and an Open Graph image for every page, install @stati/images and turn the features on in your config:

npm install --save-dev @stati/images

See Images for the options.

Verification

To verify your installation works:

# Start the development server
npm run dev

# Build the site
npm run build

# Preview the built site
npm run preview

The development server runs at http://localhost:3000 and the preview server at http://localhost:4000.

Next steps