Framework guide

Add a CSV and Excel importer to React

Bootstrapware Importer is a React component for SaaS products that need customer spreadsheet upload. It handles CSV, Excel (XLSX), and TSV in the browser: column mapping, typed validation, preview, duplicate detection, and failed-row export. Your app receives normalized objects through onComplete. File contents are not uploaded to Bootstrapware.

This page is the framework-agnostic React path. If you use Next.js, Vite, or Remix, prefer those guides for env vars and server route shapes, then come back here for the component contract.

Install

pnpm add @bootstrapware/importer
npm install @bootstrapware/importer

Import @bootstrapware/importer/styles.css once near the feature (or in your global CSS entry).

Local schema embed

Pass fields in props. Good for development and for apps that keep schema in source control.

import { Importer } from "@bootstrapware/importer";
import "@bootstrapware/importer/styles.css";

export function ContactsImport() {
  return (
    <Importer
      title="Import contacts"
      fields={[
        { key: "email", label: "Email", type: "email", required: true },
        { key: "name", label: "Name", type: "string", required: true },
        { key: "company", label: "Company", type: "string" },
      ]}
      duplicateKey="email"
      onComplete={async (rows, meta) => {
        const res = await fetch("/api/contacts/import", {
          method: "POST",
          headers: { "Content-Type": "application/json" },
          body: JSON.stringify({ rows, meta }),
        });
        if (!res.ok) throw new Error("Import failed");
      }}
    />
  );
}

Supported field types: string, number, date, email, enum (requires enumValues), boolean, url. See fields and validation.

Hosted configuration

Publish a revision in the dashboard, then pass importerId and a publishable key (bsw_live_pub_ or bsw_test_pub_). Secret keys never belong in client bundles.

<Importer
  importerId="imp_..."
  publishableKey="bsw_live_pub_..."
  onComplete={(rows) => {
    void fetch("/api/contacts/import", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({ rows }),
    });
  }}
/>

Optional apiBaseUrl defaults to the Bootstrapware Importer API. Origins must allow your app origin when the browser fetches published config. See origins.

Your API owns persistence

Treat onComplete like any other trusted-looking client payload: authenticate, authorize, re-validate, then write. Invalid rows never reach onComplete; customers can fix them in preview or download import-errors.csv.

Where to put the component

Place it on an authenticated settings or data page: “Import contacts,” “Import catalog,” “Bulk add users.” Keep it behind your own auth UI. The package does not replace login.

Pitfalls

  • Missing stylesheet import
  • Expecting Bootstrapware to store or receive row payloads
  • Shipping a secret key to the browser
  • Skipping server-side validation before inserts

Related: React component props · Next.js · Vite · Remix · Live demo