1. Spreadsheet docs
  2. Developers

Installation

Install 8sheets from npm or serve it as static files, and set up Vite, webpack, Next.js, Nuxt or the Angular CLI.

8sheets is a set of ES modules with no runtime dependencies. Besides its JavaScript, it loads a few files of its own at run time: its Web Workers (for reading and writing files), and data that only some features need, such as icons, spelling dictionaries and map shapes. Every setup on this page comes down to one rule: those files must stay next to the modules that load them, on your own site.

Packages

PackageWhat it isWorks with
@8sheets/coreThe spreadsheet and its API, with TypeScript declarationsCurrent browsers, and Node for headless use
8sheetsThe same package under an unscoped name
@8sheets/reactThe <Sheet> componentReact 18 and 19, StrictMode included
@8sheets/vueThe Sheet component and useSheet()Vue 3.4 or later, Nuxt
@8sheets/angularThe <eight-sheet> standalone componentAngular 17 or later, with zone.js or zoneless, and server rendering

Install the core package together with the component you use:

JavaScript

npm i @8sheets/core

React

npm i @8sheets/react @8sheets/core

Vue

npm i @8sheets/vue @8sheets/core

Angular

npm i @8sheets/angular @8sheets/core

The components add no runtime dependency beyond their framework. Keep @8sheets/core and the component at the same version: they are released together.

The files that are fetched only when a feature needs them are the bulk of the package: map data for filled map charts (about 4.8 MB), spelling dictionaries (about 1.1 MB), the thesaurus (about 3.8 MB) and the icon set (about 0.5 MB). A page that never uses those features never downloads them.

Vite

Vite serves and builds 8sheets with no plugin. Its Workers are ES modules, so set the Worker format:

// vite.config.js
import { defineConfig } from 'vite';

export default defineConfig({
  worker: { format: 'es' },
  // Only before Vite 8: keep 8sheets out of dependency pre-bundling, which would move
  // its modules away from their Workers, so files couldn't be opened or saved in `vite` dev.
  // With Vue, list '@8sheets/vue' here too.
  optimizeDeps: { exclude: ['@8sheets/core'] },
});

Vite 8 needs only the worker line.

Before Vite 8, don't await 8sheets at the top level of your entry module (main.js or the file index.html loads). Vite 7 and earlier build with Rollup, which puts the 8sheets modules the entry imports into the entry's own chunk; the parts 8sheets loads on demand (the grid, the ribbon, the panels) then import that chunk, which is still waiting at your await, so the page waits forever and mountWorkbook never resolves. With Vite 5 and 6 and their default build.target, such an entry doesn't build at all. Mount inside a function or with .then, or load 8sheets with import():

// Inside a function or with .then:
mountWorkbook(document.querySelector('#sheet')).then((wb) => {
  wb.activeSheet.range('A1').values = 'Hello';
});

// Or, at the top level, through import():
const { mountWorkbook } = await import('@8sheets/core');
const wb = await mountWorkbook(document.querySelector('#sheet'));

Vite 8, webpack, Next.js and pages without a bundler have no such limit.

webpack

webpack 5 copies the Workers and data files through the new URL('./…', import.meta.url) references 8sheets uses, with no loader or plugin. Nothing needs to be configured.

Next.js

@8sheets/react is marked 'use client', and it touches window and document only in an effect, so the server renders an empty <div>. It builds with Turbopack and with webpack, with no configuration. Render it from a client component:

'use client';
import { Sheet } from '@8sheets/react';

export default function Workbook() {
  return (
    <div style={{ height: 520 }}>
      <Sheet options={{ chrome: 'light' }} onReady={(wb) => console.log(wb.sheets.length)} />
    </div>
  );
}

To keep 8sheets out of the server bundle entirely, load it only in the browser. dynamic() doesn't forward refs, so take the workbook from onReady:

'use client';
import dynamic from 'next/dynamic';

const Sheet = dynamic(() => import('@8sheets/react').then((m) => m.Sheet), { ssr: false });

Nuxt

Wrap the component in <ClientOnly> so the server renders nothing and the browser mounts the workbook, and set the Worker format in nuxt.config.ts:

// nuxt.config.ts
export default defineNuxtConfig({
  vite: { worker: { format: 'es' } },
});
<template>
  <ClientOnly>
    <Sheet :options="{ chrome: 'light' }" style="height: 520px" @ready="onReady" />
  </ClientOnly>
</template>

Angular CLI

The Angular CLI bundles modules from node_modules but not the Worker and data files they load, so a bundled 8sheets could neither open nor save files. The component therefore loads 8sheets at run time from a served copy of the package. Add it to the assets of your build target in angular.json:

"assets": [
  { "glob": "**/*", "input": "node_modules/@8sheets/core", "output": "8sheets", "ignore": ["**/*.d.ts", "*.md", "package.json"] }
]

The component imports 8sheets/api/index.js, read against the page's <base href>, only on a page that shows a sheet and only in the browser, so your app's bundle doesn't grow. To serve it from another path, provide the URL of api/index.js:

// app.config.ts
import { ApplicationConfig } from '@angular/core';
import { EIGHT_SHEETS_URL } from '@8sheets/angular';

export const appConfig: ApplicationConfig = {
  providers: [{ provide: EIGHT_SHEETS_URL, useValue: '/static/8sheets/api/index.js' }],
};

In Angular code, import from @8sheets/core only types (import type). The values, such as createWorkbook, belong to the copy the component loads; reach them through the workbook it hands you.

Without a bundler

Copy the package folder into your site's static files and import its entry module:

cp -r node_modules/@8sheets/core public/vendor/8sheets
<div id="sheet" style="height: 600px"></div>
<script type="module">
  import { mountWorkbook } from '/vendor/8sheets/api/index.js';

  const wb = await mountWorkbook(document.getElementById('sheet'), { chrome: 'light' });
  wb.activeSheet.range('A1').values = [['Hello from 8sheets']];
</script>

The server must send .js files with a JavaScript content type, because the Workers are started as modules.

Serve it from your own site Browsers start a Worker only from the page's own origin. A public CDN on another domain can serve the modules, but opening and saving files would then fail. Serve 8sheets from your own domain, or from a CDN path that your domain proxies.

From the source licence

The source download holds the readable source. Serve its src/ folder with your app and import src/api/index.js; the components are in integrations/react, integrations/vue and integrations/angular, as plain files that import 8sheets through one relative path you adjust once. Each folder's README explains it.

Headers

8sheets uses SharedArrayBuffer when the page is cross-origin isolated, and runs without it otherwise. To turn it on, send:

Cross-Origin-Opener-Policy: same-origin
Cross-Origin-Embedder-Policy: credentialless

Use credentialless, not require-corp: require-corp blocks =IMAGE() pictures from other sites. A Content Security Policy that works with 8sheets is on Security and hosting.

Check the install

VERSION is exported, so a one-line check shows which version your bundler picked up:

import { VERSION } from '@8sheets/core';
console.log('8sheets', VERSION);

Then mount a workbook as in For developers and open an .xlsx file through File > Open: if the file opens, the Workers were found.

Node

@8sheets/core runs in Node with no page, for building and calculating workbooks on a server. See Workbooks in Node. Its declarations name DOM types such as HTMLElement, because the same API mounts in a page, so a Node project that checks library types (skipLibCheck: false) needs "DOM" in lib.