docs.sheetjs.com/docz/docs/03-demos/12-static/11-svelte.md

363 lines
10 KiB
Markdown
Raw Normal View History

2023-04-30 12:27:09 +00:00
---
2023-08-18 20:39:12 +00:00
title: Supercharge SvelteKit Apps with Spreadsheets
2023-07-19 03:27:47 +00:00
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.
2023-04-30 12:27:09 +00:00
pagination_prev: demos/net/index
pagination_next: demos/mobile/index
---
import current from '/version.js';
2023-05-07 13:58:36 +00:00
import CodeBlock from '@theme/CodeBlock';
2023-04-30 12:27:09 +00:00
2023-07-19 03:27:47 +00:00
[SvelteKit](https://kit.svelte.dev/) is a framework for generating static sites.
It leverages modern technologies including ViteJS and SvelteJS[^1]
2023-04-30 12:27:09 +00:00
2023-07-19 03:27:47 +00:00
[SheetJS](https://sheetjs.com) is a JavaScript library for reading and writing
data from spreadsheets.
2023-04-30 12:27:09 +00:00
2023-07-19 03:27:47 +00:00
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.
2023-04-30 12:27:09 +00:00
2023-07-19 03:27:47 +00:00
The ["Complete Example"](#complete-example) section includes a complete website
powered by an XLSX spreadsheet.
2023-04-30 12:27:09 +00:00
2023-10-25 06:29:34 +00:00
:::info pass
This demo focuses on server-side processing with SvelteKit and Svelte.
2023-07-19 03:27:47 +00:00
The [Svelte demo](/docs/demos/frontend/svelte) covers general client-side usage.
:::
2023-04-30 12:27:09 +00:00
The following diagram depicts the workbook waltz:
```mermaid
flowchart LR
file[(workbook\nfile)]
subgraph SheetJS operations
base64(base64\nstring)
2023-05-25 01:36:15 +00:00
aoo(array of\nobjects)
2023-04-30 12:27:09 +00:00
end
html{{HTML\nTABLE}}
file --> |vite.config.js\ndata loader| base64
2023-05-25 01:36:15 +00:00
base64 --> |+page.server.js\nload function| aoo
aoo --> |+page.svelte\ncomponent| html
2023-04-30 12:27:09 +00:00
```
2023-12-05 03:46:54 +00:00
:::note Tested Deployments
2023-10-25 06:29:34 +00:00
2023-12-05 03:46:54 +00:00
This demo was tested in the following environments:
2024-06-04 03:54:48 +00:00
| SvelteJS | Kit | Date |
|:-----------------|:---------|:-----------|
| `4.2.17` | `2.5.10` | 2024-06-03 |
| `5.0.0-next.149` | `2.5.10` | 2024-06-03 |
2023-10-25 06:29:34 +00:00
:::
2023-04-30 12:27:09 +00:00
## Integration
`+page.server.js` scripts can be pre-rendered by exporting `prerender` from the
script. If the SheetJS operations are performed in the server script, only the
results will be added to the generated pages!
For static site generation, `@sveltejs/adapter-static` must be used.
### Loader
2023-07-19 03:27:47 +00:00
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
2023-04-30 12:27:09 +00:00
The ViteJS demo used the query `?b64` to identify files. To play nice with
SvelteKit, this demo matches the file extensions directly.
:::
The loader should be added to `vite.config.js`. The code is nearly identical to
2023-07-19 03:27:47 +00:00
the "Base64 Loader" ViteJS example.
2023-04-30 12:27:09 +00:00
```js title="vite.config.js"
import { sveltekit } from '@sveltejs/kit/vite';
import { defineConfig } from 'vite';
import { readFileSync } from 'fs';
export default defineConfig({
assetsInclude: ['**/*.numbers', '**/*.xlsx'],
plugins: [sveltekit(), {
name: "sheet-base64",
transform(code, id) {
if(!id.match(/\.(numbers|xlsx)$/)) return;
var data = readFileSync(id, "base64");
return `export default '${data}'`;
}
}]
});
```
#### Types
For VSCodium integration, types can be specified in `src/app.d.ts`.
The example data loader returns Base64 strings. Declarations should be added for
each file extension supported in the loader:
```ts title="src/app.d.ts"
declare global {
2023-08-18 20:39:12 +00:00
declare module '*.numbers' { const data: string; export default data; }
declare module '*.xlsx' { const data: string; export default data; }
2023-04-30 12:27:09 +00:00
}
```
### Data Processing
2023-07-19 03:27:47 +00:00
For static sites, SheetJS operations should be run in `+page.server.js`[^3]. The
script must include `export const prerender = true`[^4].
2023-04-30 12:27:09 +00:00
Assuming `pres.xlsx` is stored in the `data` directory from the project root,
the relative import
```js
import b64 from "../../data/pres.xlsx"
```
will return a Base64 string which can be parsed in the script. The workbook
2023-07-19 03:27:47 +00:00
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:
2023-04-30 12:27:09 +00:00
```js title="src/routes/+page.server.js"
import b64 from "../../data/pres.xlsx";
import { read, utils } from "xlsx";
export const prerender = true;
/** @type {import('./$types').PageServerLoad} */
export async function load({ params }) {
const wb = read(b64);
/** @type {[string, any[]][]} */
const data = wb.SheetNames.map(n => [n, utils.sheet_to_json(wb.Sheets[n])]);
return Object.fromEntries(data);
}
```
### Data Rendering
The shape of the data is determined by the loader. The example loader returns an
object whose keys are worksheet names and whose values are arrays of objects.
Using standard Svelte patterns, HTML tables can be generated from the data:
```html title="src/routes/+page.svelte"
<script>
/** @type {import('./$types').PageData} */
export let data;
/* `pres` will be the data from Sheet1 */
/** @type {Array<{Name: string, Index: number}>}*/
export let pres = data["Sheet1"];
</script>
<h1>Presidents</h1>
2023-12-05 03:46:54 +00:00
<table><thead><tr><th>Name</th><th>Index</th></tr></thead><tbody>
2023-04-30 12:27:09 +00:00
{#each pres as p}<tr>
<td>{p.Name}</td>
<td>{p.Index}</td>
</tr>{/each}
</tbody></table>
```
When built using `npm run build`, SvelteKit will perform the conversion and emit
a simple HTML table without any reference to the existing spreadsheet file!
## Complete Example
2024-06-04 03:54:48 +00:00
:::caution pass
When this demo was last tested, SvelteKit required NodeJS major version 20.
:::
2023-04-30 12:27:09 +00:00
### Initial Setup
1) Create a new site:
```bash
npm create svelte@latest sheetjs-svelte
```
2023-05-01 01:27:02 +00:00
When prompted:
- `Which Svelte app template?` select `Skeleton Project`
- `Add type checking with TypeScript?` select `Yes, using JavaScript with JSDoc`
2024-06-04 03:54:48 +00:00
- `Select additional options` press <kbd>Enter</kbd> (do not select options)
2023-05-01 01:27:02 +00:00
2023-12-05 03:46:54 +00:00
:::note pass
2024-06-04 03:54:48 +00:00
To test the Svelte 5 beta, select `Try the Svelte 5 preview (unstable!)`
2023-12-05 03:46:54 +00:00
:::
2023-07-19 03:27:47 +00:00
2) Enter the project folder and install dependencies:
```bash
cd sheetjs-svelte
npm i
```
2024-04-26 04:16:13 +00:00
3) Fetch the example file [`pres.xlsx`](https://docs.sheetjs.com/pres.xlsx) and
move to a `data` subdirectory in the root of the project:
2023-04-30 12:27:09 +00:00
```bash
mkdir -p data
2024-04-26 04:16:13 +00:00
curl -Lo data/pres.xlsx https://docs.sheetjs.com/pres.xlsx
2023-04-30 12:27:09 +00:00
```
2023-07-19 03:27:47 +00:00
4) Install the SheetJS library:
2023-04-30 12:27:09 +00:00
2023-05-07 13:58:36 +00:00
<CodeBlock language="bash">{`\
2023-04-30 12:27:09 +00:00
npm i --save https://cdn.sheetjs.com/xlsx-${current}/xlsx-${current}.tgz`}
2023-05-07 13:58:36 +00:00
</CodeBlock>
2023-04-30 12:27:09 +00:00
2024-06-04 03:54:48 +00:00
5) Replace the contents of `vite.config.js` with the following codeblock:
2023-04-30 12:27:09 +00:00
2023-12-05 03:46:54 +00:00
```js title="vite.config.js"
import { sveltekit } from '@sveltejs/kit/vite';
import { defineConfig } from 'vite';
import { readFileSync } from 'fs';
export default defineConfig({
assetsInclude: ['**/*.numbers', '**/*.xlsx'],
plugins: [sveltekit(), {
name: "sheet-base64",
transform(code, id) {
if(!id.match(/\.(numbers|xlsx)$/)) return;
var data = readFileSync(id, "base64");
return `export default '${data}'`;
}
}]
});
```
6) Append the following lines to `src/app.d.ts`:
```ts title="src/app.d.ts (add to end of file)"
declare global {
declare module '*.numbers' { const data: string; export default data; }
declare module '*.xlsx' { const data: string; export default data; }
}
```
2024-06-04 03:54:48 +00:00
7) Replace the contents of `src/routes/+page.server.js` with the following code.
Create the file if it does not exist.
2023-12-05 03:46:54 +00:00
```js title="src/routes/+page.server.js"
import b64 from "../../data/pres.xlsx";
import { read, utils } from "xlsx";
export const prerender = true;
/** @type {import('./$types').PageServerLoad} */
export async function load({ params }) {
const wb = read(b64);
/** @type {[string, any[]][]} */
const data = wb.SheetNames.map(n => [n, utils.sheet_to_json(wb.Sheets[n])]);
return Object.fromEntries(data);
}
```
2023-04-30 12:27:09 +00:00
2024-06-04 03:54:48 +00:00
8) Replace the contents of `src/routes/+page.svelte` with the following code.
Create the file if it does not exist.
2023-12-05 03:46:54 +00:00
```html title="src/routes/+page.svelte"
<script>
/** @type {import('./$types').PageData} */
export let data;
/* `pres` will be the data from Sheet1 */
/** @type {Array<{Name: string, Index: number}>}*/
export let pres = data["Sheet1"];
</script>
<h1>Presidents</h1>
<table><thead><tr><th>Name</th><th>Index</th></tr></thead><tbody>
{#each pres as p}<tr>
<td>{p.Name}</td>
<td>{p.Index}</td>
</tr>{/each}
</tbody></table>
```
2023-04-30 12:27:09 +00:00
### Live Reload
2023-07-19 03:27:47 +00:00
9) Open `data/pres.xlsx` in a spreadsheet editor like Apple Numbers or Excel.
2023-04-30 12:27:09 +00:00
2023-07-19 03:27:47 +00:00
10) Start the development server:
2023-04-30 12:27:09 +00:00
```bash
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.
2023-07-19 03:27:47 +00:00
11) In the spreadsheet, set cell A7 to `SheetJS Dev` and cell B7 to `47`. Save
2023-04-30 12:27:09 +00:00
the file. After saving, the browser should automatically refresh with new data.
### Static Site
2023-07-19 03:27:47 +00:00
12) Stop the development server and install the static adapter:
2023-04-30 12:27:09 +00:00
```bash
2023-05-07 13:58:36 +00:00
npm i --save @sveltejs/adapter-static
2023-04-30 12:27:09 +00:00
```
2023-12-05 03:46:54 +00:00
13) Edit `svelte.config.js` to use the new adapter.
The config should currently use `adapter-auto`:
```js title="svelte.config.js (default configuration)"
import adapter from '@sveltejs/adapter-auto';
```
Replace the module name with `@sveltejs/adapter-static`:
2023-04-30 12:27:09 +00:00
2023-12-05 03:46:54 +00:00
```js title="svelte.config.js (change dependency)"
import adapter from '@sveltejs/adapter-static';
2023-04-30 12:27:09 +00:00
```
2023-07-19 03:27:47 +00:00
14) Build the static site:
2023-04-30 12:27:09 +00:00
```bash
npm run build
```
2023-07-19 03:27:47 +00:00
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
2023-12-05 03:46:54 +00:00
<tr><td>Bill Clinton</td><td>42</td></tr>
2023-07-19 03:27:47 +00:00
```
[^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)