Project Structure

A Streak.js project has the following folder layout:

my-streak-site/
  src/
    handlers/       ← data handlers (one per page), plus optional
                       Middleware.ts and CommonHandler.ts
    layouts/        ← layout components (full HTML document)
    widgets/        ← widget components (page sections)
  public/
    assets/         ← JS/CSS files served as static files
    styles/         ← compiled Tailwind CSS
  out/              ← build output (created by `streak-forge build`)
  streak.sitemap.json
  tsconfig.json
  package.json

src/handlers/

Data handlers are async functions that supply the data rendered into each page. Each page in the sitemap references one handler by filename (without extension).

src/handlers/HomeDataHandler.ts   ← referenced as "dataHandler": "HomeDataHandler"

Two filenames in this directory are reserved and auto-discovered if present, rather than referenced from the sitemap:

• Middleware.ts — runs first on every page resolution and can override which render config is used for a URL
• CommonHandler.ts — shared data, fetched once and passed into every page's data handler as { common }

Neither file is required.

src/layouts/

Layouts are TSX components that return the full HTML document. Each layout uses WidgetPlaceholder components from streak-forge/components to mark where widgets are inserted.

src/layouts/MainLayout.tsx   ← referenced as "rootLayout": "MainLayout"

src/widgets/

Widgets are TSX components rendered per page. Each widget filename must exactly match the type field in the sitemap (case-sensitive).

src/widgets/HelloBanner.tsx    ← referenced as "type": "HelloBanner"
src/widgets/HelloMessage.tsx   ← referenced as "type": "HelloMessage"

public/assets/

JavaScript and other files placed here are served as static files under /assets/ and can be loaded at runtime via gDom.loadPackage("js/motion.js"), which prepends /assets/ when fetching — so a file at public/assets/js/motion.js is fetched as /assets/js/motion.js.

out/

The build output directory, written by streak-forge build. Each sitemap entry produces a JSON snapshot at out/<url>/<version>/raw-content.json:

out/
  1.0.0/
    raw-content.json        ← page at url "/"
  page-2/
    1.0.0/
      raw-content.json      ← page at url "/page-2"

Note:streak-forge pre-build writes to a separate .prebuild/ cache directory — it does not produce out/.

streak.sitemap.json

The single configuration file that defines every page in the site. It declares each page's URL, renderId, data handler, layout, and widget list.

TypeScript Path Aliases

Projects use "baseUrl": "src/" in tsconfig.json, so imports resolve from src/:

import { getHomePageContents } from "services/SanityServices"; // src/services/SanityServices
import Button from "@common/components/button/Button";         // src/common/components/...
import { baseUrl } from "utils/config";                        // src/utils/config

The streak-forge/components import resolves from node_modules/streak-forge.