@bootstrapware/importer

Embeddable CSV, Excel, and TSV importing for small production SaaS.

Parsing, mapping, and validation run in the browser. File contents, parsed rows, and filenames never leave the customer's machine. Bootstrapware is not in the data path. Your app receives normalized rows through onComplete and sends them to your own backend.

On the upload step, once fields are known, Download template.csv generates a client-side file from the local or hosted schema (label headers, falling back to keys; one type-derived example row).

pnpm add @bootstrapware/importer

Peer dependencies: react and react-dom (>= 18).

Local schema

Use this for development, evaluation, or when you want the schema in code.

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

<Importer
  fields={[
    { key: "email", label: "Email", type: "email", required: true, aliases: ["Email Address", "E-mail"] },
    { key: "name", label: "Name", type: "string", required: true },
    { key: "seats", label: "Seats", type: "number" },
  ]}
  duplicateKey="email"
  onComplete={(rows) => {
    // Send rows to YOUR backend. Not ours.
  }}
/>

Hosted configuration

Publishable keys may appear in the browser. Secret keys must stay server-side. File contents are still never uploaded.

<Importer
  importerId="imp_..."
  publishableKey="bsw_live_pub_..."
  onComplete={(rows) => {
    // rows go to your API
  }}
/>

Optional apiBaseUrl defaults to https://importer.bootstrapware.co.

Field types

string | number | date | email | enum | boolean | url

enum requires enumValues.

Optional aliases?: string[] helps auto-map common header variants (Email Address, E-mail, and so on).

Optional unique: true on a field rejects duplicate values for that field within the file. Component-level duplicateKey does the same for one chosen field.

Optional locale props:

<Importer
  fields={fields}
  dateOrder="DMY"       // slash/dash/dot dates as day/month/year
  numberLocale="eu"     // or "us" | "auto" (default)
  dir="rtl"
  onComplete={onComplete}
/>

Parsing notes

• Numbers accept US and European formats, currency symbols, percentages as fractions, and accounting negatives ($1,234.50, 1.234,56, 50% → 0.5, (500)). With numberLocale="eu" or semicolon-delimited auto, bare 1.234 is thousands.
• Common empty placeholders (N/A, -, null) are treated as blank.
• Emails like Ada <[email protected]> or mailto:[email protected] are normalized to [email protected].
• Booleans accept true/false, yes/no, y/n, 1/0, on/off.
• URLs accept http/https. Bare www.example.com is stored as https://www.example.com/.
• Mapped cells are trimmed and internal whitespace is collapsed (including Excel NBSP).
• CSV delimiter is auto-detected (,, ;, or |) from the leading non-empty rows, so a title line without separators does not force comma. Separators inside quoted cells are ignored. .tsv / .tab use tabs.
• Multi-sheet Excel workbooks show a sheet picker on the map step.
• Title or report rows above the real headers can be skipped: the map step shows a Header row picker (auto-detected from field keys, labels, and aliases). Column dropdowns include sample cell values from the file.
• dateOrder="DMY" parses 3/4/2024 as 4 March; default MDY is 3 April. Dotted dates (15.03.2024) and values with a day or month above 12 are unambiguous and parse without flipping dateOrder.

Security

• Do not put bsw_live_sec_ or bsw_test_sec_ in client code.
• Do not upload spreadsheet contents to Bootstrapware.
• onComplete is the data path to your application.

Docs

• Product: https://bootstrapware.co/importer
• Quickstart: https://bootstrapware.co/importer/docs/quickstart
• Agent rules (AGENTS.md): https://bootstrapware.co/importer/docs/agents

For coding agents, copy the packaged AGENTS.md into your repo rules, or point the agent at the docs URL above.

License

MIT