Portable JSON Index State

Querylight index state is intentionally JSON-serializable, and the recommended serialization path is gzipped bytes.

This page covers the smallest possible version of the pattern: serialize indexState, ship it, and hydrate it again later. For the broader deployment pattern around browser apps and static sites, see Serialization, Hydration, and Shipping Indexes.

Serialize

import { serializeDocumentIndex } from "@tryformation/querylight-ts";

const compressed = serializeDocumentIndex({ index });

Hydrate

import { deserializeDocumentIndex } from "@tryformation/querylight-ts";

const hydrated = deserializeDocumentIndex({ index, compressed });

loadState(...) expects the same logical field layout you used when you built the index. If the runtime schema changes, rebuild and reship the JSON state.

When to use it

• Precompute indexes at build time
• Ship them to the browser
• Avoid reindexing on startup
• Keep test fixtures deterministic

This pattern is a good fit when:

• the source documents already exist at build time
• startup latency matters more than extra build-time work
• the serialized payload still fits comfortably in browser or process memory
• you want deterministic fixtures for tests or demos

This is the recommended architecture for documentation and static-site search:

1. Build your DocumentIndex or createSimpleTextSearchIndex(...) bundle during your site build.
2. Serialize the resulting index state to gzipped bytes.
3. Fetch that compressed payload in the browser.
4. Hydrate the index state.
5. Run search queries locally in the browser.

That pattern keeps the runtime simple, avoids client-side reindexing, and gives you predictable startup cost.

Learn more

• Getting Started with Browser Search
• JSON on Wikipedia
• RFC 8259: The JavaScript Object Notation (JSON) Data Interchange Format
• JSON.stringify() on MDN