docs.sheetjs.com/docz/docs/03-demos/12-static/02-gatsbyjs.md

541 lines
14 KiB
Markdown
Raw Normal View History

2023-01-15 03:36:13 +00:00
---
2023-10-09 01:13:21 +00:00
title: Spreadsheets in GatsbyJS Sites
sidebar_label: GatsbyJS
description: Make static websites from spreadsheets using GatsbyJS. Seamlessly integrate data into your website using SheetJS. Generate websites from data in Excel spreadsheets.
2023-02-28 11:40:44 +00:00
pagination_prev: demos/net/index
pagination_next: demos/mobile/index
2023-01-15 03:36:13 +00:00
sidebar_custom_props:
type: native
---
import current from '/version.js';
2023-10-09 01:13:21 +00:00
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
2023-05-07 13:58:36 +00:00
import CodeBlock from '@theme/CodeBlock';
2023-01-15 03:36:13 +00:00
2024-05-05 03:43:33 +00:00
export const r = {style: {color:"red"}};
export const R = {style: {backgroundColor:"darkred"}};
2023-10-09 01:13:21 +00:00
GatsbyJS is a framework for creating websites. It uses React components for page
templates and GraphQL for loading data.
2023-01-15 03:36:13 +00:00
2023-10-09 01:13:21 +00:00
[SheetJS](https://sheetjs.com) is a JavaScript library for reading and writing
data from spreadsheets.
2023-01-15 03:36:13 +00:00
2023-10-09 01:13:21 +00:00
This demo uses GatsbyJS and SheetJS (through the `gatsby-transformer-excel`[^1]
transformer) to pull data from a spreadsheet and display the content in a page.
The ["Complete Example"](#complete-example) section includes a complete website
powered by an XLSX spreadsheet.
:::info pass
2023-01-15 03:36:13 +00:00
`gatsby-transformer-excel` is maintained by the Gatsby core team and all bugs
should be directed to the main Gatsby project. If it is determined to be a bug
2023-10-09 01:13:21 +00:00
in the parsing logic, issues should then be raised with the SheetJS team.
2023-01-15 03:36:13 +00:00
:::
2023-09-24 03:59:48 +00:00
:::caution pass
2023-01-15 03:36:13 +00:00
`gatsby-transformer-excel` uses an older version of the library. It can be
overridden through a `package.json` override in the latest versions of NodeJS:
2023-10-09 01:13:21 +00:00
<CodeBlock language="json" title="package.json (add highlighted lines)">{`\
2023-01-15 03:36:13 +00:00
{
"overrides": {
"xlsx": "https://cdn.sheetjs.com/xlsx-${current}/xlsx-${current}.tgz"
}
}`}
2023-05-07 13:58:36 +00:00
</CodeBlock>
2023-01-15 03:36:13 +00:00
:::
:::danger Telemetry
2023-10-09 01:13:21 +00:00
GatsbyJS collects telemetry by default. The `telemetry` subcommand can disable it:
```js
npx gatsby telemetry --disable
```
:::
## Integration Details
```mermaid
flowchart LR
file[(workbook\nfile)]
subgraph SheetJS operations
filenode[File\nNode]
datanode[Data\nNodes]
end
aoo(array of\nobjects)
html{{HTML\nTABLE}}
file --> |Source\nPlugin| filenode
filenode --> |Transformer\nPlugin| datanode
datanode --> |GraphQL\nQuery| aoo
aoo --> |React\nJSX| html
```
In the GatsbyJS data system, source plugins read from data sources and generate
nodes represent raw data. Transformer plugins transform these nodes into other
nodes that represent processed data for use in pages.
This example uses `gatsby-source-filesystem`[^2] to read files from the
filesystem and `gatsby-transformer-excel` transformer to perform the transform.
### Installation
The [SheetJS NodeJS module](/docs/getting-started/installation/nodejs) will be
referenced by `gatsby-transformer-excel`.
Before installing, to ensure that the transformer uses the latest version of the
library, the `overrides` section must be added to `package.json`:
<CodeBlock language="json" title="package.json (add highlighted lines)">{`\
{
// highlight-start
"overrides": {
"xlsx": "https://cdn.sheetjs.com/xlsx-${current}/xlsx-${current}.tgz"
}
// highlight-end
}`}
</CodeBlock>
`gatsby-transformer-excel` and `gatsby-source-filesystem` should be installed
after installing SheetJS modules:
<Tabs groupId="pm">
<TabItem value="npm" label="npm">
<CodeBlock language="bash">{`\
npx gatsby telemetry --disable
npm i --save https://cdn.sheetjs.com/xlsx-${current}/xlsx-${current}.tgz
npm i --save gatsby-transformer-excel gatsby-source-filesystem`}
</CodeBlock>
</TabItem>
<TabItem value="pnpm" label="pnpm">
<CodeBlock language="bash">{`\
npx gatsby telemetry --disable
2024-03-20 07:05:29 +00:00
pnpm install --save https://cdn.sheetjs.com/xlsx-${current}/xlsx-${current}.tgz
pnpm install --save gatsby-transformer-excel gatsby-source-filesystem`}
2023-10-09 01:13:21 +00:00
</CodeBlock>
</TabItem>
<TabItem value="yarn" label="Yarn" default>
<CodeBlock language="bash">{`\
npx gatsby telemetry --disable
yarn add https://cdn.sheetjs.com/xlsx-${current}/xlsx-${current}.tgz
yarn add gatsby-transformer-excel gatsby-source-filesystem`}
</CodeBlock>
</TabItem>
</Tabs>
### GraphQL details
Under the hood, `gatsby-transformer-excel` uses the SheetJS `read`[^3] method to
parse the workbook into a SheetJS workbook[^4]. Each worksheet is extracted from
the workbook. The `sheet_to_json` method[^5] generates row objects using the
headers in the first row as keys.
2023-01-15 03:36:13 +00:00
2023-10-09 01:13:21 +00:00
Consider the following worksheet:
2023-01-15 03:36:13 +00:00
![pres.xlsx](pathname:///pres.png)
Assuming the file name is `pres.xlsx` and the data is stored in "Sheet1", the
following nodes will be created:
2024-04-01 10:44:10 +00:00
```js title="GraphQL Nodes"
2023-01-15 03:36:13 +00:00
[
{ Name: "Bill Clinton", Index: 42, type: "PresXlsxSheet1" },
{ Name: "GeorgeW Bush", Index: 43, type: "PresXlsxSheet1" },
{ Name: "Barack Obama", Index: 44, type: "PresXlsxSheet1" },
{ Name: "Donald Trump", Index: 45, type: "PresXlsxSheet1" },
{ Name: "Joseph Biden", Index: 46, type: "PresXlsxSheet1" },
]
```
The type is a proper casing of the file name concatenated with the sheet name.
The following query pulls the `Name` and `Index` fields from each row:
2024-04-01 10:44:10 +00:00
```graphql title="GraphQL Query to pull Name and Index fields from each row"
2023-01-15 03:36:13 +00:00
{
allPresXlsxSheet1 { # "all" followed by type
edges {
node { # each line in this block should be a field in the data
Name
Index
}
}
}
}
```
2023-10-09 01:13:21 +00:00
## Complete Example
2023-01-15 03:36:13 +00:00
2023-12-05 03:46:54 +00:00
:::note Tested Deployments
2023-01-15 03:36:13 +00:00
2024-04-01 10:44:10 +00:00
This demo was tested in the following environments:
| GatsbyJS | Date |
|:---------|:-----------|
2024-05-05 03:43:33 +00:00
| `5.13.4` | 2024-05-04 |
2024-04-01 10:44:10 +00:00
| `4.25.8` | 2024-03-27 |
2023-01-15 03:36:13 +00:00
:::
### Project setup
2023-10-09 01:13:21 +00:00
0) Disable GatsbyJS telemetry:
```bash
npx gatsby telemetry --disable
```
2024-05-05 03:43:33 +00:00
:::info pass
In NodeJS 22, the process displayed an error:
<pre>
<span {...R}> ERROR </span><span {...r}> UNKNOWN</span>
{`\n`}
{`\n`}
(node:25039) [DEP0040] DeprecationWarning: The `punycode` module is deprecated.
Please use a userland alternative instead.
(Use `node --trace-deprecation ...` to show where the warning was created)
</pre>
**This is a false report!**
The error can be safely ignored.
:::
2023-10-09 01:13:21 +00:00
1) Create a template site:
```bash
2024-04-01 10:44:10 +00:00
npx gatsby new sheetjs-gatsby
```
:::info pass
For older Gatsby versions, the project must be built from the starter project.
For GatsbyJS 4, the starter commit is `6bc4466090845f20650117b3d27e68e6e46dc8d5`
and the steps are shown below:
```bash
git clone https://github.com/gatsbyjs/gatsby-starter-default sheetjs-gatsby
cd sheetjs-gatsby
git checkout 6bc4466090845f20650117b3d27e68e6e46dc8d5
npm install
cd ..
2023-10-09 01:13:21 +00:00
```
2023-01-15 03:36:13 +00:00
2024-04-01 10:44:10 +00:00
:::
2023-01-15 03:36:13 +00:00
2) Follow the on-screen instructions for starting the local development server:
```bash
cd sheetjs-gatsby
npm run develop
```
Open a web browser to the displayed URL (typically `http://localhost:8000/`)
3) Edit `package.json` and add the highlighted lines in the JSON object:
2023-12-05 03:46:54 +00:00
<CodeBlock language="json" title="package.json (add highlighted lines)">{`\
2023-01-15 03:36:13 +00:00
{
// highlight-start
"overrides": {
"xlsx": "https://cdn.sheetjs.com/xlsx-${current}/xlsx-${current}.tgz"
},
// highlight-end
"name": "sheetjs-gatsby",
"version": "1.0.0",
`}
2023-05-07 13:58:36 +00:00
</CodeBlock>
2023-01-15 03:36:13 +00:00
4) Install the library and plugins:
2023-05-07 13:58:36 +00:00
<CodeBlock language="bash">{`\
2023-01-15 03:36:13 +00:00
npm i --save https://cdn.sheetjs.com/xlsx-${current}/xlsx-${current}.tgz
npm i --save gatsby-transformer-excel gatsby-source-filesystem
`}
2023-05-07 13:58:36 +00:00
</CodeBlock>
2023-01-15 03:36:13 +00:00
2024-04-01 10:44:10 +00:00
:::info pass
For older versions of Gatsby, older versions of the dependencies must be used.
For GatsbyJS 4, the plugin version numbers align with the Gatsby version:
```bash
npm i --save gatsby-transformer-excel@4 gatsby-source-filesystem@4
```
:::
2024-04-26 04:16:13 +00:00
5) Make a `src/data` directory, download https://docs.sheetjs.com/pres.xlsx, and
2023-04-07 08:30:20 +00:00
move the downloaded file into the new folder:
2023-01-15 03:36:13 +00:00
2023-04-07 08:30:20 +00:00
```bash
mkdir -p src/data
2024-04-26 04:16:13 +00:00
curl -L -o src/data/pres.xlsx https://docs.sheetjs.com/pres.xlsx
2023-04-07 08:30:20 +00:00
```
6) Edit `gatsby-config.js` and add the following lines to the `plugins` array:
2023-12-05 03:46:54 +00:00
```js title="gatsby-config.js (add highlighted lines)"
2023-04-07 08:30:20 +00:00
module.exports = {
siteMetadata: {
title: `sheetjs-gatsby`,
siteUrl: `https://www.yourdomain.tld`,
},
// highlight-start
2023-01-15 03:36:13 +00:00
plugins: [
{
resolve: `gatsby-source-filesystem`,
options: {
name: `data`,
path: `${__dirname}/src/data/`,
},
},
`gatsby-transformer-excel`,
],
2023-04-07 08:30:20 +00:00
// highlight-end
}
2023-01-15 03:36:13 +00:00
```
2024-04-01 10:44:10 +00:00
:::note pass
If the `plugins` array exists, the two plugins should be added at the beginning:
```js title="gatsby-config.js (add highlighted lines)"
plugins: [
// highlight-start
{
resolve: `gatsby-source-filesystem`,
options: {
name: `data`,
path: `${__dirname}/src/data/`,
},
},
`gatsby-transformer-excel`,
// highlight-end
// ...
```
:::
2023-01-15 03:36:13 +00:00
Stop and restart the development server process (`npm run develop`).
### GraphiQL test
2023-12-05 03:46:54 +00:00
7) Open the GraphiQL editor. The output of the previous step displayed the URL
(typically `http://localhost:8000/___graphql` )
2023-01-15 03:36:13 +00:00
There is an editor in the left pane. Paste the following query into the editor:
2023-12-05 03:46:54 +00:00
```graphql title="GraphQL Query (paste into editor)"
2023-01-15 03:36:13 +00:00
{
allPresXlsxSheet1 {
edges {
node {
Name
Index
}
}
}
}
```
2023-12-05 03:46:54 +00:00
Press the Execute Query button (`▶`) and data should show up in the right pane:
2023-01-15 03:36:13 +00:00
![GraphiQL Screenshot](pathname:///gatsby/graphiql.png)
2024-05-05 03:43:33 +00:00
<details>
<summary><b>Sample Output</b> (click to show)</summary>
In GatsbyJS version `5.13.4`, the raw output was:
```json title="GraphQL query result from GatsbyJS 5.13.4"
{
"data": {
"allPresXlsxSheet1": {
"edges": [
{
"node": {
"Name": "Bill Clinton",
"Index": 42
}
},
{
"node": {
"Name": "GeorgeW Bush",
"Index": 43
}
},
{
"node": {
"Name": "Barack Obama",
"Index": 44
}
},
{
"node": {
"Name": "Donald Trump",
"Index": 45
}
},
{
"node": {
"Name": "Joseph Biden",
"Index": 46
}
}
]
}
},
"extensions": {}
}
```
</details>
2023-01-15 03:36:13 +00:00
### React page
8) Create a new file `src/pages/pres.js` that uses the query and displays the result:
2024-05-05 03:43:33 +00:00
```jsx title="src/pages/pres.js (create new file)"
2023-01-15 03:36:13 +00:00
import { graphql } from "gatsby"
import * as React from "react"
export const query = graphql`query {
allPresXlsxSheet1 {
edges {
node {
Name
Index
}
}
}
}`;
const PageComponent = ({data}) => {
return ( <pre>{JSON.stringify(data, 2, 2)}</pre> );
};
export default PageComponent;
```
2023-10-09 01:13:21 +00:00
After saving the file, access `http://localhost:8000/pres` in the browser. The
displayed JSON is the data that the component receives:
2023-01-15 03:36:13 +00:00
2023-12-05 03:46:54 +00:00
```js title="Expected contents of /pres"
2023-01-15 03:36:13 +00:00
{
"allPresXlsxSheet1": {
"edges": [
{
"node": {
"Name": "Bill Clinton",
"Index": 42
}
},
// ....
```
9) Change `PageComponent` to display a table based on the data:
2024-04-01 10:44:10 +00:00
```jsx title="src/pages/pres.js (replace PageComponent)"
2023-01-15 03:36:13 +00:00
import { graphql } from "gatsby"
import * as React from "react"
export const query = graphql`query {
allPresXlsxSheet1 {
edges {
node {
Name
Index
}
}
}
}`;
// highlight-start
const PageComponent = ({data}) => {
const rows = data.allPresXlsxSheet1.edges.map(r => r.node);
return ( <table>
<thead><tr><th>Name</th><th>Index</th></tr></thead>
<tbody>{rows.map(row => ( <tr>
<td>{row.Name}</td>
<td>{row.Index}</td>
</tr> ))}</tbody>
</table> );
};
// highlight-end
export default PageComponent;
```
Going back to the browser, `http://localhost:8000/pres` will show a table:
![Data in Table](pathname:///gatsby/table1.png)
### Live refresh
2023-12-05 03:46:54 +00:00
10) Open the file `src/data/pres.xlsx` in Excel or another spreadsheet editor.
Add a new row at the end of the file, setting cell `A7` to "SheetJS Dev" and
cell `B7` to `47`. The sheet should look like the following screenshot:
2023-01-15 03:36:13 +00:00
![New Row in File](pathname:///gatsby/pres2.png)
2023-12-05 03:46:54 +00:00
Save the file and observe that the table has refreshed with the new data:
2023-01-15 03:36:13 +00:00
![Updated Table](pathname:///gatsby/table2.png)
### Static site
2023-12-05 03:46:54 +00:00
11) Stop the development server and build the site:
2023-01-15 03:36:13 +00:00
2023-12-05 03:46:54 +00:00
```bash
npm run build
2023-01-15 03:36:13 +00:00
```
2023-12-05 03:46:54 +00:00
The build output will confirm that the `/pres` route is static:
```text title="Output from GatsbyJS build process"
2023-01-15 03:36:13 +00:00
Pages
┌ src/pages/404.js
│ ├ /404/
│ └ /404.html
├ src/pages/index.js
│ └ /
└ src/pages/pres.js
└ /pres/
╭────────────────────────────────────────────────────────────────╮
│ │
│ (SSG) Generated at build time │
│ D (DSG) Deferred static generation - page generated at runtime │
│ ∞ (SSR) Server-side renders at runtime (uses getServerData) │
│ λ (Function) Gatsby function │
│ │
╰────────────────────────────────────────────────────────────────╯
```
2023-09-14 08:19:13 +00:00
The generated page will be placed in `public/pres/index.html`.
2023-01-15 03:36:13 +00:00
2023-09-14 08:19:13 +00:00
12) Open `public/pres/index.html` with a text editor and search for "SheetJS".
There will be a HTML row:
2023-12-05 03:46:54 +00:00
```html title="public/pres/index.html (Expected contents)"
2023-01-15 03:36:13 +00:00
<tr><td>SheetJS Dev</td><td>47</td></tr>
```
2023-10-09 01:13:21 +00:00
[^1]: The package is available as [`gatsby-transformer-excel` on the public NPM registry](https://www.npmjs.com/package/gatsby-transformer-excel). It is also listed on the [GatsbyJS plugin library](https://www.gatsbyjs.com/plugins/gatsby-transformer-excel/).
[^2]: See [the `gatsby-source-filesystem` plugin](https://www.gatsbyjs.com/plugins/gatsby-source-filesystem/) in the GatsbyJS documentation
[^3]: See [`read` in "Reading Files"](/docs/api/parse-options)
[^4]: See ["Workbook Object"](/docs/csf/book) for more details on the SheetJS workbook object.
[^5]: See [`sheet_to_json` in "Utilities"](/docs/api/utilities/array#array-output)