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/engine-2-0-0.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
---
"react-data-export": patch
---

Require javascript-excel `^2.0.0`, the stable release (was a 2.0.0 prerelease range).
2 changes: 1 addition & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ Export data from React to `.xlsx` and `.csv`.

- **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. 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)).
- **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 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-beta.0",
"javascript-excel": "^2.0.0",
"react": "^19.3.1",
"react-data-export": "1.0.0-beta.0",
"react-dom": "^19.3.1"
Expand Down
8 changes: 4 additions & 4 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-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.
Status: **design decided (2026-11-16); the dataset module is implemented** (RDE-1.9) on **javascript-excel ≥ 2.0.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,7 +263,7 @@ 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: 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.
- **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 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.
Expand Down Expand Up @@ -291,7 +291,7 @@ export function ExcelExport(props: ExcelExportProps): ReactElement;
| `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-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.
So react-data-export depends on `"javascript-excel": "^2.0.0"` ([Q6](#12-design-decisions)), the stable 2.0 release. 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 Down Expand Up @@ -341,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): 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.
**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, then `^2.0.0-beta.0`, and `^2.0.0` since javascript-excel 2.0.0 shipped on 2026-11-19 (§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
2 changes: 1 addition & 1 deletion docs/triage-1.0.md
Original file line number Diff line number Diff line change
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 | 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. |
| #170 | Browser window stops responding | Still open, tracked | From javascript-excel 2.0.0-alpha.7 (react-data-export requires 2.0.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
10 changes: 5 additions & 5 deletions package-lock.json

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

2 changes: 1 addition & 1 deletion packages/react-data-export/package.json
Original file line number Diff line number Diff line change
Expand Up @@ -80,6 +80,6 @@
"vitest": "^5.1.0"
},
"dependencies": {
"javascript-excel": "^2.0.0-beta.0"
"javascript-excel": "^2.0.0"
}
}
Loading