@zonekit/config

Manifest fetching and resolved-config assembly for Zonekit.

Use @zonekit/config when you already have config artifacts or manifests somewhere and need to turn them into a ResolvedConfig in a browser, Node service, or shell bootstrap path. This package fetches manifests, applies feature flags, builds resolved config, caches results, and can poll a version endpoint for refreshes.

If you need an HTTP server that exposes /resolve, /preview, or /version, use @zonekit/config-server.

Installation

pnpm add @zonekit/config

Quick start

import {
  createConfigRefresher,
  createConfigResolver,
  createManifestFetcher,
  createPreviewResolver,
} from "@zonekit/config";

const fetcher = createManifestFetcher({
  primaryBaseUrl: "https://cdn.example.com/manifests",
  buildPath: (dimensions) =>
    dimensions.map((dimension) => `${dimension.name}/${dimension.value}`).join("/") +
    "/manifest.json",
});

const resolver = createConfigResolver({
  fetcher,
  dimensions: [
    { name: "tenant", value: "acme" },
    { name: "region", value: "us-east" },
  ],
  flagProvider: {
    getFlags: async () => ({ "new-dashboard": true }),
  },
});

const resolvedConfig = await resolver.resolve();

const refresher = createConfigRefresher({
  versionUrl: "https://config.example.com/version",
  resolver,
  pollingIntervalMs: 30_000,
  onRefresh: (nextConfig) => {
    console.log("Config refreshed", nextConfig.configVersion);
  },
});

const previewResolver = createPreviewResolver(fetcher, {
  getFlags: async () => ({ "new-dashboard": true }),
});

const preview = await previewResolver.preview(
  [{ name: "tenant", value: "acme" }],
  { "new-dashboard": false },
);

void resolvedConfig;
void refresher;
void preview;

Recommended usage

1. Use createManifestFetcher() to describe where manifests live.
2. Use createConfigResolver() to build and cache a ResolvedConfig.
3. Add createConfigRefresher() if clients need polling-based refresh.
4. Add createPreviewResolver() when you need draft or flag-override previews.

Key exports

Resolution flow

• createManifestFetcher(options) to fetch manifests from a CDN or config endpoint, with optional fallback behavior.
• createConfigResolver(options) to resolve, cache, and invalidate ResolvedConfig.
• createConfigRefresher(options) to poll a version endpoint and re-resolve on change.
• createPreviewResolver(fetcher, flagProvider) to preview config with flag overrides and no cache reuse.

Validation

• validateManifest(manifest) for manifest-level validation.
• validateResolvedConfig(config) for resolved-config validation.
• validateFlagSubtractOnly(manifestRoutes, resolvedRoutes) to assert flags only subtract routes.

Errors

• FlagViolationError when flagged routing produces an invalid surface.
• SchemaVersionMismatchError when fetched config has an incompatible schema version.

Notes

• resolve() caches results. Use ttl for expiry or invalidate() after a version change.
• fallbackFetcher on the resolver is the last-resort path if the primary fetcher fails.
• createConfigRefresher() expects a version endpoint that returns a version field.
• This package is SSR-safe. Inject your own fetch implementation when you are not using globalThis.fetch.

License

MIT

Read more:

• Config plane overview
• Config resolver docs
• @zonekit/config package docs