kwasm
Standalone wasm-based client-only layout viewer for semiconductor designs, powered by KLayout.
kwasm compiles KLayout's layout rendering engine to WebAssembly via Emscripten, wrapped in a Rust FFI layer. The result is an interactive GDS2/OASIS viewer that runs entirely in the browser — no install required.
Features
- View GDS2 and OASIS layout files in the browser
- Pan, zoom, select, measure, and draw annotations
- Layer panel with per-layer visibility toggling and color display
- Toolbar with switchable interaction modes
- Dark and light theme
- Load layouts via drag & drop or
?url=query parameter - Configurable toolbar via
?tools=query parameter - Python package with embeddable Jupyter viewer
- CLI for bundling layouts into self-contained HTML files
Quick Start
# Build all WASM artifacts
just build
# Build docs site and serve at http://localhost:8080
just serve
Available Commands
| Command | Description |
|---|---|
just build [mode] |
Build WASM artifacts (all by default) |
just dev [mode] |
Copy bundled HTML from dist/ into the Python package |
just wheel |
Build Python wheel |
just dist |
Build everything (WASM + wheel) |
just check [mode] |
Check WASM compilation (no link) |
just test |
Run Python and standalone Rust tests |
just docs [mode] |
Build versioned documentation pages in site/ |
just serve [mode] [port] |
Build docs and serve |
just clean |
Clean build artifacts |
Testing
The default test command does not require Emscripten, KLayout C++ compilation, or browser binaries:
just test
Use the focused commands when working in a specific part of the repository:
| Command | Test suite |
|---|---|
just test-python |
Complete pytest suite |
just test-rust |
Standalone Rust crates that do not link KLayout |
just test-js |
Vitest unit project; requires npm dependencies and built WASM artifacts |
just test-js-browser |
Vitest browser project; additionally requires Playwright Chromium |
CI runs the Python and Rust suites plus the existing Vitest unit/browser projects and WASM compilation checks.
Query Parameters
| Parameter | Description |
|---|---|
?url= |
Load a layout file from a URL (e.g. ?url=https://example.com/chip.gds) |
?tools= |
Comma-separated list of toolbar tools to show. All tools are shown by default. |
?lyp= |
Load a .lyp layer properties file from a URL (e.g. ?lyp=layers.lyp) |
?drop= |
Enable/disable drag & drop (true/false). Default: true. |
?layers= |
Show/hide the layer panel (true/false). Default: true. |
Available tool names for ?tools=:
| Name | Description |
|---|---|
select |
Pointer/select mode |
move |
Pan mode |
ruler |
Ruler/measure mode |
draw-polyline |
Draw polyline annotations |
draw-manhattan |
Draw manhattan route |
draw-freehand |
Draw freehand annotations |
clear-all |
Erase all annotations |
fit-all |
Zoom to fit layout |
reload |
Reload layout |
top-ports |
Toggle top-level port markers |
instance-ports |
Toggle instance port markers |
dangling-ports |
Toggle dangling port markers |
text |
Toggle text labels |
theme |
Light/dark mode toggle |
Example: ?tools=ruler,top-ports,instance-ports shows only the ruler, top-level ports, and instance ports buttons.
Python Package
kwasm is available as a Python package that bundles the WASM viewer:
pip install kwasm
Jupyter Notebook
import kwasm
kwasm.show("my_chip.gds")
kwasm.show("my_chip.gds", lyp="layers.lyp", tools=("ruler", "fit-all"))
When used with gdsfactory, you can pass components directly:
import gdsfactory as gf
import kwasm
c = gf.components.mzi()
kwasm.show(c)
CLI
# Bundle a GDS into a self-contained HTML file
kwasm bundle my_chip.gds --output viewer.html --lyp layers.lyp
# Bundle and open in the default browser
kwasm view my_chip.gds
License
JavaScript Workspace (@gdsfactory/kwasm npm package)
The repo is an npm workspace; the publishable React library lives under packages/kwasm/ and the example Vite app under packages/example/.
Engines
- Node
>=22.14 - npm
>=11.5.1
Layout
packages/
kwasm/ # @gdsfactory/kwasm — publishable Vite library
example/ # Vite example app (private, not published)
Common commands
| Command | What it does |
|---|---|
npm install |
Install root + workspace dev dependencies; refresh package-lock.json |
npm run dev |
Start the example app's Vite dev server (HMR; library changes reflect via workspace symlink — Phase 5 wires the full demo) |
npm run build |
Run vite build in every workspace package that defines a build script |
npm test |
Run Vitest in every workspace package that defines test |
npm run lint |
ESLint over packages/**/*.{ts,tsx} |
npm run format |
Prettier over the workspace |
npm run ci |
Lint + format check + build + test (used by .github/workflows/ci.yml) |
WASM artifacts
The packages/kwasm/wasm/ directory holds the modular ESM glue + gzipped WASM bytes consumed by the lib at consumer build time. It is populated by just build js-lib (added in Phase 1). The bundled-HTML pipeline (just build all) is unchanged.
Tooling
- TypeScript strict;
target: ES2022,jsx: react-jsx; nopathsaliases inpackages/kwasm/src/(would leak into emitted.d.ts). - ESLint 10 flat config (
typescript-eslint,react-hooks,jsx-a11y,eslint-config-prettier). - Prettier 3.
- Pre-commit via
prek(project convention — neverpre-commit). - Vitest 4 with
unit(happy-dom) andbrowser(Playwright + Chromium) projects.
Supported consumer bundlers (v1)
Vite only. Next.js / Webpack / Rspack / esbuild are explicitly out of scope for v1 (locked in Phase 1 discussion, 2026-04-25). Other bundlers may work but are not validated in CI.
1 maintainer
Metadata
1 maintainer
Release files for kwasm 0.2.26
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| kwasm-0.2.26-py3-none-any.whl | Python 3 | none | any | Details |
Release files / kwasm-0.2.26-py3-none-any.whl
| Download URL | kwasm-0.2.26-py3-none-any.whl |
|---|---|
| Size | 6.9 MB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
c07af2bbf27335777ad604041c4c78752bf07c21c77a685a26c0de098dc47e4a
|
|
BLAKE2b-256 checksum How to use checksums |
ffa996f5b9f3ad75a4f9d3b2e36b64df013c1105729890e7c15f3d8810636f09
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.13
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Aug 20, 2026.
Transparency log
