create-stati

v1.11.8

Published

3 months ago

**The official scaffolding tool for Stati - get a new static site up and running in under 2 minutes.**

0High
0Medium
0Low

imrecsige

create-stati

The official scaffolding tool for Stati - get a new static site up and running in under 2 minutes.

Create a production-ready Stati site with your choice of template and styling, complete with sensible defaults and best practices built-in.

Quick Start

Create a new Stati site with a single command:

npx create-stati

The interactive wizard will guide you through:

Project name - What to call your site
Template - Starting point (currently: blank)
CSS solution - Plain CSS, Sass, or Tailwind
Git initialization - Optional repository setup

In less than 2 minutes, you'll have a complete static site ready to customize.

Non-Interactive Mode

Skip the prompts and create a site with specific options:

npx create-stati my-site --template=blank --styling=tailwind --git

Available flags:

--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

Examples:

# Plain CSS (Git initialized by default)
npx create-stati my-blog --styling=css

# TypeScript with Tailwind
npx create-stati my-app --typescript --styling=tailwind

# Tailwind without Git and skip install
npx create-stati my-portfolio --styling=tailwind --no-git --no-install

# Sass with pnpm as package manager
npx create-stati my-docs --styling=sass --package-manager=pnpm

# Full control with all options
npx create-stati my-site --typescript --styling=tailwind --no-git --no-install --package-manager=yarn

Note: In non-interactive mode (when using CLI flags), dependencies are installed by default using npm. Use --package-manager to specify a different package manager (yarn, pnpm, or bun).

Interactive Setup

When you run npx create-stati, you'll see a friendly wizard:

? Project name: my-site
? Choose a template: Blank
? Which CSS solution would you like? (Use arrow keys)
  > Plain CSS (recommended for beginners)
    Sass/SCSS
    Tailwind CSS
? Enable TypeScript support? (y/N)
? Initialize a git repository? (Y/n)
? Install dependencies? (Y/n)
? Which package manager would you like to use? (Use arrow keys)
  > npm
    yarn
    pnpm
    bun

Each choice is explained, so you can make the right decision for your project.

Note: The package manager prompt only appears if you choose to install dependencies and multiple package managers are detected on your system.

TypeScript Support

When TypeScript is enabled (via --typescript flag or interactive prompt), your project will include:

stati.config.ts - TypeScript configuration file with full type safety
tsconfig.json - TypeScript compiler configuration optimized for browser targets
src/main.ts - Entry point for your TypeScript code
typecheck script - Run npm run typecheck to validate your TypeScript

How It Works

Stati uses esbuild for lightning-fast TypeScript compilation:

Development mode (stati dev): Stable filenames, source maps enabled, no minification
Production mode (stati build): Hashed filenames for cache busting, minified output

Your compiled JavaScript bundle is automatically injected into your HTML output before the closing </body> tag. No template modifications needed!

The bundle path is also available via stati.assets.bundlePath for advanced use cases like preloading:

<head>
  <% if (stati.assets?.bundlePath) { %>
  <link rel="modulepreload" href="<%= stati.assets.bundlePath %>">
  <% } %>
</head>

The Blank Template

A minimal, flexible starting point for any type of Stati site.

What You Get

Features:

Clean, minimal layout with no opinionated styling
Basic page structure with welcome content and clear instructions
Responsive design foundation ready to customize
Extensible architecture for any project type
Just the essentials - build on your own terms

File Structure (Plain CSS):

my-site/
├── site/
│   ├── index.md          # Homepage with welcome content
│   └── layout.eta        # Main HTML layout template
├── public/
│   ├── styles.css        # Basic CSS styles
│   └── favicon.svg       # Default favicon
├── stati.config.js       # Stati configuration
└── package.json          # Project dependencies

File Structure (Sass):

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

