Skip to content
STACK IT FAST
Share

elekcsv

Maintainer verified
CommunityClassicHeadless CSV Ingestion EngineSolo

Shared by Kayra @kayra61b

Site GitHub

elek (npm scope @elekcsv) is a headless, locale-aware CSV import toolkit for TypeScript: a single core engine parses, validates and maps CSV columns, wrapped by dedicated React, Vue, Svelte, SolidJS, Preact and Angular packages.

Language
TypeScript
License
Apache-2.0
Running for
1 year
Team
Solo

Why this architecture

Keeping parsing, compiled-validator generation, fuzzy column mapping and bitmap error tracking in one dependency-free core package lets every UI framework reuse identical import logic instead of six separate implementations.

Tech stack by layer

14 technologies · audited Sep 17, 2026
Frontend & UI
  • ReactShips the `useCSVImporter` hook and a headless idle→mapping→review→complete state machine.
  • VueWraps the core engine in Vue composables for the same import pipeline.
  • SvelteWraps the core engine in Svelte stores.
  • SolidJSWraps the core engine in Solid signals.
  • PreactWraps the core engine in Preact hooks.
  • AngularWraps the core engine in an injectable Angular service built on signals.
  • AstroPowers apps/demo, which mounts all six framework adapters side by side for manual testing.
Data & Persistence
  • TypeScriptImplements the shared parse/validate/map pipeline (compiled validators, bitmap error tracking, fuzzy column matching) that every adapter wraps.
Infrastructure & Deploy
  • BunRuns the workspace test suite (`bun test`) and drives the multi-package dev/build scripts.
  • BiomeSingle lint/format tool for the whole monorepo (`biome check .`).
  • tsupBundles the core engine and every framework adapter to ESM + CJS with type declarations.
  • ChangesetsTracks per-package version bumps and drives `changeset publish` for the 7 published npm packages.
  • GitHub ActionsRuns the CI workflow and the npm publish workflow on push.
Tooling, Testing & Ops
  • Context7Ships a context7.json so AI coding assistants can index elek's docs directly instead of guessing at the API.
Agent rules for this stackAstro SSR + Tailwind CSS + CloudflareAGENTS.md · 39 lines · CLAUDE.md · 16 lines

elekcsv architecture diagram

Open SVG
elekcsv architecture diagramCSV file → Host app (select file); Host app → Framework adapters (useCSVImporter); Framework adapters → @elekcsv/core (state machine); @elekcsv/core → Column mapper (map headers); @elekcsv/core → Compiled validators (validate cells); @elekcsv/core → Locale parsers (dates · numbers); Compiled validators → Validated rows (results)CLIENTSSERVICESWORKERS & JOBSDATA & STORAGECSV fileuser uploadHost appReact · Vue · Svelte · AngularFramework adaptershooks · composables · stores@elekcsv/corezero framework depsColumn mapperexact · alias · fuzzy matchCompiled validatorsnew Function() · bitmapLocale parserstr · en · de · frValidated rows+ error bitmapselect filestate machineuseCSVImportermap headersvalidate cellsdates · numbersresults
How the main components of elekcsv connect, as described by its maintainers.
Diagram as text
  • CSV file (user upload) → Host app (React · Vue · Svelte · Angular): select file
  • Host app (React · Vue · Svelte · Angular) → Framework adapters (hooks · composables · stores): useCSVImporter
  • Framework adapters (hooks · composables · stores) → @elekcsv/core (zero framework deps): state machine
  • @elekcsv/core (zero framework deps) → Column mapper (exact · alias · fuzzy match): map headers
  • @elekcsv/core (zero framework deps) → Compiled validators (new Function() · bitmap): validate cells
  • @elekcsv/core (zero framework deps) → Locale parsers (tr · en · de · fr): dates · numbers
  • Compiled validators (new Function() · bitmap) → Validated rows (+ error bitmap): results

Key architectural decisions

6 decisions
  1. 01

    One core engine, six thin framework adapters

    packages/core has zero framework dependencies; packages/react, vue, svelte, solid, preact and angular each depend on @elekcsv/core and only add framework-idiomatic bindings (hooks, composables, stores, signals, a service), so parsing/validation logic is never duplicated per framework.

  2. 02

    Schemas compile to raw JS functions instead of running an interpreter per row

    Per docs/compiled-validation.md and the README, compileSchema() turns a declarative schema into a new Function()-generated validator so V8 can inline it, rather than walking a rule tree for every cell.

  3. 03

    Column mapping is a 3-tier matcher, not exact-header matching

    docs/column-mapping.md documents exact match, then alias match against a schema-declared aliases array, then Levenshtein fuzzy matching with a configurable threshold, used to map arbitrary CSV headers (e.g. "E-Posta Adresi") onto schema fields.

  4. 04

    Validation errors are tracked with a bitmap, not per-row error objects

    docs/validation-bitmap.md describes O(1) bitmap.hasError(row, col) lookups with lazy error message materialization, avoiding allocation of one error object per invalid cell on large imports.

  5. 05

    Locale handling is built into the core engine, not left to the caller

    docs/locale-support.md and the README show built-in date/number/currency/boolean parsing for tr, en, en-GB, de and fr locales, registered through registerLocale(), so consumers do not need a separate date-parsing library.

  6. 06

    Release automation via Changesets rather than manual version bumps

    The root package.json exposes changeset, version and release scripts backed by .changeset/config.json, and each of the 7 published packages sets publishConfig.access: public for its own npm release.

How elekcsv is built

How elek is structured

