Serialization, Hydration, and Shipping Indexes

Build indexes ahead of time and ship their gzipped serialized state to the browser when you want local search without client-side reindexing.

That avoids reindexing large corpora on every page load.

The basic idea

At build time:

1. create your DocumentIndex
2. index your documents once
3. serialize indexState to gzipped bytes

At runtime:

1. fetch or import the compressed payload
2. create an empty index with the same field layout
3. call loadState(...)

Why this pattern works well

It is a good fit for:

• static sites
• documentation portals
• browser apps with bundled content
• offline-capable local search

It trades extra build-time work for a faster runtime experience.

What to serialize

Usually you want:

• the index state
• a lightweight source-document map for rendering results
• optionally extra payloads such as vector embeddings or chunk metadata

Keep retrieval data and rendering data conceptually separate, even if they ship together.

Browser tradeoffs

Prebuilt indexes make startup faster, but payload size still matters. To keep things practical:

• avoid indexing unnecessary fields
• use helper fields deliberately
• split large payloads if your app can lazy-load them

Keep field definitions aligned

Hydration only works correctly when the runtime index is created with the same logical field layout used at build time.

If you change the schema, rebuild and reship the state.

A common architecture

• build docs or records in CI
• emit compressed index assets during the site build
• load the serialized state in the browser
• run queries locally with no backend dependency

This pattern keeps runtime logic small, removes client-side indexing work, and gives you a predictable startup cost tied to payload size instead of indexing time.