Installation

Install Deno

Dune runs on Deno 2.x. If you don't have it yet:

# macOS / Linux
curl -fsSL https://deno.land/install.sh | sh

# Windows (PowerShell)
irm https://deno.land/install.ps1 | iex

# Homebrew
brew install deno

Verify your installation:

deno --version
# deno 2.x.x

Create a new site

dune new my-site
cd my-site

This scaffolds a minimal Dune site:

my-site/
├── dune.config.ts          # Site configuration (programmatic)
├── content/                # Your content lives here
│   └── 01.home/
│       └── default.md      # Your homepage
├── config/
│   ├── site.yaml           # Site identity (title, URL, taxonomies)
│   └── system.yaml         # Engine behavior (cache, debug, languages)
└── themes/
    └── starter/            # Starter theme
        ├── templates/
        │   └── default.tsx
        ├── components/
        │   └── layout.tsx
        ├── islands/        # Preact islands (hydrated in the browser)
        │   └── NavToggle.tsx
        └── theme.yaml

Start the dev server

dune dev

Open http://localhost:3000. You should see your homepage.

The dev server watches for changes — edit content/01.home/default.md and your browser will refresh automatically.

What just happened?

  1. Dune scanned the content/ directory and built a content index — a lightweight map of every page, its route, and its frontmatter
  2. It loaded config/site.yaml and config/system.yaml, merging them with defaults
  3. It started a Fresh 2 server. GET requests for content pages are routed through Fresh's ctx.render(), which handles the response and injects Fresh's client bootstrap script into every HTML page — enabling island hydration once you add interactive components
  4. When you visited /, Dune found 01.home/default.md, loaded its Markdown, rendered it to HTML, passed it to your theme's default.tsx template, and returned the result via Fresh

Troubleshooting

Template changes not appearing after server restart

Deno caches compiled .tsx files on disk. In rare cases the cached version survives a server restart and serves stale output. Force a clean compile with:

DENO_DIR=$(mktemp -d) dune dev

This uses a fresh Deno compile cache for the session. You can safely delete the stale cache manually from ~/Library/Caches/deno/gen/ (macOS) or ~/.cache/deno/gen/ (Linux) if you prefer a permanent fix.