This commit is contained in:
SheetJS 2023-07-18 23:27:47 -04:00
parent c541c81a16
commit 272cecf23c
3 changed files with 86 additions and 37 deletions

@ -1,25 +1,35 @@
---
title: SvelteKit
sidebar_label: SvelteKit
description: Make static websites from spreadsheets using SvelteKit. Seamlessly integrate data into your website using SheetJS. Rapidly develop web apps powered by data in Excel.
pagination_prev: demos/net/index
pagination_next: demos/mobile/index
---
# Supercharge SvelteKit Apps with Spreadsheets
import current from '/version.js';
import CodeBlock from '@theme/CodeBlock';
:::note
[SvelteKit](https://kit.svelte.dev/) is a framework for generating static sites.
It leverages modern technologies including ViteJS and SvelteJS[^1]
This demo covers SvelteKit. The [Svelte demo](/docs/demos/frontend/svelte)
covers general client-side strategies.
[SheetJS](https://sheetjs.com) is a JavaScript library for reading and writing
data from spreadsheets.
This demo uses ["Base64 Loader"](/docs/demos/static/vitejs#base64-loader)
from the ViteJS demo.
This demo uses SvelteKit and SheetJS to pull data from a spreadsheet and display
the content in an HTML table. We'll explore how to use a plugin to pull raw data
from files and how to organize page scripts to process the files at compile time.
The ["Complete Example"](#complete-example) section includes a complete website
powered by an XLSX spreadsheet.
:::note pass
The [Svelte demo](/docs/demos/frontend/svelte) covers general client-side usage.
:::
SvelteKit projects use ViteJS under the hood. They expose the `vite.config.js`
script. The [ViteJS demo](/docs/demos/static/vitejs) examples work as expected!
The following diagram depicts the workbook waltz:
```mermaid
@ -45,7 +55,11 @@ For static site generation, `@sveltejs/adapter-static` must be used.
### Loader
:::note
SvelteKit projects use ViteJS under the hood. They expose the `vite.config.js`
script. The "Base64 Loader" from the ViteJS demo[^2] can pull data from files
into Base64 strings for processing in `+page.server.js` scripts.
:::note pass
The ViteJS demo used the query `?b64` to identify files. To play nice with
SvelteKit, this demo matches the file extensions directly.
@ -53,7 +67,7 @@ SvelteKit, this demo matches the file extensions directly.
:::
The loader should be added to `vite.config.js`. The code is nearly identical to
the ["Base64 Loader" ViteJS example.](/docs/demos/static/vitejs#base64-loader)
the "Base64 Loader" ViteJS example.
```js title="vite.config.js"
import { sveltekit } from '@sveltejs/kit/vite';
@ -95,7 +109,8 @@ declare global {
### Data Processing
For static sites, SheetJS operations should be run in `+page.server.js` .
For static sites, SheetJS operations should be run in `+page.server.js`[^3]. The
script must include `export const prerender = true`[^4].
Assuming `pres.xlsx` is stored in the `data` directory from the project root,
the relative import
@ -105,9 +120,12 @@ import b64 from "../../data/pres.xlsx"
```
will return a Base64 string which can be parsed in the script. The workbook
object can be post-processed using utility functions. The following example
uses `sheet_to_json` to generate arrays of row objects for each worksheet. The
data presented to the page will be an object whose keys are worksheet names:
object can be post-processed using utility functions.
The following example uses the SheetJS `read` method[^5] to parse spreadsheet
files and the `sheet_to_json` method[^6] to generate arrays of row objects for
each worksheet. The data presented to the page will be an object whose keys are
worksheet names:
```js title="src/routes/+page.server.js"
import b64 from "../../data/pres.xlsx";
@ -157,7 +175,7 @@ a simple HTML table without any reference to the existing spreadsheet file!
:::note
This demo was tested on 2023 April 30 using SvelteKit `1.15.9`
This demo was tested on 2023 July 12 using SvelteKit `1.22.2` and Svelte `4.0.5`
:::
@ -167,8 +185,6 @@ This demo was tested on 2023 April 30 using SvelteKit `1.15.9`
```bash
npm create svelte@latest sheetjs-svelte
cd sheetjs-svelte
npm i
```
When prompted:
@ -177,7 +193,14 @@ When prompted:
- `Add type checking with TypeScript?` select `Yes, using JavaScript with JSDoc`
- `Select additional options` press Enter (do not select options)
2) Fetch the example file [`pres.xlsx`](https://sheetjs.com/pres.xlsx) and move
2) Enter the project folder and install dependencies:
```bash
cd sheetjs-svelte
npm i
```
3) Fetch the example file [`pres.xlsx`](https://sheetjs.com/pres.xlsx) and move
to a `data` subdirectory in the root of the project:
```bash
@ -185,29 +208,30 @@ mkdir -p data
curl -Lo data/pres.xlsx https://sheetjs.com/pres.xlsx
```
3) Install the SheetJS library:
4) Install the SheetJS library:
<CodeBlock language="bash">{`\
npm i --save https://cdn.sheetjs.com/xlsx-${current}/xlsx-${current}.tgz`}
</CodeBlock>
4) Replace the contents of `vite.config.js` with the contents of the code block
5) Replace the contents of `vite.config.js` with the contents of the code block
named [`vite.config.js` in the "Loader" section](#loader)
5) Append the lines from [`src/app.d.ts` snippet in the "Types" section](#types)
6) Append the lines from [`src/app.d.ts` snippet in the "Types" section](#types)
to the `src/app.d.ts` file.
6) Replace the contents of `src/routes/+page.server.ts` with the contents of the
code block named [`src/routes/+page.server.ts` in "Data Processing"](#data-processing)
7) Replace the contents of `src/routes/+page.server.ts` with the contents of the
code block named [`src/routes/+page.server.ts` in "Data Processing"](#data-processing).
If the file does not exist, create a new file.
7) Replace the contents of `src/routes/+page.svelte` with the contents of the
8) Replace the contents of `src/routes/+page.svelte` with the contents of the
code block named [`src/routes/+page.svelte` in "Data Rendering"](#data-rendering)
### Live Reload
8) Open `data/pres.xlsx` in a spreadsheet editor like Apple Numbers or Excel.
9) Open `data/pres.xlsx` in a spreadsheet editor like Apple Numbers or Excel.
9) Start the development server:
10) Start the development server:
```bash
npm run dev
@ -216,29 +240,48 @@ npm run dev
Open the displayed URL (typically `http://localhost:5173`) in a web browser and
observe that the data from the spreadsheet is displayed in the page.
10) In the spreadsheet, set cell A7 to `SheetJS Dev` and cell B7 to `47`. Save
11) In the spreadsheet, set cell A7 to `SheetJS Dev` and cell B7 to `47`. Save
the file. After saving, the browser should automatically refresh with new data.
### Static Site
11) Stop the development server and install the static adapter:
12) Stop the development server and install the static adapter:
```bash
npm i --save @sveltejs/adapter-static
```
12) Edit `svelte.config.js` to use the new adapter:
13) Edit `svelte.config.js` to use the new adapter:
```diff title="svelte.config.js"
-import adapter from '@sveltejs/adapter-auto';
+import adapter from '@sveltejs/adapter-static';
```
13) Build the static site:
14) Build the static site:
```bash
npm run build
```
14) Open a web browser and access the displayed URL (`http://localhost:8080`).
View the page source and confirm that the raw HTML table includes the data.
15) Start a local web server that will host the production build:
```bash
npx -y http-server build
```
16) Open a web browser and access the displayed URL (`http://localhost:8080`).
View the page source and confirm that the raw HTML table includes the data.
Searching for `Bill Clinton` should reveal the following row:
```html
<tr><td>Bill Clinton</td> <td>42</td> </tr>
```
[^1]: See ["SvelteKit vs Svelte"](https://kit.svelte.dev/docs/introduction#sveltekit-vs-svelte) in the SvelteKit documentation.
[^2]: See ["Base64 Plugin" in the ViteJS demo](/docs/demos/static/vitejs#base64-plugin)
[^3]: See ["Universal vs server"](https://kit.svelte.dev/docs/load#universal-vs-server) in the SvelteKit documentation.
[^4]: See ["prerender"](https://kit.svelte.dev/docs/page-options#prerender) in the SvelteKit documentation.
[^5]: See [`read` in "Reading Files"](/docs/api/parse-options)
[^6]: See [`sheet_to_json` in "Utilities"](/docs/api/utilities/array#array-output)

@ -7,6 +7,12 @@ sidebar_position: 2
<details>
<summary><b>File Format Support</b> (click to show)</summary>
Traditional spreadsheet software, including Excel, support "Cell Links". The
entire cell text is clickable.
Modern spreadsheet software, including Numbers, support "Span Links". Links are
applied to text fragments within the cell content. This mirrors HTML semantics.
| Formats | Link | Tooltip | Link Type |
|:------------------|:-----:|:-------:|:----------|
| XLSX / XLSM | ✔ | ✔ | Cell Link |
@ -29,14 +35,14 @@ Hyperlinks are stored in the `l` key of cell objects. The `Target` field of the
hyperlink object is the target of the link, including the URI fragment. Tooltips
are stored in the `Tooltip` field and are displayed when hovering over the text.
For example, the following snippet creates a link from cell `A3` to
For example, the following snippet creates a link from cell `A1` to
<https://sheetjs.com> with the tip `"Find us @ SheetJS.com!"`:
```js
ws["A1"].l = { Target: "https://sheetjs.com", Tooltip: "Find us @ SheetJS.com!" };
```
:::note
:::note pass
Following traditional software, hyperlinks are applied to entire cell objects.
Some formats (including HTML) attach links to text spans. The parsers apply the
@ -44,7 +50,7 @@ first link to the entire cell. Writers apply links to the entire cell text.
:::
:::caution
:::caution pass
Excel does not automatically style hyperlinks. They will be displayed using
the default cell style.
@ -142,7 +148,7 @@ ws["B3"].l = { Target: "SheetJS.xlsb" }; /* Link to SheetJS.xlsb */
ws["B4"].l = { Target: "../SheetJS.xlsm" }; /* Link to ../SheetJS.xlsm */
```
:::caution
:::caution pass
Relative Paths have undefined behavior in the SpreadsheetML 2003 format. Excel
2019 will treat a `..\` parent mark as two levels up.

@ -39,7 +39,7 @@ These instructions were tested on the following platforms:
| Platform | Test Date |
|:------------------------------|:-----------|
| Linux (Steam Deck Holo 3.4.6) | 2023-04-04 |
| Linux (Steam Deck Holo 3.4.8) | 2023-07-12 |
| Linux (Ubuntu 18.04 aarch64) | 2023-04-13 |
| MacOS 10.13 (x64) | 2023-04-04 |
| MacOS 13.0 (arm64) | 2023-04-13 |