Installation — Sheetwrite

Choose a framework in the header once. Every framework-aware example uses that preference, including the quick starts below and the lifecycle guide.

$ npm install @sheetwrite/core

import { createGrid, initSheetwrite } from "@sheetwrite/core";
import "@sheetwrite/core/styles.css";

await initSheetwrite();
const grid = createGrid(document.querySelector("#grid")!, { workbook, data });

The host owns initialization and must destroy the returned Grid when its DOM lifetime ends.

$ npm install @sheetwrite/react

import { Sheetwrite } from "@sheetwrite/react";
import "@sheetwrite/react/styles.css";

export function Workbook() {
  return <Sheetwrite columns={columns} defaultRows={rows} height={520} />;
}

The adapter initializes WASM after client mount. Use a client component boundary in server-rendered React hosts.

$ npm install @sheetwrite/vue

<script setup lang="ts">
import { Sheetwrite } from "@sheetwrite/vue";
import "@sheetwrite/vue/styles.css";
</script>

<template>
  <Sheetwrite :columns="columns" :default-rows="rows" height="520px" />
</template>

The adapter initializes WASM after client mount. Use a client-only boundary in Nuxt and other server-rendered Vue hosts.

$ npm install @sheetwrite/svelte

<script lang="ts">
  import { Sheetwrite } from "@sheetwrite/svelte";
  import "@sheetwrite/svelte/styles.css";
</script>

<Sheetwrite {columns} defaultRows={rows} height="520px" />

The adapter initializes WASM after client mount. Use a client-only boundary when a SvelteKit route renders on the server.

Server-rendered host boundaries

The adapter host, its Grid, and WASM initialization are client-owned. Server rendering may produce surrounding layout and fallback content, but it must not instantiate a Sheetwrite component or call createGrid.

Next.js App Router: put the adapter import and component in a module whose first directive is "use client". Import @sheetwrite/react/styles.css once from the root layout. The production fixture builds a static Next route, hydrates it in Chromium, then proves ready, edit, input reset, and unmount using the adapter's zero-argument initializer.

Nuxt: render @sheetwrite/vue from a .client.vue component or inside Nuxt's <ClientOnly> boundary, and load @sheetwrite/vue/styles.css through the app-level css configuration. Nuxt is not currently in the release runtime matrix, so this boundary is required and server-side component execution is not claimed as supported.

SvelteKit: make the containing route client-rendered with export const ssr = false, or create the adapter only from onMount when the rest of the route must stay server-rendered. Import @sheetwrite/svelte/styles.css from the client-owned component or app stylesheet. SvelteKit is not currently in the release runtime matrix; direct SSR of the adapter is not claimed as supported.

Runtime initialization

Zero-argument initSheetwrite() is canonical for the imperative package. It is re-entrant: concurrent calls share one initialization, retries work after failure, and repeats after success are no-ops. Framework adapters call the same initializer on mount.

Pass a source only for unsupported bundlers, public-asset policies, or controlled delivery:

await initSheetwrite(source);

Accepted sources are BufferSource | URL | string | Request | WebAssembly.Module. The raw binary remains exported as @sheetwrite/wasm/wasm.

// Vite-family URL
import wasmUrl from "@sheetwrite/wasm/wasm?url";
await initSheetwrite(wasmUrl);

// webpack asset URL
await initSheetwrite(new URL("@sheetwrite/wasm/wasm", import.meta.url));

// Public-copy fallback
await initSheetwrite("/sheetwrite_wasm_bg.wasm");

webpack and Next.js need no IgnorePlugin; package export conditions keep Node filesystem code out of browser graphs.

Full formula engine

By default, @sheetwrite/core uses @sheetwrite/wasm. This engine has the standard function set and the smallest download. Install @sheetwrite/formulas when the app needs the analysis families: distributions and statistics, regression, finance, dates, text and regex, database, matrices, reshaping, LAMBDA helpers, and GROUPBY/PIVOTBY. It uses the same engine code, with more functions and a larger download. The analysis formulas guide shows each family with examples. Choose an engine by its functions and download size.

$ npm install @sheetwrite/core @sheetwrite/formulas

Select the engine one time, before the app creates a grid or a store, and before a framework adapter mounts:

import { initSheetwrite } from "@sheetwrite/core";
import * as formulas from "@sheetwrite/formulas";

await initSheetwrite(undefined, formulas);

An app uses one engine. After initialization starts, the engine cannot change. A call that selects a different engine rejects.
Later calls to initSheetwrite() without an engine keep the selected engine. Framework adapters make this call when they mount.
The default engine returns #NAME? for the analysis functions, and formula assist does not suggest them. An import of @sheetwrite/formulas does not select the engine.
The formula function contract shows which build has each function.

Failure UI and retries

React accepts fallback; Vue and Svelte use fallback content or slots. Initialization failures reach onInitializationError or Vue's initialization-error. A changed explicit source or remount can retry after failure.

Optional feature assets

Worker rendering and XLSX stay explicit. Import the Worker entry from @sheetwrite/core/worker. XLSX requires @sheetwrite/xlsx plus import "@sheetwrite/xlsx/register" before toolbar or programmatic export.