Skip to content

Commit 527f311

Browse files
thewtexthewtex
committed
docs: update vite example docs
1 parent b10f94e commit 527f311

File tree

2 files changed

+77
-57
lines changed

2 files changed

+77
-57
lines changed

‎docs/typescript/distribution/vite.md

Lines changed: 77 additions & 52 deletions
Original file line numberDiff line numberDiff line change
@@ -1,15 +1,25 @@
1-
# itk-wasm in a web browser application via Vite
1+
# ITK-Wasm package bundled with Vite
22

3-
This example demonstrates how to use *itk-wasm* in a web browser application built with [Vite](https://vitejs.dev/). Find the code in [itk-wasm/examples/Vite](https://github.com/InsightSoftwareConsortium/ITK-Wasm/tree/main/examples/Vite).
3+
This example demonstrates how to use an ITK-wasm package in a web browser application bundled with [Vite](https://vitejs.dev/).
44

5-
*itk-wasm* **asynchronously** downloads web worker JavaScript and WebAssembly Emscripten modules **on demand**. For *itk-wasm* to work:
5+
Find the full example in the `ITK-Wasm/examples/vite` [directory of the GitHub repository](https://github.com/InsightSoftwareConsortium/ITK-Wasm/tree/main/examples/vite).
66

7-
* Copy *itk-wasm* Javascript and WebAssembly files to a public directory
8-
* Tell *itk-wasm* the location to download the Javascript and WebAssembly files in the public directory
7+
ITK-Wasm **asynchronously** downloads web worker JavaScript and WebAssembly Emscripten modules **on demand**. This allows the main application to load quickly, while the ITK-Wasm modules are loaded in the background when needed. It also allows the application to use only the ITK-Wasm modules that it needs, rather than loading all of them at once. Finally, computation-intensive tasks can be offloaded to web workers, which run in a separate thread from the main application, preventing the UI from freezing during long-running tasks.
98

10-
## Copy *itk-wasm* Javascript and WebAssembly files to a public directory
9+
A few steps are required to configure Vite to work with ITK-Wasm packages:
1110

12-
In the Vite example, `vite.config.js` uses `vite-plugin-static-copy` to move prebuilt *itk-wasm* files to the `/dist` directory.
11+
1. Copy ITK-Wasm Javascript and WebAssembly assets to a public directory.
12+
2. Tell ITK-Wasm the location of the assets.
13+
3. Prevent Vite from pre-bundling ITK-Wasm packages.
14+
15+
## Copy Javascript and WebAssembly assets to a public directory
16+
17+
In the Vite example, `vite.config.js` uses `vite-plugin-static-copy` to copy prebuilt *ITK-Wasm* pipeline assets to the `/dist` directory.
18+
19+
```sh
20+
npm install @itk-wasm/image-io
21+
npm install -D vite-plugin-static-copy
22+
```
1323

1424
```js
1525
import { defineConfig } from 'vite'
@@ -20,84 +30,99 @@ export default defineConfig({
2030
// put lazy loaded JavaScript and Wasm bundles in dist directory
2131
viteStaticCopy({
2232
targets: [
23-
{ src: 'node_modules/itk-wasm/dist/web-workers/*', dest: 'dist/itk/web-workers' },
2433
{
25-
src: 'node_modules/itk-image-io/*',
26-
dest: 'dist/itk/image-io',
34+
src: "node_modules/@itk-wasm/image-io/dist/pipelines/*.{js,wasm,wasm.zst}",
35+
dest: "pipelines/",
2736
},
28-
{
29-
src: 'node_modules/itk-mesh-io/*',
30-
dest: 'dist/itk/mesh-io',
31-
rename: 'mesh-io'
32-
}
3337
],
34-
})
38+
}),
3539
],
3640
...
3741
})
3842
```
3943

40-
The Vite config copies *web-workers* directory, which asynchronously perform IO or runs processing pipelines in a background thread.
44+
## Tell ITK-Wasm the location of the WebAssembly assets
45+
46+
Call `setPipelinesBaseUrl` to tell the ITK-Wasm package where to find the WebAssembly assets. This is typically done in the main JavaScript file of your application, after importing the ITK-Wasm package.
4147

42-
The config copies the complete *image-io* and *mesh-io* directories. You may want to copy a subset of *image-io* or *mesh-io* files, based on what features you use of *itk-wasm*.
48+
```js
49+
// Example ITK-Wasm package, @itk-wasm/image-io
50+
import { readImage, setPipelinesBaseUrl } from "@itk-wasm/image-io";
51+
52+
// Use app-vendored WebAssembly module assets copied by viteStaticCopy
53+
const viteBaseUrl = import.meta.env.BASE_URL || "/";
54+
const pipelinesBaseUrl = new URL(
55+
`${viteBaseUrl}pipelines`,
56+
document.location.origin
57+
).href;
58+
setPipelinesBaseUrl(pipelinesBaseUrl);
59+
60+
[...]
61+
// Call the readImage function from the package
62+
const { image } = await readImage(files[0]);
63+
[...]
64+
```
4365

44-
## Tell *itk-wasm* the location to download the Javascript and WebAssembly files
66+
## Prevent Vite from pre-bundling ITK-Wasm packages
4567

46-
To change the location of the *itk-wasm* web worker and Emscripten modules, configure Vite's `resolve.alias` setting.
68+
Ensure that Vite does try to pre-bundle the ITK-Wasm packages, which can break lazy loading of the web worker and Emscripten modules. This is done by adding associated packages the `optimizeDeps.exclude` array in `vite.config.js`. This is more important when an ITK-Wasm package is a transitive dependency.
4769

4870
```js
49-
import { defineConfig } from 'vite'
50-
import path from 'path'
51-
52-
const itkConfig = path.resolve(__dirname, 'src', 'itkConfig.js')
71+
import { defineConfig } from "vite";
72+
import { viteStaticCopy } from "vite-plugin-static-copy";
5373

5474
export default defineConfig({
55-
...
56-
resolve: {
57-
// where itk-wasm code has 'import ../itkConfig.js` point to the path of itkConfig
58-
alias: {
59-
'../itkConfig.js': itkConfig,
60-
'../../itkConfig.js': itkConfig
61-
}
62-
}
63-
})
64-
```
6575

66-
The itkConfig.js file holds paths where *itk-wasm* fetches assets at runtime.
76+
// @thewtex/zstddec is used to decompress the WebAssembly modules
77+
optimizeDeps: {
78+
exclude: ["itk-wasm", "@itk-wasm/image-io", "@thewtex/zstddec"],
79+
},
6780

68-
```js
69-
const itkConfig = {
70-
pipelineWorkerUrl: '/itk/web-workers/min-bundles/pipeline.worker.js',
71-
imageIOUrl: '/itk/image-io',
72-
meshIOUrl: '/itk/mesh-io',
73-
pipelinesUrl: '/itk/pipelines'
74-
}
75-
76-
export default itkConfig
81+
plugins: [
82+
// put lazy loaded JavaScript and Wasm bundles in dist directory
83+
viteStaticCopy({
84+
targets: [
85+
{
86+
src: "node_modules/@itk-wasm/image-io/dist/pipelines/*.{js,wasm,wasm.zst}",
87+
dest: "pipelines/",
88+
},
89+
],
90+
}),
91+
],
92+
});
7793
```
7894

95+
7996
## Test the example
8097

81-
In the example [directory](https://github.com/InsightSoftwareConsortium/ITK-Wasm/tree/main/examples/Vite)
98+
In the [example directory](https://github.com/InsightSoftwareConsortium/ITK-Wasm/tree/main/examples/Vite):
8299

83100
### Development
84101

85102
```sh
86103
npm install
87-
npm run start
104+
npm start
88105
```
89-
And visit [http://localhost:8080/](http://localhost:8080/).
90106

91-
### Test static bundled assets
107+
And visit [http://localhost:8085/](http://localhost:8085/).
108+
109+
<video width="480" autoplay muted loop>
110+
<source src="../../_static/videos/vite.webm" type="video/webm">
111+
Sorry, your browser doesn't support embedded videos.
112+
</video>
113+
114+
### Build for production and preview
92115

93116
```sh
94117
npm run build
95-
npm run start:production
118+
npm run preview
96119
```
97120

98-
### Run Cypress end to end tests
121+
### Run Playwright end to end tests
122+
123+
The full example is configured for browser-based testing with the [Playwright](https://playwright.dev/) library.
99124

100125
```sh
101-
npm run build
102-
npm run test
126+
npx playwright install --with-deps
127+
npm test
103128
```

‎examples/vite/vite.config.js

Lines changed: 0 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,15 +1,10 @@
1-
import path from "path";
2-
31
import { defineConfig } from "vite";
42
import { viteStaticCopy } from "vite-plugin-static-copy";
53

64
export default defineConfig({
75
server: {
86
port: 8085,
97
},
10-
worker: {
11-
format: "es",
12-
},
138
optimizeDeps: {
149
exclude: ["itk-wasm", "@itk-wasm/image-io", "@thewtex/zstddec"],
1510
},

0 commit comments

Comments
 (0)