Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 5 additions & 0 deletions .changeset/beta-wording.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
---
"react-data-export": patch
---

README: the 1.0 feature set is complete; until 1.0.0, changes are limited to fixes found in testing. A Web Worker option comes in a 1.x release.
5 changes: 5 additions & 0 deletions .changeset/javascript-excel-beta-0.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
---
"react-data-export": patch
---

Depend on javascript-excel `^2.0.0-beta.0`, its first 2.0.0 beta. Since 2.0.0-alpha.7 its writer returns to the event loop about every 16 ms, so a large `.xlsx` export on the main thread no longer freezes the page, and `signal`/`abort()` take effect while it runs.
3 changes: 2 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,8 @@ Export data from React to `.xlsx` and `.csv`.
## Status: 1.0 is a from-scratch rewrite, in progress

- **1.0 has a new API.** It is rebuilt on [javascript-excel](https://github.com/securedeveloper/javascript-excel) 2.0, and its main entry has no `<ExcelFile>` / `<ExcelSheet>` / `<ExcelColumn>`. The 0.6 API ships only as the deprecated `react-data-export/legacy` entry: supported for all of 1.x, removed in 2.0. See [Migrating from 0.x](#migrating-from-0x).
- **1.0 prereleases are on npm's `next` tag:** `npm install react-data-export@next`. They have dataset export (`exportDataset`, `exportWorkbook`, `useExcelExport`, `<ExcelExport>`) and table export for an HTML `<table>` (`exportTable`, `useTableExport`, `<ExportTableButton>`), as specified in [docs/api.md](docs/api.md), built on javascript-excel 2.0's `fromDataset`, `fromTable`, writer and download. As an alpha, the API may still change before 1.0.0. Coming from 0.x: the [migration guide](docs/migration.md).
- **1.0 prereleases are on npm's `next` tag:** `npm install react-data-export@next`. They have dataset export (`exportDataset`, `exportWorkbook`, `useExcelExport`, `<ExcelExport>`) and table export for an HTML `<table>` (`exportTable`, `useTableExport`, `<ExportTableButton>`), as specified in [docs/api.md](docs/api.md), built on javascript-excel 2.0's `fromDataset`, `fromTable`, writer and download. The 1.0 feature set is complete: until 1.0.0, changes are limited to fixes found in testing. Coming from 0.x: the [migration guide](docs/migration.md).
- **Big exports stay responsive.** Exports run on the main thread. Since javascript-excel 2.0.0-alpha.7 (react-data-export requires 2.0.0-beta.0 or later), the `.xlsx` writer returns to the event loop about every 16 ms, so the page keeps rendering and handling input during a large export, and `abort()` works while it runs. A `worker` option, which writes the file in a Web Worker on top of `javascript-excel/worker`, comes in a 1.x release after 1.0.0, not in 1.0 ([docs/api.md §7](docs/api.md#7-errors-abort-and-progress)).

```tsx
import { ExcelExport } from 'react-data-export';
Expand Down
2 changes: 1 addition & 1 deletion apps/playground/package.json
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@
"test": "vitest run"
},
"dependencies": {
"javascript-excel": "^2.0.0-alpha.3",
"javascript-excel": "^2.0.0-beta.0",
"react": "^19.3.1",
"react-data-export": "1.0.0-alpha.3",
"react-dom": "^19.3.1"
Expand Down
2 changes: 1 addition & 1 deletion apps/playground/src/App.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -275,7 +275,7 @@ export function App(): ReactElement {
return (
<>
<aside className="banner" aria-label="Prerelease notice">
<strong>Prerelease.</strong> react-data-export {version} is an alpha; the API can still change before 1.0.0. Everything runs in your browser: no uploads, no tracking, no cookies.
<strong>Prerelease.</strong> react-data-export {version} is a 1.0 prerelease. The feature set is complete; until 1.0.0, changes are limited to fixes found in testing. Everything runs in your browser: no uploads, no tracking, no cookies.
</aside>
<main>
<header>
Expand Down
18 changes: 10 additions & 8 deletions docs/api.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# react-data-export 1.0: API design (dataset module)

Status: **design decided (2026-11-16); the dataset module is implemented** (RDE-1.9) on **javascript-excel ≥ 2.0.0-alpha.2** (see [§9](#9-dependencies-and-order)). It is not published yet. Table export (module B, [§13](#13-table-export)) is designed and implemented in RDE-1.17.
Status: **design decided (2026-11-16); the dataset module is implemented** (RDE-1.9) on **javascript-excel ≥ 2.0.0-beta.0** (see [§9](#9-dependencies-and-order)), and ships in the 1.0 prereleases on npm's `next` tag. The 1.0 feature set is complete: until 1.0.0, changes are limited to fixes found in testing. Table export (module B, [§13](#13-table-export)) is designed and implemented in RDE-1.17.

This document covers module A, **dataset export** (`exportDataset`, `exportWorkbook`, `useExcelExport`, `<ExcelExport>`), and module B, **table export** (`exportTable`, `useTableExport`, `<ExportTableButton>`, [§13](#13-table-export)).

Expand Down Expand Up @@ -263,10 +263,11 @@ export function ExcelExport(props: ExcelExportProps): ReactElement;
- react-data-export's own misuse errors (CSV with several sheets, `dataset` and `workbook` both or neither, an unknown `format`) are `TypeError`s. That's how javascript-excel treats invalid options too.
- **Abort.** `signal` reaches `toBlob`, which checks it between sheet chunks. It is also checked before building and before the download starts. Every export starts by yielding once (one microtask) and re-checking the signal before it builds anything. `toCsvBlob` is synchronous, so without that yield a CSV export started in an effect would finish, download included, before React 18/19 StrictMode's simulated unmount could abort it, and the documented auto-export recipe would save the file twice in development. An abort rejects with `signal.reason` (a `DOMException` `AbortError` by default). `toCsvBlob` is synchronous, so a CSV export can only be aborted before it starts.
- **Progress.** `onProgress` receives javascript-excel's `Progress` (`phase`, `sheet`, `ratio` from 0 to 1, non-decreasing) from `toBlob`. The building phase (`fromDataset`) is synchronous and reports nothing, so the first progress event comes from the writer. CSV reports no progress.
- **Big data.** Large exports run on the main thread in 1.0. Off-main-thread writing comes with javascript-excel's worker entry (its JSE-8):
- `fromDataset` has to run on the main thread, because accessors are functions and can't be sent to a worker.
- **Big data: the main thread stays responsive.** In 1.0, exports run on the main thread. From javascript-excel 2.0.0-alpha.7 (react-data-export depends on 2.0.0-beta.0 or later, §9), `toBlob` returns to the event loop about every 16 ms while it writes. So a large `.xlsx` export doesn't freeze the page: frames render, input is handled, and `abort()` or an aborted `signal` takes effect while the file is being written. The output bytes are the same as without the pauses. Building the sheet (`fromDataset`, `fromTable`) and writing CSV (`toCsvBlob`) are still synchronous.
- **Worker: 1.x, not 1.0** (decided 2026-11-17). javascript-excel's worker entry, `javascript-excel/worker` (its §5.5), has existed since 2.0.0-alpha.1. react-data-export adds it after 1.0.0, in a 1.x minor release:
- `fromDataset` and `fromTable` have to run on the main thread: accessors are functions and can't be sent to a worker, and the table is in the page.
- The resulting sheet is plain data, and can be written in a worker.
- When JSE-8 ships, `ExportOptions` gains `worker?: WorkerClient`. That is additive, not a breaking change. Until then this is listed under 1.x, not 1.0.
- `ExportOptions` gains `worker?: WorkerClient`. That's additive, not a breaking change, so it doesn't have to wait for 2.0.

## 8. SSR and `"use client"`

Expand All @@ -287,9 +288,10 @@ export function ExcelExport(props: ExcelExportProps): ReactElement;
| `toCsvBlob`, `CsvWriteOptions` | `javascript-excel/csv`, §5.3 | 2.0.0-alpha.1 |
| `download` | `javascript-excel/dom`, §5.4 | 2.0.0-alpha.1 (JSE-7) |
| `fromTable`, `FromTableOptions`, `TableElement` (§13) | `javascript-excel/dom`, §5.4 | 2.0.0-alpha.1 (JSE-7) |
| `WorkerClient` (1.x only) | `javascript-excel/worker`, §5.5 | planned (JSE-8) |
| `toBlob` returning to the event loop while it writes (§7) | core entry, §5.1 | 2.0.0-alpha.7 |
| `WorkerClient` (1.x only, §7) | `javascript-excel/worker`, §5.5 | 2.0.0-alpha.1 (JSE-8) |

So react-data-export depends on `"javascript-excel": "^2.0.0-alpha.2"` ([Q6](#12-design-decisions)), the first prerelease with `fromDataset`/`fromDatasets`. Nothing in react-data-export reimplements them.
So react-data-export depends on `"javascript-excel": "^2.0.0-beta.0"` ([Q6](#12-design-decisions)), the first 2.0.0 beta. 2.0.0-alpha.2 was the first prerelease with `fromDataset`/`fromDatasets`, and 2.0.0-alpha.7 the first whose writer yields to the browser. Nothing in react-data-export reimplements them.

## 10. Feature coverage

Expand All @@ -306,7 +308,7 @@ The 1.0 feature list, and where each one comes from:
| Totals row / formulas, hyperlinks (#103 #99 #175) | `total` on columns; cells with `formula` / `hyperlink` |
| RTL sheets (#109 #162 #157) | `rightToLeft` (`DatasetOptions`) |
| CSV options: delimiter, BOM, injection guard (#138) | `format: 'csv'` + `csv` (`CsvWriteOptions`); the injection guard is on by default |
| Big data: progress, `AbortSignal` (#154 #170 #153) | `onProgress`, `signal`, hook `abort()`; worker in 1.x (§7) |
| Big data: progress, `AbortSignal` (#154 #170 #153) | `onProgress`, `signal`, hook `abort()`; the writer yields to the browser on the main thread; worker in 1.x (§7) |
| SSR-safe, no `window` at import (#168 family) | §8 |
| Export an HTML table (#172) | `exportTable`, `useTableExport`, `<ExportTableButton>` over `fromTable` (§13) |

Expand Down Expand Up @@ -339,7 +341,7 @@ These were the open questions of the review. Each one is decided, and the sectio

**Q5. `<ExcelExport>` triggers.** Decided (2026-11-16): a default button or a render prop, with no `cloneElement` (§6). The 0.x-style `element` with an injected `onClick` is not carried over, because it breaks with components that don't forward `onClick` and with fragments.

**Q6. javascript-excel range during the 2.0 prereleases.** Decided (2026-11-16): `"javascript-excel": "^2.0.0-alpha.2"` (§9). A caret on a prerelease matches only later 2.0.0 prereleases and 2.0.0 itself. An exact pin bumped with each alpha was not taken.
**Q6. javascript-excel range during the 2.0 prereleases.** Decided (2026-11-16): a caret range on a prerelease, `"javascript-excel": "^2.0.0-alpha.2"` at the time and `^2.0.0-beta.0` now (§9). A caret on a prerelease matches only later 2.0.0 prereleases and 2.0.0 itself. An exact pin bumped with each alpha was not taken.

**Q7. Accessor fields.** Decided (2026-11-16): javascript-excel's `key` / `path` / `value` / `index` pass through unchanged (§3). That gives one documented shape for every framework and no ambiguity about `'a.b'`. A combined react-data-export field mapped to `key` or `path`, which javascript-excel's Q18 would allow, was not taken.

Expand Down
8 changes: 4 additions & 4 deletions docs/triage-1.0.md
Original file line number Diff line number Diff line change
Expand Up @@ -96,7 +96,7 @@ Thanks to the community pull requests whose ideas shaped 1.0:
| #85 | Error by importing the project | Fixed in 1.0.0-alpha.1 | No `tempa-xlsx`, `xlsx`, `file-saver` or `prop-types` any more; the only dependency is javascript-excel (no runtime deps). Import errors from the old dependency chain can't happen. |
| #90 | issue in react js dependence added time Module not found: Can't resolve 'react-data-export' using | Fixed in 1.0.0-alpha.1 | Same: the 0.x dependency chain is gone; `exports` map with ESM + CJS + types, smoke-tested from the packed tarball in CI. |
| #100 | Module not found: Can't resolve 'prop-types' in \node_modules\react-data-export\dist\ExcelPlugin\components | Fixed in 1.0.0-alpha.1 | `prop-types` is not used in 1.0. |
| #110 | xlsx dependency blows up webpack bundle size | Fixed in 1.0.0-alpha.1 | `xlsx`/`tempa-xlsx` are no longer dependencies; javascript-excel has zero runtime dependencies and per-entry tree-shaking (writer, CSV, DOM are separate entries). Bundle size: [placeholder, measure in the bundler matrix]. |
| #110 | xlsx dependency blows up webpack bundle size | Fixed in 1.0.0-alpha.1 | `xlsx`/`tempa-xlsx` are no longer dependencies; javascript-excel has zero runtime dependencies and per-entry tree-shaking (writer, CSV, DOM are separate entries). Bundle size, measured with the bundler matrix's `bundle-size` fixture (`npm run bundlers -- bundle-size`: Vite 8.3.8 + React 19.3.1 production builds, react-data-export 1.0.0-alpha.3 on javascript-excel 2.0.0-alpha.7 and 2.0.0-beta.0, which give the same numbers, minus the same app with React alone). `exportDataset` adds 72.8 KiB minified (24.7 KiB gzip), `<ExportTableButton>` 78.4 KiB (27.7 KiB gzip), every export of the main entry 90.0 KiB (31.5 KiB gzip). 0.6.0's `<ExcelFile>` adds 741.1 KiB (266.3 KiB gzip). |
| #168 | Module not found can't resolve 'fs' in node_modules\tempa-xlsx | Fixed in 1.0.0-alpha.1 | No `tempa-xlsx`, so no `fs` import; covered by the CRA/webpack 5 fixture in the bundler matrix (RDE-1.11). |
| #169 | Why does xlsx get installed into my package.json when installing this package | Fixed in 1.0.0-alpha.1 | `xlsx` is not a dependency or a required peer in 1.0. |
| #173 | Application crash when using vitejs | Fixed in 1.0.0-alpha.1 | No `cptable`/`xlsx` code; Vite fixture in the bundler matrix. |
Expand Down Expand Up @@ -218,7 +218,7 @@ Thanks to the community pull requests whose ideas shaped 1.0:
| # | title | disposition | how / reason |
|---|---|---|---|
| #154 | The maximum you can export to excel is 1299 rows, how to increase the number of exported rows? | Fixed in 1.0.0-alpha.1 | Measured on alpha.1 (Node 24): 1,300 / 10,000 / 100,000 rows × 3 columns export and read back complete (100k rows: 318 ms, 2.1 MB). |
| #170 | Browser window stops responding | Still open, tracked | The javascript-excel writer works in chunks and yields; a worker option (`javascript-excel/worker`) is planned for react-data-export 1.x. Keep open until the worker option ships. |
| #170 | Browser window stops responding | Still open, tracked | From javascript-excel 2.0.0-alpha.7 (react-data-export requires 2.0.0-beta.0 or later), the writer returns to the event loop about every 16 ms, so a large export on the main thread no longer freezes the page. The `worker` option (`javascript-excel/worker`) lands in react-data-export 1.x, not 1.0 (decided 2026-11-17). Keep open until the worker option ships. |

### Out of scope for 1.0

Expand Down Expand Up @@ -653,6 +653,6 @@ Each comment is followed by the footer above. "Close" means close after posting;

- **Side-by-side blocks (#134):** `fromDatasets` places a block next to the previous one only with a negative `offset.rows`. A clearer option (for example `offset: { beside: true }`) is a javascript-excel ticket.
- **Excel checks (#76, #94):** open a 1.0.0-alpha.1 single-sheet and multi-sheet file in Excel for Mac and Windows; close both issues with the result.
- **Bundle size (#110):** the bundler matrix (RDE-1.11) can record the size of a minimal app with and without react-data-export, so the comment can quote a measured number instead of `[placeholder]`.
- **Worker option (#170):** `ExportOptions.worker` on javascript-excel's `WorkerClient` (docs/api.md §7), for react-data-export 1.x.
- **Bundle size (#110):** measured (2026-11-17) with the bundler matrix's `bundle-size` fixture; the numbers are in the #110 row in §2. The `Bundlers` CI job prints the same table in its summary on every run.
- **Worker option (#170):** `ExportOptions.worker` on javascript-excel's `WorkerClient` (docs/api.md §7), in react-data-export 1.x, not 1.0 (decided 2026-11-17). Until then, the main-thread writer yields to the browser (javascript-excel 2.0.0-alpha.7).

1 change: 1 addition & 0 deletions fixtures/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,7 @@ Small apps that install the **packed** react-data-export tarball, exactly as use
| `vite-react19` | Vite 8 | 19 | production build of `<ExcelExport>`, `useExcelExport`, `exportDataset` and `useTableExport(ref)` behind a custom button; the bundle has no `fs`/`tempa-xlsx`/`jszip`/`cptable` |
| `next-app` | Next.js 16 (App Router, webpack and Turbopack builds) | 19 | `next build`: a server component renders `<ExcelExport>` (a client component through `"use client"`) and client components use the hook and `<ExportTableButton tableRef={ref}>` on a table with a `colspan` header; the page is prerendered on the server (the check looks for the table and the button in the HTML), so importing the package on the server must not crash |
| `webpack5-cra` | Create React App 5 (`react-scripts`, webpack 5) | 18 | production build with CRA's default config, which has no Node polyfills, including `<ExportTableButton>` (the `javascript-excel/dom` subpath through webpack 5's exports-map resolution) |
| `bundle-size` | Vite 8 | 19 | not a compatibility check: one production build per usage (`exportDataset` alone, `<ExportTableButton>` alone, every export, and 0.6.0's `<ExcelFile>` for comparison) and React alone, and a table of what each adds (minified, gzip -9, brotli -11), in the log and the job summary (#110) |
| `react17-ts` | Vite 8 | 17, with `@types/react` 17 | `tsc` against the published types, including `exportTable(ref, { format: "csv" })` with React 17's `useRef<HTMLTableElement>(null)`, then a production build |

These replace the failures reported in #168 (`Can't resolve 'fs'` with react-scripts 5), #173 (`cptable is not defined` with Vite), #177 (`Could not resolve "xlsx"` with Vite) and #182 (`jszip is not a constructor`). All of them came from the 0.x dependency on `tempa-xlsx`, `jszip` and `file-saver`, which 1.0 no longer has.
Expand Down
8 changes: 8 additions & 0 deletions fixtures/bundle-size/package.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,8 @@
{
"name": "fixture-bundle-size",
"private": true,
"type": "module",
"scripts": { "build": "vite build" },
"dependencies": { "react": "19.3.1", "react-dom": "19.3.1", "react-data-export-0.6": "npm:[email protected]", "prop-types": "15.8.1" },
"devDependencies": { "vite": "8.3.8" }
}
25 changes: 25 additions & 0 deletions fixtures/bundle-size/src/all.jsx
Original file line number Diff line number Diff line change
@@ -0,0 +1,25 @@
// Every export of the main entry, used: the upper bound for react-data-export.
import { useRef } from "react";
import { createRoot } from "react-dom/client";
import { ExcelExport, ExportTableButton, exportDataset, exportTable, exportWorkbook, isExcelError, sanitizeSheetName, useExcelExport, useTableExport } from "react-data-export";

const people = { columns: [{ title: "Name", key: "name" }], data: [{ name: "Ada" }] };

function App() {
const ref = useRef(null);
const hook = useExcelExport();
const table = useTableExport(ref);
return (
<>
<table ref={ref}><tbody><tr><td>Ada</td></tr></tbody></table>
<ExcelExport dataset={people}>Component</ExcelExport>
<ExportTableButton tableRef={ref}>Table button</ExportTableButton>
<button onClick={() => hook.exportDataset(people, { format: "csv" })}>Hook</button>
<button onClick={() => table.exportTable()}>Table hook</button>
<button onClick={() => exportWorkbook({ sheets: [{ ...people, name: sanitizeSheetName("a/b") }] }).catch((e) => isExcelError(e))}>Workbook</button>
<button onClick={() => Promise.all([exportDataset(people), exportTable(ref)])}>Both</button>
</>
);
}

createRoot(document.getElementById("root")).render(<App />);
4 changes: 4 additions & 0 deletions fixtures/bundle-size/src/baseline.jsx
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
// React alone: the app every other entry is measured against.
import { createRoot } from "react-dom/client";

createRoot(document.getElementById("root")).render(<button onClick={() => console.log("export")}>Export</button>);
7 changes: 7 additions & 0 deletions fixtures/bundle-size/src/dataset.jsx
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
// The smallest dataset export: one exportDataset call behind a button.
import { createRoot } from "react-dom/client";
import { exportDataset } from "react-data-export";

const people = { columns: [{ title: "Name", key: "name" }], data: [{ name: "Ada" }] };

createRoot(document.getElementById("root")).render(<button onClick={() => exportDataset(people, { filename: "people" })}>Export</button>);
16 changes: 16 additions & 0 deletions fixtures/bundle-size/src/table.jsx
Original file line number Diff line number Diff line change
@@ -0,0 +1,16 @@
// Table export: <ExportTableButton> on a table ref.
import { useRef } from "react";
import { createRoot } from "react-dom/client";
import { ExportTableButton } from "react-data-export";

function App() {
const ref = useRef(null);
return (
<>
<table ref={ref}><tbody><tr><td>Ada</td></tr></tbody></table>
<ExportTableButton tableRef={ref} filename="people">Export</ExportTableButton>
</>
);
}

createRoot(document.getElementById("root")).render(<App />);
Loading
Loading