File Structure (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

What's Included:

Homepage (site/index.md) - Welcome page with getting started instructions
Layout (site/layout.eta) - HTML5 boilerplate with responsive meta tags
Styles - CSS in public/ (plain CSS) or src/ (Sass/Tailwind)
Configuration (stati.config.js) - Pre-configured with sensible defaults
Favicon (public/favicon.svg) - Simple SVG favicon ready to customize

Perfect For

Personal websites and portfolios
Landing pages and marketing sites
Learning Stati fundamentals
Any project where you want full control

Getting Started with Blank

The homepage provides clear next steps
Edit site/index.md to add your content
Customize site/layout.eta for your HTML structure
Update your styles (in public/ for plain CSS, src/ for Sass/Tailwind)
Configure site metadata in stati.config.js

CSS Options

Choose the styling approach that fits your workflow.

Plain CSS (Recommended for Beginners)

Simple and straightforward
No build step required
Full control over every style
Great for learning
Styles location: public/styles.css

Sass/SCSS

CSS with superpowers (variables, nesting, mixins)
Compiles to standard CSS
Popular and well-supported
Styles location: src/styles.scss → compiles to dist/styles.css

Tailwind CSS

Utility-first framework
Rapid prototyping
Built-in design system
Automatic purging for production
Styles location: src/styles.css → compiles to dist/styles.css

After Creation

Once your site is created, follow these steps:

1. Install Dependencies (if needed)

If you chose to install dependencies during scaffolding, you can skip this step. Otherwise, navigate to your project directory and install dependencies with your preferred package manager:

cd my-site

# Using npm
npm install

# Using yarn
yarn install

# Using pnpm
pnpm install

# Using bun
bun install

2. Start Development

npm run dev

Your site will be live at http://localhost:3000 with hot reload.

3. Build for Production

npm run build

Static files will be generated in the dist/ directory.

4. Preview Production Build

npm run preview

Test your production build at http://localhost:4000.

Project Structure

All Stati sites follow this conventional structure:

my-site/
├── site/             # Your content and templates
│   ├── *.md          # Markdown pages
│   ├── *.eta         # Eta templates
│   └── _partials/    # Reusable template parts (optional)
├── public/           # Static assets (CSS, images, fonts)
├── stati.config.js   # Stati configuration
├── package.json      # Project metadata and scripts
└── dist/             # Built site (generated on build)

How it works:

site/ - All your content lives here. Markdown files become pages.
public/ - Static assets copied as-is to your build.
stati.config.js - Configure your site's behavior.
dist/ - Your built static site, ready to deploy.

Next Steps

Learn Stati

Documentation - Complete guides and tutorials
Core Concepts - Templates, routing, and markdown
Configuration - Site config, ISG, and hooks
Examples - Real-world recipes

Customize Your Site

Modify layouts and styles to match your brand
Add new pages in the site/ directory
Create reusable partials in site/_partials/
Configure SEO, sitemap, and robots.txt

Deploy

Build your site and deploy to any static hosting:

Netlify - Drag and drop dist/ or connect Git
Vercel - Import your repository
GitHub Pages - Push dist/ to gh-pages branch
Any static host - Just upload the dist/ folder

Configuration Example

Each template comes with a pre-configured stati.config.js optimized for that use case:

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

export default defineConfig({
  site: {
    title: 'My Stati Site',
    baseUrl: 'https://example.com',
    defaultLocale: 'en-US',
  },
  srcDir: 'site',
  outDir: 'dist',
  staticDir: 'public',
});

You can customize this file to add features like SEO, sitemap, ISG caching, and more. See the Configuration Guide for all options.

Requirements

Node.js >=22
npm 11.5.1 or higher (or yarn/pnpm equivalent)

Learn More

Full Documentation - Complete guides and tutorials
CLI Commands - All available commands
Core Concepts - How Stati works
Examples - Real-world projects and recipes

Support & Community

GitHub Issues - Report bugs or request features
Discussions - Ask questions, share ideas
Documentation - Comprehensive guides

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

create-stati

Quick Start

Non-Interactive Mode

Interactive Setup

TypeScript Support

How It Works

The Blank Template

What You Get

Perfect For

Getting Started with Blank

CSS Options

Plain CSS (Recommended for Beginners)

Sass/SCSS

Tailwind CSS

After Creation

1. Install Dependencies (if needed)

2. Start Development

3. Build for Production

4. Preview Production Build

Project Structure

Next Steps

Learn Stati

Customize Your Site

Deploy

Configuration Example

Requirements

Learn More

Support & Community

License