elek is a Bun-managed TypeScript monorepo declared in the root package.json workspaces (packages/*, apps/*). packages/core is the engine: CSV parsing, schema-driven validation, column mapping and locale handling, with no framework dependency. Six adapter packages — packages/react, packages/vue, packages/svelte, packages/solid, packages/preact and packages/angular — each depend on @elekcsv/core (^1.1.1, per their package.json files) and add only framework-idiomatic bindings on top. apps/demo is an Astro app that pulls in all seven packages plus Tailwind CSS to exercise every adapter in one place, and benchmarks/ holds standalone scripts (parse-comparison.ts, validation-benchmark.ts, etc.) that compare the engine against PapaParse and csv-parse.

Frontend

The six adapters are deliberately thin. Each has its own package.json with a peerDependencies entry pinning the minimum supported framework version (e.g. react: >=18, vue: >=3, svelte: >=3, solid-js: >=1, preact: >=10, @angular/core: >=16) and re-exports the same underlying pipeline through hooks (React, Preact), composables (Vue), stores (Svelte), signals (SolidJS), or an injectable service (Angular). apps/demo/package.json depends on @astrojs/react, @astrojs/vue, @astrojs/svelte, @astrojs/solid-js and @astrojs/preact simultaneously, confirming the demo app is built specifically to run all adapters side by side rather than showcasing just one.

Build, test & deploy

bun test (root script) runs the test suite; .github/workflows/ci.yml runs it on push per the workflows list in the repo. Each package builds independently with tsup (build/dev scripts in every packages/*/package.json), emitting dist/index.js (ESM), dist/index.cjs (CJS) and .d.ts types per the shared exports map. biome.json at the root is the single lint/format source for the whole repo (biome check ., biome format --write .). Releases go through Changesets: .changeset/config.json plus the root changeset, version and release scripts (bun run build && changeset publish) drive independent npm releases for the 7 packages, each with publishConfig.access: public pointing at the public npm registry. A second workflow, publish.yml, exists alongside ci.yml in .github/workflows for that release step.

What to copy (and what not to)

The core-plus-thin-adapters split is the reusable idea: put every bit of business logic (parsing, validation, mapping, locale rules) in one framework-agnostic package, and let per-framework packages be nothing more than a hook/store/service that calls it. That keeps behavior identical across React, Vue, Svelte, SolidJS, Preact and Angular consumers, and it is straightforward to replicate for any data-processing library that needs multi-framework bindings. The compiled-validator approach (schemas → new Function()) and the bitmap error tracker are the two most copy-worthy internals if the goal is raw throughput on large client-side datasets; both are documented in docs/compiled-validation.md and docs/validation-bitmap.md rather than left as unexplained optimizations. What is more specific to this project's scale is the 7-package publish pipeline (Changesets + tsup + Biome across a Bun workspace) — appropriate for a small, single-maintainer library, but more coordination than most teams need if they are not shipping several public npm packages from one repo.

Sources & repo audit

Edited
Sep 29, 2026
Audited
Sep 17, 2026
Commit
6f2c630
License
Apache-2.0

Maintained by the project's owner. It started from our independent analysis of github.com/k61b/elekcsv (Sep 17, 2026).

Show this stack on your README or website
Tech stack of elekcsv
[![Tech stack of elekcsv on STACK IT FAST](https://stackitfast.com/badge/elekcsv.svg)](https://stackitfast.com/project/elekcsv)

Paste it into your README. It shows your current stack and links to this page.
Use this stack

Scaffold it with your agent

Paste this prompt into Claude Code, Cursor, Windsurf or AGY to start a project with elekcsv's architecture.

  1. 1Copy the promptThe full markdown spec, with every layer and decision.
  2. 2Open your AI toolClaude Code, Cursor, Windsurf or Copilot, in a new repo.
  3. 3Paste and scaffoldUse it as the first instruction; review before you ship.
use-this-stack.md · 8 lines · 0.6 KB
# Use the elekcsv Architecture Stack

Project Type: Headless CSV Ingestion Engine · Scale: Solo
Tech Stack: TypeScript, Bun, React, Vue, Svelte, SolidJS, Preact, Angular, Astro, Biome, tsup, Changesets, GitHub Actions, Context7

Rationale: Keeping parsing, compiled-validator generation, fuzzy column mapping and bitmap error tracking in one dependency-free core package lets every UI framework reuse identical import logic instead of six separate implementations.

Task: Scaffold a modern production-ready repository utilizing this exact architecture. Follow identical package boundaries and migration patterns.
Scaffolded something with this prompt?
Would you pick this stack for a headless csv ingestion engine project?

Copied 12 times · 5 of 5 reported launches succeeded (100%)

Frequently asked about elekcsv

What is elek (elekcsv) built with?

elek is a Bun-managed TypeScript workspace: a framework-free core engine (packages/core) plus six thin adapter packages for React, Vue, Svelte, SolidJS, Preact and Angular, built with tsup, linted with Biome, and released with Changesets.

Does elek need a backend or server?

No. Parsing, validation and column mapping all run client-side (or in any JS runtime) inside the core engine; there is no server component in this repository, only a library and an Astro demo app that runs the adapters in the browser.

Which frontend frameworks does elek support?

React, Vue, Svelte, SolidJS, Preact and Angular each have a dedicated npm package (@elekcsv/react, @elekcsv/vue, etc.) that wraps the same @elekcsv/core engine with framework-idiomatic bindings.

How does elek handle large CSV files without freezing the browser?

It compiles validation schemas into optimized functions and tracks errors with a bitmap for O(1) lookups instead of allocating one error object per invalid cell, which docs/performance.md and docs/validation-bitmap.md describe as the mechanism for handling large imports without excessive garbage collection.

One email a month: new deep dives and stack trends

New source-audited architectures, head-to-head comparisons and the monthly stack report. No spam, unsubscribe anytime.

Similar architectures

use-this-stack.md