Sitemap

streak.sitemap.json is the single entry point for the entire build. Every page, its layout, its data source, and its widget list is declared here.

File Location

streak.sitemap.json   ← project root

Full Example

[
  {
    "url": "/",
    "renderConfig": {
      "renderId": "homeRenderId",
      "metadata": {},
      "dataHandler": "HomeDataHandler",
      "rootLayout": "MainLayout",
      "widgets": [
        { "id": "PageHead",     "type": "PageHead" },
        { "id": "HelloBanner",  "type": "HelloBanner" },
        { "id": "HelloMessage", "type": "HelloMessage", "loadingStrategy": "lazy" }
      ],
      "version": "1.0.0"
    }
  }
]

Field Reference

Top-level page entry

Field	Type	Meaning
`url`	string	The URL path for this page
`renderConfig`	object	All rendering configuration for this page

renderConfig fields

Field	Type	Meaning
`renderId`	string	Unique ID for this render config
`metadata`	object	Arbitrary bag passed through to the page's data handler as its first argument
`dataHandler`	string	Filename (without extension) in `src/handlers/`
`rootLayout`	string	Filename (without extension) in `src/layouts/`
`widgets[]`	array	Ordered list of widgets to place on this page
`version`	string	Version string; forms part of this entry's output path (`out/<url>/<version>/raw-content.json`)

Field	Type	Meaning
`id`	string	Any string identifying this widget slot. Must match `WidgetPlaceholder id=` in the layout and the handler return key. Unique within this page's `widgets[]`. Not required to equal `type`.
`type`	string	The widget name — must match the filename in `src/widgets/` (case-sensitive)
`loadingStrategy`	`"lazy"`	If set, widget JS assets are deferred until after page is interactive

id and type are separate: type picks the component file, id picks the data slice and the layout slot. Examples use the same value for both only for readability.

renderId Uniqueness

renderId must be globally unique across all sitemap entries. streak-forge build writes each entry's rendered output to a path based on its url and version:

out/<url>/<version>/raw-content.json

This file is an intermediate snapshot of the rendered page — not final HTML. Turning it into a deployable site is handled by Nexus; see the Nexus documentation.

If two entries share the same renderId, one will overwrite the other.

The widgets[] array is ordered. Widgets are rendered and injected in the order they appear. Each entry must have a corresponding WidgetPlaceholder in the layout whose id and type equal that entry's id and type.

Each id must be unique within the page. The same type may appear in multiple entries — this is how you place the same widget component in more than one spot on a page:

"widgets": [
  { "id": "featuredProducts", "type": "ProductList" },
  { "id": "newArrivals",      "type": "ProductList" }
]

Each instance renders the same file with its own props.data (keyed by id) at its own placeholder. Note: <Script> ids are deduplicated per page, so a widget type reused on one page must emit a distinct <Script id> per instance or only the first gets its client script. See WidgetPlaceholder.

loadingStrategy: "lazy"

When a widget entry includes "loadingStrategy": "lazy", the widget's HTML is still rendered at build time and included in the initial HTML. However, app.js defers loading the widget's JS assets until after the page is interactive. See Lazy Widgets for details.

Data Handler and Layout Resolution

dataHandler: "HomeDataHandler" → src/handlers/HomeDataHandler.ts
rootLayout: "MainLayout" → src/layouts/MainLayout.tsx
widgets[].type: "HelloBanner" → src/widgets/HelloBanner.tsx

All lookups are by filename without extension.

Multiple Pages

[
  {
    "url": "/",
    "renderConfig": {
      "renderId": "homeRenderId",
      "dataHandler": "HomeDataHandler",
      "rootLayout": "MainLayout",
      "widgets": [],
      "version": "1.0.0"
    }
  },
  {
    "url": "/about",
    "renderConfig": {
      "renderId": "aboutRenderId",
      "dataHandler": "AboutDataHandler",
      "rootLayout": "MainLayout",
      "widgets": [],
      "version": "1.0.0"
    }
  }
]

streak-forge build produces one out/<url>/<version>/raw-content.json file per entry — for example, the /about entry above writes out/about/1.0.0/raw-content.json.