CONTRIBUTING.md

Contributing to WebSpatial

Thank you for your interest in contributing to WebSpatial! This document provides guidelines and instructions for contributors.

Prerequisites

Required Tools

• Node.js 24+ and pnpm 11+ to install dependencies and run the local test website
• Xcode 26.x with the Apple Vision Pro simulator (current CI selects Xcode 26.3 for visionOS builds)
• VSCode Text editor (recommended)

Recommended Knowledge

Be familiar with web development and common tools like React (how to build UI) and libraries like ThreeJS (3D scene management). Would be good to know how to build a standard website first:

• ReactJS
• ThreeJS
• Ensure you can install npm packages. Try this if npm install fails

Know how to build/run an Apple vision pro app in XCode

• Hello world

Development Setup

1. Clone the repository:

git clone https://github.com/webspatial/webspatial-sdk.git
cd webspatial-sdk

2. Enable pnpm:

corepack enable
corepack prepare pnpm@11.25.0 --activate

3. Install packages and link to workspace for local development:

npm run setup

4. Start the development server:

npm run dev

5. Verify that the server is started by going to http://localhost:5173/

If you develop an external app with a linked @webspatial/react-sdk and Vite HMR (not the monorepo test-server), dedupe react / react-dom in Vite and alias the SDK to a single copy. Portal hook invariants and regression tests are documented in packages/react/src/spatialized-container/ARCHITECTURE.md (section Portal lifecycle and local dev (HMR)).

Local CodeQL-Aligned Checks

Run the fast unused-local check before opening a PR that changes TypeScript or JavaScript:

pnpm run check:unused

This runs tsc --noUnusedLocals true --noEmit across the package, test-server, and compatibility tsconfigs. It catches stale imports, local helpers, and bindings that would otherwise show up in CodeQL quality checks such as js/unused-local-variable.

For a closer local match to GitHub code scanning, install the CodeQL CLI, put codeql on your PATH, then run:

pnpm run codeql:js

The script creates a JavaScript/TypeScript database under .codeql-db/ and writes SARIF results to .codeql-results/javascript-security-and-quality.sarif. Override paths with CODEQL_DATABASE or CODEQL_OUTPUT, or set CODEQL=/path/to/codeql if the binary is not on PATH.

Testing on Apple Vision Pro Simulator

1. Open the project in Xcode:
   • It is located in /packages/visionOS/web-spatial.xcodeproj
   • Click play to launch in the simulator
   • You should now see webspatial running in the simulator
   • To set a custom initial URL, you can modify manifest.swift

Packages

• @webspatial/react-sdk - The React SDK makes the WebSpatial API immediately available inside React.
• @webspatial/core-sdk - The React SDK is implemented on top of the Core SDK, which is a framework-agnostic pure-JS API that enables the WebSpatial App Shell to natively spatialize 2D HTML content and render 3D content.
• @webspatial/builder - The build tool transforms websites into Packaged WebSpatial Apps for debugging and distributing on spatial computing platforms.

Changesets (releases)

Published packages in this monorepo are versioned with Changesets. Configuration lives in .changeset/config.json.

When you need a changeset

If your pull request changes anything under packages/ (source, package.json, platform shells, etc.), add a changeset so the release notes and semver bumps stay accurate:

