Core Concepts 5 min read

File-Based Routing & Data Hooks

Learn how Staticraft maps files to HTTP paths, fetches dynamic data via server.js hooks, manages background revalidation timers, and statically pre-renders dynamic SSG routes.

1. File-Based Route Mapping

Staticraft uses filesystem conventions to discover pages. Any `page.html` located under `src/app/` automatically establishes a route pattern:

Code Reference Staticraft

src/app/page.html               -> /
src/app/about/page.html         -> /about
src/app/blog/page.html          -> /blog
src/app/blog/[slug]/page.html    -> /blog/:slug

2. Colocated server.js Data Hook

To attach dynamic data to a page, place a `server.js` file next to `page.html`. Export a default object containing a `data()` async function.

Code Reference Staticraft

// src/app/page.js
export default {
    revalidate: 600,
    data: async () => {
        const response = await fetch("https://api.example.com/stats");
        const stats = await response.json();
        return {
            title: "Dashboard Overview",
            stats
        };
    }
};

3. Background Revalidation Timers

The `revalidate` property specifies how often Staticraft ScheduleManager re-fetches data and re-renders the page in the background. - `revalidate: 60` -> Refresh every 1 minute - `revalidate: 3600` -> Refresh every 1 hour - Unspecified / omitted -> Permanent static page (rendered once)

Code Reference Staticraft

export default {
    revalidate: 300 // Re-renders in background every 5 minutes
};

4. Dynamic SSG Routes with generatePaths()

For dynamic routes like `src/app/blog/[slug]/page.html`, export `generatePaths()` from `server.js`. This returns an array of param objects and associated page data to pre-render every page statically.

Code Reference Staticraft

// src/app/blog/[slug]/server.js
export default {
    revalidate: 1800,
    generatePaths: async () => [
        {
            params: { slug: "welcome-to-staticraft" },
            data: { title: "Welcome to Staticraft", author: "Abhay Vachhani" }
        },
        {
            params: { slug: "zero-port-architecture" },
            data: { title: "Zero-Port Architecture", author: "Abhay Vachhani" }
        }
    ]
};

← Previous Guide

Getting Started with Staticraft

‹ All Documentation Guides