Introduction
Schema driven CSV and Excel ingestion for React and Node.js
IngestX is an open-source, schema driven data ingestion library crafted and maintained by Izanagi Labs. It provides a unified API to process CSV and Excel files across the browser (React) and the server (Node.js). Available as @izanagi-labs/ingestx on npm.
If you are building an application where users upload spreadsheet data and you need to reliably validate, parse, and ingest that data without crashing the browser or the server, IngestX is for you.
Why IngestX?
- Format Agnostic: Parse both CSV and Excel (
.xlsx,.xls) files through a single, unified pipeline. - Isomorphic: Runs identically in the browser (via Web Workers) and Node.js (via Streams/Filesystem), sharing the exact same schema declarations.
- Schema Validation: Configured via TypeScript. Rows are validated against your schema, separating valid and invalid outputs.
- Chunked Processing: Employs chunk based parsing and web workers in the browser to reduce main UI thread blocking.
- Incremental Processing: CSV files are evaluated incrementally in chunks. (You can separately configure
collectResults: falseto prevent processed rows from accumulating in memory).
How it Works
IngestX is built on three core concepts:
- Columns & Schemas: You define the expected structure of the incoming data using the
ixschema builder. - Parsers: Depending on the file format (CSV or Excel) and environment (Browser or Node), IngestX initializes the correct parser to read chunks of raw data.
- Ingestion Controller: The controller manages validation, lifecycle, and progress reporting, returning results to you incrementally or in a final collection.
What IngestX is Not
- Not a UI Library: IngestX is headless. It does not provide file upload buttons or data grids. You own your UI.
- Not an ORM: It validates input data and returns structured JavaScript objects; it does not write directly to your database.