Drift Static Framework Overview
Drift Static combines an AOT compiler, headless server virtual machine (DriftServerVM), and Vite bundler to produce production-ready static sites.
The Build Pipeline
When you run drift-ssg build (or invoke build() programmatically), the framework executes eight discrete phases:
1. Configuration Loading
├── Resolves drift.config.js / ts
└── Merges defaults (pagesDir, outDir, site, base, head)
│
▼
2. Route Discovery (scanRoutes)
├── Scans pages directory for .drift and .md files
└── Builds hierarchical layout chains (_layout.drift)
│
▼
3. Path Resolution (resolveAllRoutePaths)
├── Resolves static routes (index, about, etc.)
└── Calls getStaticPaths() on dynamic routes ([slug], [...slug])
│
▼
4. Island & Style Discovery
├── Scans templates for elements with client:* directives
└── Extracts CSS import specifiers from <script> blocks
│
▼
5. Island & CSS Bundling (bundleIslands via Vite)
├── Emits minified island entry points (islands-[hash].js)
└── Compiles and hashes site styles (styles-[hash].css)
│
▼
6. Page Pre-Rendering (renderPage)
├── Executes DriftServerVM for each concrete path
├── Composes nested layout hierarchy
└── Injects head metadata and island script tags only where needed
│
▼
7. Static Asset Copying
└── Copies public/ directory files directly to outDir
│
▼
8. SEO Generation
├── Emits sitemap.xml with canonical site URLs
└── Emits robots.txt
Zero-JS by Default
In traditional SSR frameworks (Next.js, Nuxt), even a completely static page ships hundreds of kilobytes of runtime JavaScript to re-hydrate the DOM on the client.
In Drift Static:
- If a page contains no interactive islands, 0 script tags are injected into the HTML.
- The page loads with instantaneous First Contentful Paint (FCP) and optimal Lighthouse scores.
- Interactive islands bundle only their own component dependencies and the lightweight
hydrateIslands()runtime.
Development Server
Start the dev server with on-demand SSG and instant Hot Module Replacement:
drift-ssg dev --port 3000
When you edit .drift components or .md files, the server invalidates modules and updates your browser immediately.