1. From the repo root, run pnpm changeset (or npx changeset add).
2. Select the affected @webspatial/* packages and patch, minor, or major as appropriate. The fixed group in config bumps several packages together when any of them changes.
3. Commit the generated .changeset/<random-name>.md with your code.

You do not need a changeset for edits that only touch apps/, tests/, .github/ (unless they change published packages), docs outside packages, or other paths that do not modify packages/.

Bypass (maintainers)

For rare cases where packages/ changed but no release note or version bump should be recorded, a maintainer can add the GitHub label skip-changeset to the PR so CI allows merging without a new .changeset/*.md file. Create that label once under Issues → Labels if it does not exist yet.

License

This project is licensed under the MIT License. See the LICENSE file for details.

Licenses and Attributions

This project uses the following third-party libraries:

• tsup@8.4.0 - Licensed under the MIT
• typedoc-plugin-markdown@4.6.3 - Licensed under the MIT
• typedoc@0.26.11 - Licensed under the Apache-2.0
• typescript@5.7.3 - Licensed under the Apache-2.0
• @google/model-viewer@4.1.0 - Licensed under the Apache-2.0
• @types/hast@3.0.4 - Licensed under the MIT
• @types/lodash.isequal@4.5.8 - Licensed under the MIT
• @types/lodash@4.17.16 - Licensed under the MIT
• @types/node@22.15.2 - Licensed under the MIT
• @types/react-dom@18.3.7 - Licensed under the MIT
• @types/react@18.3.21 - Licensed under the MIT
• @types/three@0.170.0 - Licensed under the MIT
• @types/unist@3.0.3 - Licensed under the MIT
• esbuild-plugin-d.ts@1.3.1 - Licensed under the MIT
• esbuild-plugin-define@0.5.0 - Licensed under the MIT
• esbuild@0.25.3 - Licensed under the MIT
• lodash.isequal@4.5.0 - Licensed under the MIT
• react-dom@19.1.0 - Licensed under the MIT
• react@19.1.0 - Licensed under the MIT
• three@0.170.0 - Licensed under the MIT
• tiny-glob@0.2.9 - Licensed under the MIT
• webpack@5.99.8 - Licensed under the MIT
• @resvg/resvg-js@2.6.2 - Licensed under the MPL-2.0
• @rollup/plugin-terser@0.4.4 - Licensed under the MIT
• @rollup/plugin-typescript@11.1.6 - Licensed under the MIT
• @types/cli-progress@3.11.6 - Licensed under the MIT
• @types/inquirer@8.2.11 - Licensed under the MIT
• @types/mime-types@2.1.4 - Licensed under the MIT
• @types/minimist@1.2.5 - Licensed under the MIT
• @types/node-fetch@2.6.12 - Licensed under the MIT
• @types/node@12.20.55 - Licensed under the MIT
• @types/semver@7.7.0 - Licensed under the MIT
• @types/valid-url@1.0.7 - Licensed under the MIT
• cli-progress@3.12.0 - Licensed under the MIT
• colors@1.4.0 - Licensed under the MIT
• commander@13.1.0 - Licensed under the MIT
• fetch-h2@2.5.1 - Licensed under the MIT
• fs-extra@11.3.0 - Licensed under the MIT
• glob@10.4.5 - Licensed under the ISC
• inquirer@8.2.6 - Licensed under the MIT
• javascript-obfuscator@4.1.1 - Licensed under the BSD-2-Clause
• jimp@0.22.12 - Licensed under the MIT
• mime-types@2.1.35 - Licensed under the MIT
• minimist@1.2.8 - Licensed under the MIT
• node-fetch@2.6.7 - Licensed under the MIT
• rollup@3.29.5 - Licensed under the MIT
• semver@7.7.1 - Licensed under the ISC
• sharp@0.33.5 - Licensed under the Apache-2.0
• tslib@2.8.1 - Licensed under the 0BSD
• valid-url@1.0.9 - Licensed under the MIT*
• xcode@3.0.1 - Licensed under the Apache-2.0
• @gsap/react@2.1.2 - Licensed under the MIT*
• @react-spring/web@9.7.5 - Licensed under the MIT
• @reduxjs/toolkit@2.8.0 - Licensed under the MIT
• @tailwindcss/typography@0.5.16 - Licensed under the MIT
• @tweenjs/tween.js@25.0.0 - Licensed under the MIT
• @types/animejs@3.1.13 - Licensed under the MIT
• @types/react-syntax-highlighter@15.5.13 - Licensed under the MIT
• @types/redux-state-sync@3.1.10 - Licensed under the MIT
• @types/redux@3.6.0 - Licensed under the MIT
• @types/three@0.164.1 - Licensed under the MIT
• @typescript-eslint/eslint-plugin@7.18.0 - Licensed under the MIT
• @typescript-eslint/parser@7.18.0 - Licensed under the BSD-2-Clause
• @vitejs/plugin-react@4.4.1 - Licensed under the MIT
• @xterm/addon-fit@0.10.0 - Licensed under the MIT
• @xterm/xterm@5.5.0 - Licensed under the MIT
• animejs@3.2.2 - Licensed under the MIT
• autoprefixer@10.4.21 - Licensed under the MIT
• concurrently@8.2.2 - Licensed under the MIT
• daisyui@4.12.24 - Licensed under the MIT
• esbuild-css-modules-plugin@3.1.4 - Licensed under the MIT
• esbuild-plugin-tailwindcss@1.2.3 - Licensed under the MIT
• esbuild-sass-plugin@3.3.1 - Licensed under the MIT
• eslint-plugin-react-hooks@4.6.2 - Licensed under the MIT
• eslint-plugin-react-refresh@0.4.20 - Licensed under the MIT
• eslint@8.57.1 - Licensed under the MIT
• gsap@3.13.0 - Licensed under the Custom: https://gsap.com/GSAP-share-image.png
• http-server@14.1.1 - Licensed under the MIT
• livereload@0.9.3 - Licensed under the MIT
• motion@11.18.2 - Licensed under the MIT
• popmotion@11.0.5 - Licensed under the MIT
• postcss-modules@6.0.1 - Licensed under the MIT
• postcss@8.5.3 - Licensed under the MIT
• react-dom@18.3.1 - Licensed under the MIT
• react-fps@1.0.6 - Licensed under the MIT
• react-markdown@9.1.0 - Licensed under the MIT
• react-redux@9.2.0 - Licensed under the MIT
• react-router-dom@6.30.0 - Licensed under the MIT
• react-syntax-highlighter@15.6.1 - Licensed under the MIT
• react@18.3.1 - Licensed under the MIT
• redux-state-sync@3.1.4 - Licensed under the ISC
• redux@5.0.1 - Licensed under the MIT
• styled-components@6.1.17 - Licensed under the MIT
• tailwindcss@3.4.17 - Licensed under the MIT
• three@0.164.1 - Licensed under the MIT
• [web-content@0.0.5](No repository link) - Licensed under the UNLICENSED
• @eslint/js@9.26.0 - Licensed under the MIT
• @types/chai@5.2.2 - Licensed under the MIT
• @types/express@5.0.1 - Licensed under the MIT
• @types/mocha@10.0.10 - Licensed under the MIT
• @types/react-dom@19.1.3 - Licensed under the MIT
• @types/react@19.1.3 - Licensed under the MIT
• chai@5.2.0 - Licensed under the MIT
• [ci-test@0.0.4](No repository link) - Licensed under the UNLICENSED
• eslint-plugin-react-hooks@5.2.0 - Licensed under the MIT
• eslint@9.26.0 - Licensed under the MIT
• express@4.21.2 - Licensed under the MIT
• globals@16.1.0 - Licensed under the MIT
• mocha@11.2.2 - Licensed under the MIT
• tsx@4.19.3 - Licensed under the MIT
• typescript-eslint@8.32.0 - Licensed under the MIT
• vite@6.3.3 - Licensed under the MIT
• @changesets/cli@2.29.2 - Licensed under the MIT
• @eslint-community/eslint-utils@4.7.0 - Licensed under the MIT
• @eslint-community/regexpp@4.12.1 - Licensed under the MIT
• @eslint/config-array@0.20.0 - Licensed under the Apache-2.0
• @eslint/config-helpers@0.2.2 - Licensed under the Apache-2.0
• @eslint/core@0.13.0 - Licensed under the Apache-2.0
• @eslint/eslintrc@2.1.4 - Licensed under the MIT
• @eslint/object-schema@2.1.6 - Licensed under the Apache-2.0
• @eslint/plugin-kit@0.2.8 - Licensed under the Apache-2.0
• @types/eslint-scope@3.7.7 - Licensed under the MIT
• @types/eslint@9.6.1 - Licensed under the MIT
• @typescript-eslint/scope-manager@7.18.0 - Licensed under the MIT
• @typescript-eslint/type-utils@7.18.0 - Licensed under the MIT
• @typescript-eslint/types@7.18.0 - Licensed under the MIT
• @typescript-eslint/typescript-estree@7.18.0 - Licensed under the BSD-2-Clause
• @typescript-eslint/utils@7.18.0 - Licensed under the MIT
• @typescript-eslint/visitor-keys@7.18.0 - Licensed under the MIT
• @vitest/coverage-v8@3.1.2 - Licensed under the MIT
• eslint-scope@7.2.2 - Licensed under the BSD-2-Clause
• eslint-visitor-keys@3.4.3 - Licensed under the Apache-2.0
• lint-staged@15.5.1 - Licensed under the MIT
• prettier@3.5.3 - Licensed under the MIT
• simple-git-hooks@2.13.0 - Licensed under the MIT
• vitest@3.1.2 - Licensed under the MIT