Importer quickstart · beta

Ship a recoverable import workflow.

Local mode processes records in the browser and calls your application with accepted batches. Optional Cloud v2 loads a published schema and relays batches to an approved destination.

Read the full guide Try the local demo

Package availability

Preview · npm release pending

@diakrio/importer-react

This scoped package has no verified public npm release as of 2026-09-18. You can try the locally built runtime on this site while the release is prepared.

Free for personal and commercial application use. License and notices.

These examples target the published importer beta. Your app needs React and React DOM (18.3 or 19), Phosphor icons, Kumo styles, and the importer styles. Declare the contracts and Kumo packages directly when importing their types or styles.

1. Render locally

Supply your schema and an idempotent saveRecords handler. The Local importer makes no Cloud data request.

tsx

import { Importer } from "@diakrio/importer-react";
import { z } from "zod";
import "@cloudflare/kumo/styles/standalone";
import "@diakrio/importer-react/styles.css";

const contactSchema = z.object({
  email: z.email().meta({ title: "Email" }),
  name: z.string().min(1).meta({ title: "Name" }),
  tags: z.array(z.string()).default([]),
});

<Importer
  mode="local"
  schema={contactSchema}
  onBatch={async (records, context) => {
    // Your handler must deduplicate context.batchId.
    await saveRecords(records, context.batchId);
  }}
/>

2. Connect Cloud v2 sessions

Your backend authorizes the user and mints or renews their session. A publishable key alone cannot enable API mode. Hosted activation remains in private beta.

tsx

<Importer
  mode="api"
  publishableKey={process.env.NEXT_PUBLIC_CB_KEY!}
  getSession={async ({ sessionId, signal }) => {
    // Your authenticated backend authorizes the user and session ownership.
    const response = await fetch('/api/import-session', {
      method: 'POST', signal, credentials: 'same-origin',
      headers: { 'content-type': 'application/json' },
      body: JSON.stringify({ sessionId }),
    });
    if (!response.ok) throw new Error('Import authorization failed');
    return response.json();
  }}
/>

Set up the backend exchange

Loading page…

1. Render locally

Supply your schema and an idempotent saveRecords handler. The Local importer makes no Cloud data request.

tsx

import { Importer } from "@diakrio/importer-react";
import { z } from "zod";
import "@cloudflare/kumo/styles/standalone";
import "@diakrio/importer-react/styles.css";

const contactSchema = z.object({
  email: z.email().meta({ title: "Email" }),
  name: z.string().min(1).meta({ title: "Name" }),
  tags: z.array(z.string()).default([]),
});

<Importer
  mode="local"
  schema={contactSchema}
  onBatch={async (records, context) => {
    // Your handler must deduplicate context.batchId.
    await saveRecords(records, context.batchId);
  }}
/>

2. Connect Cloud v2 sessions

Your backend authorizes the user and mints or renews their session. A publishable key alone cannot enable API mode. Hosted activation remains in private beta.

tsx

<Importer
  mode="api"
  publishableKey={process.env.NEXT_PUBLIC_CB_KEY!}
  getSession={async ({ sessionId, signal }) => {
    // Your authenticated backend authorizes the user and session ownership.
    const response = await fetch('/api/import-session', {
      method: 'POST', signal, credentials: 'same-origin',
      headers: { 'content-type': 'application/json' },
      body: JSON.stringify({ sessionId }),
    });
    if (!response.ok) throw new Error('Import authorization failed');
    return response.json();
  }}
/>

Set up the backend exchange