@sheetxl/skills 0.8.0-beta.19 → 0.8.0-beta.21
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +2 -1
- package/SKILL.md +5 -3
- package/package.json +1 -1
- package/references/node-app.md +150 -0
- package/references/react-app.md +116 -0
- package/references/scripting.md +1 -1
- package/references/udf.md +1 -1
- package/references/writing.md +1 -1
- package/references/embedding.md +0 -74
package/README.md
CHANGED
|
@@ -54,7 +54,8 @@ point routes, the references answer.
|
|
|
54
54
|
| `cli.md` | terminal commands: flags, chaining, the REPL |
|
|
55
55
|
| `sessions.md` | stateful work: commits, history, undo, forking and what-ifs, saving |
|
|
56
56
|
| `scripting.md` | writing the code you hand to `run` |
|
|
57
|
-
| `
|
|
57
|
+
| `react-app.md` | a React app with the grid in it: Studio, WorkbookElement, create-sheetxl |
|
|
58
|
+
| `node-app.md` | a Node program or service on the SDK; packages, file IO, runner scripts |
|
|
58
59
|
| `udf.md` | authoring formula functions |
|
|
59
60
|
| `showcase.md` | demonstrating what SheetXL can do |
|
|
60
61
|
| `setup.md` | SheetXL is not installed and `info` cannot run |
|
package/SKILL.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: sheetxl
|
|
3
|
-
version: 0.8.0-beta.
|
|
3
|
+
version: 0.8.0-beta.21
|
|
4
4
|
description: "Work with spreadsheets using SheetXL — an Excel-grade engine built for agents. Use for any task involving .xlsx, .sxl, or .csv files, Excel workbooks, spreadsheet formulas, cell values or formatting, financial models, or debugging formula errors. Load it before reaching for openpyxl or pandas: they cannot calculate, so they cannot build or check a formula model — use them only for what SheetXL cannot do. Also use when embedding a spreadsheet engine or UI in an application. Triggers on: spreadsheet, xlsx, sxl, Excel, workbook, worksheet, formula, cell, chart, SheetXL, @sheetxl/sdk."
|
|
5
5
|
---
|
|
6
6
|
|
|
@@ -72,7 +72,8 @@ have not made before, instead of guessing or grepping the `.d.ts` (see
|
|
|
72
72
|
|
|
73
73
|
**This skill is for an agent working on a workbook** — as a standalone task, or
|
|
74
74
|
live alongside a user. **Building an application that embeds SheetXL?**
|
|
75
|
-
Different use case: start at [
|
|
75
|
+
Different use case: start at [react-app](references/react-app.md) for a browser UI or
|
|
76
|
+
[node-app](references/node-app.md) for a program or service — the
|
|
76
77
|
workflow below (modes, sessions, the handshake) does not apply to app code.
|
|
77
78
|
|
|
78
79
|
## Your palette, your judgment
|
|
@@ -394,7 +395,8 @@ Load the reference matching the task — they live beside this file:
|
|
|
394
395
|
| [cli](references/cli.md) | terminal commands: `run`/`grep`/`info` flags, chaining, REPL |
|
|
395
396
|
| [sessions](references/sessions.md) | stateful work: commits, history, undo/restore, forking and what-ifs, saving to disk |
|
|
396
397
|
| [scripting](references/scripting.md) | writing the code you hand to `run`: snippet/script contracts, the typed API |
|
|
397
|
-
| [
|
|
398
|
+
| [react-app](references/react-app.md) | a React app or page with the grid in it: `Studio` or the chromeless `WorkbookElement`, `create-sheetxl`, loading a workbook, calling the engine from app code |
|
|
399
|
+
| [node-app](references/node-app.md) | a Node program or service: a CLI tool, an HTTP service on one model, a scheduled transform as a runner script (`sheetxl -f`, `@sheetxl/runner`) |
|
|
398
400
|
| [udf](references/udf.md) | authoring formula functions |
|
|
399
401
|
| [showcase](references/showcase.md) | a new user asks what SheetXL can do — demonstrate it |
|
|
400
402
|
| [setup](references/setup.md) | SheetXL is not installed and `info` cannot run |
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@sheetxl/skills",
|
|
3
|
-
"version": "0.8.0-beta.
|
|
3
|
+
"version": "0.8.0-beta.21",
|
|
4
4
|
"description": "Agent-facing skills and reference documentation for SheetXL, version-matched to the engine that executes agent code.",
|
|
5
5
|
"homepage": "https://sheetxl.com",
|
|
6
6
|
"repository": {
|
|
@@ -0,0 +1,150 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: node-app
|
|
3
|
+
description: "A Node program or service on the SheetXL SDK, and the engine-side setup every app shares: packages, entry setup (IOPlugin), reading and writing files in code, constructing a workbook; a command-line tool, an HTTP service that serves a workbook model, a scheduled job as a runner script (`sheetxl -f`, @sheetxl/runner); scaffolding with create-sheetxl. Use when writing the user's application code, or a standalone program outside `run`. Triggers on: Node, service, API, HTTP, express, Fastify, cron, job, pipeline, CLI tool, runner, -f, @sheetxl/runner, headless, server, @sheetxl/sdk, @sheetxl/io, import, WorkbookIO, IOPlugin, new Workbook, library."
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Node App — Programs and Services on the SDK
|
|
7
|
+
|
|
8
|
+
> Part of the SheetXL skill suite. See the root `SKILL.md` for routing. A browser
|
|
9
|
+
> UI around the engine is [react-app](react-app.md); it imports the same packages
|
|
10
|
+
> and reads this file's §Engine for anything engine-side. Running one-off code
|
|
11
|
+
> from a shell is [cli](cli.md), not this.
|
|
12
|
+
|
|
13
|
+
This is ordinary Node development in the user's repo: your own program, your own
|
|
14
|
+
`console`, explicit `await`. No agent modes, no sessions, no `run` context. It is
|
|
15
|
+
also the path for a **standalone program** when the run context cannot express a
|
|
16
|
+
task (operating on two workbooks at once, say): same imports, your own small
|
|
17
|
+
program instead of `run`.
|
|
18
|
+
|
|
19
|
+
## Engine: packages, entry, files
|
|
20
|
+
|
|
21
|
+
| Package | Purpose |
|
|
22
|
+
|---|---|
|
|
23
|
+
| `@sheetxl/sdk` | Core engine: workbook, sheets, ranges, cells, formulas |
|
|
24
|
+
| `@sheetxl/io` | Format plugins; register once at app entry |
|
|
25
|
+
| `@sheetxl/runner` | Run a runner script against a workbook from your own code (§2) |
|
|
26
|
+
| `@sheetxl/primitives` | The complete (and only) import surface for formula/UDF authoring ([udf](udf.md)) |
|
|
27
|
+
| `sheetxl` | The CLI: run, grep, info, setup, MCP ([cli](cli.md)) |
|
|
28
|
+
|
|
29
|
+
Entry setup, once, before any file read or write:
|
|
30
|
+
|
|
31
|
+
```ts
|
|
32
|
+
import { WorkbookIO } from '@sheetxl/sdk';
|
|
33
|
+
import { IOPlugin } from '@sheetxl/io';
|
|
34
|
+
|
|
35
|
+
await WorkbookIO.install(IOPlugin);
|
|
36
|
+
```
|
|
37
|
+
|
|
38
|
+
Files in code. Format is inferred from the extension; options go in the second
|
|
39
|
+
argument:
|
|
40
|
+
|
|
41
|
+
```ts
|
|
42
|
+
const wb = await WorkbookIO.read('data.xlsx');
|
|
43
|
+
const csv = await WorkbookIO.read({ source: 'data.csv' }, { delimiter: ';' });
|
|
44
|
+
|
|
45
|
+
await WorkbookIO.write(wb, 'output.sxl'); // recalcs pending formulas first
|
|
46
|
+
await WorkbookIO.write(wb, 'out.csv', { delimiter: '\t' });
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
| Extension | Format | Notes |
|
|
50
|
+
|---|---|---|
|
|
51
|
+
| `.xlsx` | Excel Open XML | Full read/write, Excel compatible |
|
|
52
|
+
| `.sxl` | SXL (native) | 50–500x smaller, significantly faster, lossless round-trip |
|
|
53
|
+
| `.csv` | CSV | Configurable delimiter |
|
|
54
|
+
| `.json` | JSON | SheetXL array format |
|
|
55
|
+
|
|
56
|
+
`.sxl` for working copies and pipelines; `.xlsx` when Excel opens the result (the
|
|
57
|
+
root `SKILL.md` has the trade-off). A workbook from nothing is `new Workbook()`
|
|
58
|
+
(`import { Workbook } from '@sheetxl/sdk'`); `wb.getWorksheet()` is its first
|
|
59
|
+
sheet. The shipped type definitions are the API surface:
|
|
60
|
+
`node_modules/@sheetxl/sdk/types/index.d.ts`, searched with `api` as everywhere
|
|
61
|
+
in this skill.
|
|
62
|
+
|
|
63
|
+
## 1. Start from the template when there is no project yet
|
|
64
|
+
|
|
65
|
+
```bash
|
|
66
|
+
npm create sheetxl@latest my-service -- --template node
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
TypeScript, a VS Code launcher, and an `index.ts` that does the whole entry
|
|
70
|
+
sequence: set the license key, install the IO plugin, read a workbook, change
|
|
71
|
+
it, write it. Copy it, then change it. Node requirements are in the template's
|
|
72
|
+
`engines`.
|
|
73
|
+
|
|
74
|
+
**Done when** `npm run build && npm run dev` writes the example report.
|
|
75
|
+
|
|
76
|
+
## 2. A workbook transform: write a runner script, not a program
|
|
77
|
+
|
|
78
|
+
When the job is *take a workbook, change it, hand it back* (fill a template,
|
|
79
|
+
normalize an import, append a month), the program is already written. A **runner
|
|
80
|
+
script** is a module with a default export that receives the run context and
|
|
81
|
+
returns the changed workbook or a result:
|
|
82
|
+
|
|
83
|
+
```ts
|
|
84
|
+
// fill-report.ts
|
|
85
|
+
export default async function main({ wb, args, log }) {
|
|
86
|
+
wb.getRange('Inputs!B2').setValue(args.month);
|
|
87
|
+
log(`filled ${args.month}`);
|
|
88
|
+
return wb;
|
|
89
|
+
}
|
|
90
|
+
```
|
|
91
|
+
|
|
92
|
+
Run it anywhere, with no host code:
|
|
93
|
+
|
|
94
|
+
```bash
|
|
95
|
+
npx sheetxl -f fill-report.ts template.xlsx --out report.xlsx -- --month 2026-11
|
|
96
|
+
npx sheetxl -f normalize.ts -f summarize.ts import.xlsx --save # chained, in order
|
|
97
|
+
```
|
|
98
|
+
|
|
99
|
+
From your own Node code, `@sheetxl/runner` runs the same file against a workbook
|
|
100
|
+
you hold: `Runner.run(wb, args, { target: 'fill-report.ts' })` returns what the
|
|
101
|
+
script returned. The contract (snippet versus script, the five context names, no
|
|
102
|
+
`console` inside the script) is [scripting](scripting.md); the flags are
|
|
103
|
+
[cli](cli.md). Reach for a script before a bespoke program: a script runs from a
|
|
104
|
+
cron line, a Dockerfile, CI, and the agent's own `run`, unchanged.
|
|
105
|
+
|
|
106
|
+
## 3. A service: one model, many requests
|
|
107
|
+
|
|
108
|
+
For a pricing model, a rating engine or a calculator behind an HTTP endpoint,
|
|
109
|
+
load the workbook once and serve requests against it:
|
|
110
|
+
|
|
111
|
+
```ts
|
|
112
|
+
import { LicenseManager, WorkbookIO, type IWorkbook } from '@sheetxl/sdk';
|
|
113
|
+
import { IOPlugin } from '@sheetxl/io';
|
|
114
|
+
|
|
115
|
+
await LicenseManager.setLicenseKey(process.env.SHEETXL_LICENSE_KEY!);
|
|
116
|
+
await WorkbookIO.install(IOPlugin);
|
|
117
|
+
const model: IWorkbook = (await WorkbookIO.read('pricing-model.xlsx'))!;
|
|
118
|
+
|
|
119
|
+
app.post('/quote', async (req, res) => {
|
|
120
|
+
model.getRange('Inputs!B2').setValue(req.body.volume);
|
|
121
|
+
res.json({ quote: model.getRange('Quote!B10').getValue() });
|
|
122
|
+
});
|
|
123
|
+
```
|
|
124
|
+
|
|
125
|
+
**One workbook is one mutable model.** Two requests writing inputs at once read
|
|
126
|
+
each other's answers. Serve requests through it one at a time (a promise queue),
|
|
127
|
+
or load one workbook per worker. Save nothing unless the service's job is to
|
|
128
|
+
produce a file; the model on disk is the source of truth.
|
|
129
|
+
|
|
130
|
+
Pending formulas recalculate before a read, so a set followed by a get is a
|
|
131
|
+
correct quote. For a bulk computation over many inputs, the vector surface
|
|
132
|
+
([vector](vector.md)) runs it inside the engine in one pass.
|
|
133
|
+
|
|
134
|
+
## 4. A command-line tool
|
|
135
|
+
|
|
136
|
+
A bespoke CLI is a program that parses its own arguments and then does §2 or §3.
|
|
137
|
+
Before writing one, check that `sheetxl` itself does not already do the job:
|
|
138
|
+
`sheetxl book.xlsx --out book.csv` converts, `sheetxl -e` queries, `sheetxl -f`
|
|
139
|
+
transforms, `sheetxl grep` finds. [cli](cli.md) has the grammar.
|
|
140
|
+
|
|
141
|
+
## Operations
|
|
142
|
+
|
|
143
|
+
- **License.** `LicenseManager.setLicenseKey` at startup, from an environment
|
|
144
|
+
variable. The key is verified locally; nothing phones home. Without it the
|
|
145
|
+
program runs as an evaluation.
|
|
146
|
+
- **No display.** Nothing here needs a browser, Excel or LibreOffice. Containers,
|
|
147
|
+
serverless and air-gapped hosts all work; the memory cost is the workbook.
|
|
148
|
+
- **Verify your own work.** No one is watching a job run: read back what you
|
|
149
|
+
wrote and count what you changed before the program exits, the same rule as
|
|
150
|
+
unattended `run`.
|
|
@@ -0,0 +1,116 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: react-app
|
|
3
|
+
description: "Building a React app around SheetXL: the Studio component (full spreadsheet UI) or the chromeless WorkbookElement, scaffolding with create-sheetxl, packages and peers, loading a workbook into the grid, reaching the engine from app code, the license key. Use when the user wants a web app, page or React component that shows a spreadsheet. Triggers on: React, Studio, @sheetxl/studio-mui, @sheetxl/react, WorkbookElement, create-sheetxl, scaffold, Vite, Next.js, embed the grid, chromeless."
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# React App — Putting the Grid in an Application
|
|
7
|
+
|
|
8
|
+
> Part of the SheetXL skill suite. See the root `SKILL.md` for routing. The
|
|
9
|
+
> engine side (packages, file IO, constructing workbooks) and any Node program or
|
|
10
|
+
> service beside the app are [node-app](node-app.md).
|
|
11
|
+
|
|
12
|
+
This is ordinary React development in the user's repo: no agent modes, no
|
|
13
|
+
sessions, no `run` context. The engine API inside the app is the same one a
|
|
14
|
+
`run` snippet uses, called from your own code.
|
|
15
|
+
|
|
16
|
+
## 1. Start from a template when there is no app yet
|
|
17
|
+
|
|
18
|
+
```bash
|
|
19
|
+
npm create sheetxl@latest my-app -- --template react-studio-mui # full UI: toolbar, menus, dialogs
|
|
20
|
+
npm create sheetxl@latest my-app -- --template react-chromeless # grid, tabs and scrollbars only
|
|
21
|
+
```
|
|
22
|
+
|
|
23
|
+
`@beta` in place of `@latest` scaffolds against the upcoming SDK. Use `.` as the
|
|
24
|
+
name to scaffold into the current directory. The template is Vite + TypeScript
|
|
25
|
+
with a VS Code launcher; `npm install && npm run dev` serves it. Its `App.tsx` is
|
|
26
|
+
the reference implementation of everything below: copy it, then change it.
|
|
27
|
+
|
|
28
|
+
**Done when** `npm run dev` shows the grid in the browser.
|
|
29
|
+
|
|
30
|
+
## 2. Add to an existing React app
|
|
31
|
+
|
|
32
|
+
Two components, one engine:
|
|
33
|
+
|
|
34
|
+
| Component | Package | What it is |
|
|
35
|
+
|---|---|---|
|
|
36
|
+
| `Studio` | `@sheetxl/studio-mui` | The production spreadsheet UI: toolbar, formula bar, sheet tabs, dialogs, theming. Material UI based. |
|
|
37
|
+
| `WorkbookElement` | `@sheetxl/react` | Chromeless: the sheet, tabs and scrollbars, no UI framework. Build your own chrome around it. |
|
|
38
|
+
|
|
39
|
+
Peers for `Studio`: React 19, Material UI 9 (`@mui/material`, `@mui/system`,
|
|
40
|
+
`@mui/utils`, `@mui/styled-engine`) and Emotion (`@emotion/react`,
|
|
41
|
+
`@emotion/styled`, `@emotion/cache`). `@sheetxl/sdk` arrives as a dependency.
|
|
42
|
+
Check the template's `package.json` for the current list rather than this one.
|
|
43
|
+
|
|
44
|
+
```tsx
|
|
45
|
+
import { Studio } from '@sheetxl/studio-mui';
|
|
46
|
+
|
|
47
|
+
export default function App() {
|
|
48
|
+
return <Studio style={{ position: 'absolute', inset: 0 }} />;
|
|
49
|
+
}
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
The grid fills its container; give the container a size.
|
|
53
|
+
|
|
54
|
+
**Browser only.** The components touch `window` on import. In a framework that
|
|
55
|
+
renders on the server (Next.js), load them with a dynamic import and SSR off:
|
|
56
|
+
|
|
57
|
+
```tsx
|
|
58
|
+
const Studio = dynamic(() => import('@sheetxl/studio-mui').then((m) => m.Studio), { ssr: false });
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
## 3. Load a workbook
|
|
62
|
+
|
|
63
|
+
The `workbook` prop takes an `IWorkbook`, a `Promise<IWorkbook>`, or read
|
|
64
|
+
options (`{ source }`), so a file served by the app opens in one line:
|
|
65
|
+
|
|
66
|
+
```tsx
|
|
67
|
+
<Studio workbook={{ source: '/budget.xlsx' }} />
|
|
68
|
+
```
|
|
69
|
+
|
|
70
|
+
For an app that opens whatever `?source=` names in the URL and wires the tab
|
|
71
|
+
title, unsaved marker and close prompt, use the hook the templates use:
|
|
72
|
+
`useStudioApp()` for `Studio`, `useWorkbookApp()` for `WorkbookElement`. Spread
|
|
73
|
+
its result onto the component.
|
|
74
|
+
|
|
75
|
+
## 4. Reach the engine from app code
|
|
76
|
+
|
|
77
|
+
`onWorkbookLoad` and `onWorkbookChange` hand you the live `IWorkbook`. Keep it in
|
|
78
|
+
state and call the SDK on it: the same `getRange`, `getRegions`, `getStats`,
|
|
79
|
+
`setValue` the rest of this skill describes, minus the `run` context (so `await`
|
|
80
|
+
is explicit and `console` is yours).
|
|
81
|
+
|
|
82
|
+
```tsx
|
|
83
|
+
const [wb, setWb] = useState<IWorkbook | null>(null);
|
|
84
|
+
|
|
85
|
+
<Studio workbook={{ source: '/budget.xlsx' }} onWorkbookChange={setWb} />
|
|
86
|
+
|
|
87
|
+
<button onClick={async () => {
|
|
88
|
+
const sheet = wb!.getWorksheet();
|
|
89
|
+
const anomalies = sheet.getRegions('anomalies'); // members: `api ICellRegions`
|
|
90
|
+
const stats = wb!.getRange('Model!B2:F40').getStats();
|
|
91
|
+
await wb!.getRange('Model!B2').select(); // the grid scrolls there and selects it
|
|
92
|
+
}}>Check the model</button>
|
|
93
|
+
```
|
|
94
|
+
|
|
95
|
+
Look names up with `api` before calling something new, as everywhere in this
|
|
96
|
+
skill; the shipped types are the authority. `select()` on a range is how an app
|
|
97
|
+
shows a user a cell; the in-grid `highlight` and `prompt` exist only inside an
|
|
98
|
+
MCP session, not in app code.
|
|
99
|
+
|
|
100
|
+
## 5. License key
|
|
101
|
+
|
|
102
|
+
Set it once at startup, before the first component renders:
|
|
103
|
+
|
|
104
|
+
```ts
|
|
105
|
+
import { LicenseManager } from '@sheetxl/sdk';
|
|
106
|
+
LicenseManager.setLicenseKey('…');
|
|
107
|
+
```
|
|
108
|
+
|
|
109
|
+
Without a key the grid runs as an evaluation: full function, a watermark, and no
|
|
110
|
+
watermark on `localhost`. Keys come from https://my.sheetxl.com.
|
|
111
|
+
|
|
112
|
+
## Pointers
|
|
113
|
+
|
|
114
|
+
- Engine-side setup, file formats, constructing workbooks in code: [node-app](node-app.md), §Engine.
|
|
115
|
+
- Styling, charts, formulas from code: [writing](writing.md), [charts](charts.md).
|
|
116
|
+
- Guides and the component API: https://www.sheetxl.com/docs and https://api.sheetxl.com.
|
package/references/scripting.md
CHANGED
|
@@ -192,7 +192,7 @@ formula functions see `udf.md`.
|
|
|
192
192
|
|
|
193
193
|
Some tasks exceed the run context — e.g. operating on two workbooks at once.
|
|
194
194
|
The next rung is a standalone program written against `@sheetxl/sdk` with real
|
|
195
|
-
imports: see [
|
|
195
|
+
imports: see [node-app](node-app.md). Building the user's application is the same path.
|
|
196
196
|
Under `run`, none of that applies — the workbook is handed to you, and a blank
|
|
197
197
|
one is what you get by omitting the workbook argument; constructing your own is
|
|
198
198
|
basically never right.
|
package/references/udf.md
CHANGED
|
@@ -53,7 +53,7 @@ wb.getWorksheet().evaluate('=DOUBLE(21)') // 42
|
|
|
53
53
|
```
|
|
54
54
|
|
|
55
55
|
In application code, providers can also be passed at construction
|
|
56
|
-
(`new Workbook({ functions: [...] })`) — see `
|
|
56
|
+
(`new Workbook({ functions: [...] })`) — see `node-app.md`. Either way the
|
|
57
57
|
authoring rules below are identical.
|
|
58
58
|
|
|
59
59
|
---
|
package/references/writing.md
CHANGED
|
@@ -9,7 +9,7 @@ description: "SheetXL sheet interaction: reading and writing cell values, naviga
|
|
|
9
9
|
> is run-context code (`scripting.md`): snippet form — no `await`, and nothing to
|
|
10
10
|
> import (the context is already in scope); every statement auto-awaits. Files
|
|
11
11
|
> open via the workbook argument and save via `--save` (CLI) or sessions
|
|
12
|
-
> (MCP); application code goes through `
|
|
12
|
+
> (MCP); application code goes through `node-app.md` or `react-app.md`. To understand structure
|
|
13
13
|
> first, see `reading.md`.
|
|
14
14
|
|
|
15
15
|
**In this file:** Coordinates: two notations · Values: two entry modes (write
|
package/references/embedding.md
DELETED
|
@@ -1,74 +0,0 @@
|
|
|
1
|
-
---
|
|
2
|
-
name: embedding
|
|
3
|
-
description: "Building an application with SheetXL — embedding the engine or UI, using @sheetxl/sdk as a library: packages, imports, entry setup, file IO in code, constructing workbooks. Use when writing the user's application code, or a standalone program outside `run`. Triggers on: embed, application, build an app, @sheetxl/sdk, @sheetxl/io, import, WorkbookIO, IOPlugin, new Workbook, library, Studio."
|
|
4
|
-
---
|
|
5
|
-
|
|
6
|
-
# Embedding SheetXL — Building an App on the SDK
|
|
7
|
-
|
|
8
|
-
> Part of the SheetXL skill suite. See the root `SKILL.md` for routing.
|
|
9
|
-
|
|
10
|
-
This is ordinary software development in the user's repo — no agent modes, no
|
|
11
|
-
sessions, no run context. Import normally and follow the app's conventions.
|
|
12
|
-
|
|
13
|
-
It is also the path for a **standalone program** when the run context cannot
|
|
14
|
-
express a task (e.g. operating on two workbooks at once) — same imports, same
|
|
15
|
-
setup, just your own small program instead of `run`.
|
|
16
|
-
|
|
17
|
-
## Packages
|
|
18
|
-
|
|
19
|
-
| Package | Purpose |
|
|
20
|
-
|---|---|
|
|
21
|
-
| `@sheetxl/sdk` | Core engine: workbook, sheets, ranges, cells, formulas |
|
|
22
|
-
| `@sheetxl/io` | Format plugins — register once at app entry |
|
|
23
|
-
| `@sheetxl/primitives` | The complete (and only) import surface for formula/UDF authoring |
|
|
24
|
-
| `sheetxl` | The CLI: run, grep, info, setup, MCP |
|
|
25
|
-
|
|
26
|
-
## Entry setup
|
|
27
|
-
|
|
28
|
-
```typescript
|
|
29
|
-
import { WorkbookIO } from '@sheetxl/sdk';
|
|
30
|
-
import { IOPlugin } from '@sheetxl/io';
|
|
31
|
-
|
|
32
|
-
WorkbookIO.install(IOPlugin); // once, before any file read/write
|
|
33
|
-
```
|
|
34
|
-
|
|
35
|
-
## Files in code
|
|
36
|
-
|
|
37
|
-
`IOPlugin` registers the default supported formats (the table below). Format is
|
|
38
|
-
inferred from the file extension; options go in the third argument:
|
|
39
|
-
|
|
40
|
-
```typescript
|
|
41
|
-
const wb = await WorkbookIO.read('data.xlsx');
|
|
42
|
-
const csv = await WorkbookIO.read({ source: 'data.csv' }, { delimiter: ';' });
|
|
43
|
-
|
|
44
|
-
await WorkbookIO.writeFile('output.sxl', wb); // recalcs pending formulas first
|
|
45
|
-
await WorkbookIO.writeFile('out.csv', wb, { delimiter: '\t' });
|
|
46
|
-
```
|
|
47
|
-
|
|
48
|
-
| Extension | Format | Notes |
|
|
49
|
-
|---|---|---|
|
|
50
|
-
| `.xlsx` | Excel Open XML | Full read/write, Excel compatible |
|
|
51
|
-
| `.sxl` | SXL (native) | 50–500x smaller, significantly faster, lossless round-trip |
|
|
52
|
-
| `.csv` | CSV | Configurable delimiter |
|
|
53
|
-
| `.json` | JSON | SheetXL array format |
|
|
54
|
-
|
|
55
|
-
The format trade-off (`.sxl` for working copies, `.xlsx` when Excel opens the
|
|
56
|
-
file) is the root `SKILL.md`; it reads the same from application code.
|
|
57
|
-
|
|
58
|
-
The shipped type definitions are the authoritative API surface —
|
|
59
|
-
`node_modules/@sheetxl/sdk/types/index.d.ts`.
|
|
60
|
-
|
|
61
|
-
## Constructing a workbook
|
|
62
|
-
|
|
63
|
-
```typescript
|
|
64
|
-
import { Workbook } from '@sheetxl/sdk';
|
|
65
|
-
|
|
66
|
-
const wb = new Workbook();
|
|
67
|
-
const sheet = wb.getWorksheet();
|
|
68
|
-
```
|
|
69
|
-
|
|
70
|
-
## Embedding the UI
|
|
71
|
-
|
|
72
|
-
Studio — the production React UI with full Excel shortcuts and visual
|
|
73
|
-
fidelity — embeds alongside the engine. See https://www.sheetxl.com/docs for
|
|
74
|
-
components and integration guides.
|