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,docsornewstemplate. - Styling solution: Choose between plain CSS, Sass, or Tailwind CSS.
- TypeScript: On by default, with a typed
stati.config.tsand esbuild-compiled client code. Answer no for a JavaScript project. - Image tools: Off by default. Answer yes to add
@stati/imagesfor 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 filetsconfig.json- TypeScript compiler configurationsrc/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 devandstati buildrun 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
- Learn about the Project Structure
- Follow the quick start
- Explore core concepts