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

• NodeJS/NPM to run local test website
• XCode >= 15.4 (If building for VisionOS)
• 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. Install pnpm and setup the project:

npm install pnpm -g
pnpm setup

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/

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.

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