Build integration and contract updates

Pull frontend-owned declarations and embed the matching public fingerprint with Vite or Next.js.

The Frontend guide establishes installation, contract pull, and the first request. Use this page to connect that contract to your frontend build. The Typed Client module owns shared installation and provider setup.

Generate before building

From the frontend package root, while the backend is running:

bun run relkit client pull http://127.0.0.1:3000 --out .relkit/generated
bun run relkit client check http://127.0.0.1:3000 --out .relkit/generated

Both build helpers read .relkit/generated/client-manifest.json relative to the frontend project root. Pulling to another directory does not change that lookup. The optional root option selects a project root, not an arbitrary manifest filename. Keep the declarations in the frontend’s TypeScript include list; the build plugin embeds the fingerprint but does not load declarations or pull them.

Select your framework

Merge relkit() into your existing plugins. This example also adds the development proxy used by the Frontend guide; the plugin itself does not configure routing:

/** Adds the pulled fingerprint and a local same-origin proxy to an existing Vite React project. */
import { relkit } from "@relkit/client/build/vite";

export default {
  plugins: [relkit()],
  server: {
    host: "127.0.0.1",
    port: 5173,
    strictPort: true,
    proxy: {
      "/rpc": { target: "http://127.0.0.1:3000", ws: true },
      "/_relkit": { target: "http://127.0.0.1:3000" },
    },
  },
};

Reference: relkit.

Wrap your existing configuration with withRelkit. Keep its routes, rewrites, and other options inside that configuration. This example also forwards RPC and identity requests to the local backend; the helper itself only embeds the fingerprint and supports workspace-linked client resolution:

/** Embeds the pulled fingerprint and forwards local browser requests to the backend. */
import { withRelkit } from "@relkit/client/build/next";

export default withRelkit({
  /** Keeps RPC and identity requests on the frontend origin.
   * @returns Local forwarding rules; replace their destinations for production. */
  async rewrites() {
    return [
      { source: "/rpc/:path*", destination: "http://127.0.0.1:3000/rpc/:path*" },
      { source: "/_relkit/:path*", destination: "http://127.0.0.1:3000/_relkit/:path*" },
    ];
  },
});

Follow the Next.js tabs in the Frontend guide for TypeScript setup, the Client Component, and verification. Replace the local rewrite destinations with your backend’s server URL for production. Rewrites require a Next.js server; static exports need gateway routing or a public backend URL with credentialed CORS. Reference: withRelkit.

Coordinate updates

After changing backend routes or public resource policies, regenerate the backend, pull its current contract into the frontend, and typecheck the caller. Restart the frontend dev server after a pull; build plugins read the fingerprint when configuration loads.

The React provider compares that compiled fingerprint with the server identity response. A mismatch produces application-updated and blocks new typed work. Update the deployed frontend and backend together. Do not clear pending-operation metadata or replay writes to get past a mismatch.

Use client check before the frontend’s production build. It checks compatibility without replacing the files. Production routing, credential handling, and stream proxy timeouts still belong to your host or gateway.

Reference and source