WebSpatial Website & Documentation

https://github.com/webspatial/doc-website
Admin
This repository contains the source for the WebSpatial website and its documentation, built with...
Tokens:43,758
Snippets:196
Trust Score:5.6
License:MIT
Update:1 year ago
Show doc for...
Tokens:
Raw
### Install Project Dependencies

Source: https://github.com/webspatial/doc-website/blob/main/docs/quick-example/index.md

Installs the necessary dependencies for the newly created project. This step ensures that all required packages are available for development.

```bash
cd YOUR_PROJECT_PATH
npm install
```

--------------------------------

### Run Development Server

Source: https://github.com/webspatial/doc-website/blob/main/docs/quick-example/index.md

Starts the development server for the project, allowing you to preview the application in real-time. It's recommended to stop this server before proceeding with subsequent steps.

```bash
npm run dev
```

--------------------------------

### Install WebSpatial SDK and Related Packages

Source: https://github.com/webspatial/doc-website/blob/main/docs/quick-example/index.md

Installs the core WebSpatial SDK packages along with essential libraries like model-viewer and three.js, as well as development dependencies for building and platform integration. This command is crucial for enabling WebSpatial features in your project.

```bash
npm install --save @webspatial/react-sdk @webspatial/core-sdk @google/model-viewer three
npm install --save-dev @webspatial/builder @webspatial/platform-visionos @webspatial/vite-plugin vite-plugin-html
```

--------------------------------

### Install Dependencies and Start Development Server (pnpm)

Source: https://github.com/webspatial/doc-website/blob/main/README.md

Installs project dependencies using pnpm and starts a local development server for previewing the Docusaurus site. Changes are hot-reloaded.

```bash
pnpm install
pnpm start
```

--------------------------------

### Build and Start with Next.js (npm/yarn)

Source: https://github.com/webspatial/doc-website/blob/main/docs/development-guide/enabling-webspatial-in-web-projects/prerequisite-become-a-minimal-pwa/test-pwa-installability.md

Builds the React site for production and starts the local server using Next.js. This is used for testing PWA installability.

```bash
npm run build
npm run start
```

--------------------------------

### Run Vite Development Server

Source: https://github.com/webspatial/doc-website/blob/main/docs/quick-example/index.md

Commands to run the Vite development server. The first command starts a regular dev server for desktop/mobile and other non-XR platforms. The second command starts a dedicated dev server for WebSpatial, setting the XR_ENV environment variable to 'avp'.

```bash
npm run dev
```

```bash
XR_ENV=avp npm run dev
```

--------------------------------

### Install React Router DOM

Source: https://github.com/webspatial/doc-website/blob/main/docs/quick-example/index.md

This command installs the `react-router-dom` library, which is essential for implementing client-side routing in a React application. It allows for navigation between different pages without full page reloads.

```bash
npm install --save react-router-dom
```

--------------------------------

### Build and Preview with Vite (npm/yarn)

Source: https://github.com/webspatial/doc-website/blob/main/docs/development-guide/enabling-webspatial-in-web-projects/prerequisite-become-a-minimal-pwa/test-pwa-installability.md

Builds the React site for production and starts a local preview server using Vite. This is part of testing PWA installability.

```bash
npm run build
npm run preview
```

--------------------------------

### Set Default Size for Start Scene

Source: https://github.com/webspatial/doc-website/blob/main/docs/quick-example/index.md

This JSON5 configuration sets the default width and height for the start scene within the `xr_main_scene` property. This is crucial for defining the initial spatial layout of the application.

```json5
{
  "xr_main_scene": {
    "default_size": {
      "width": 500,
      "height": 1000
    }
  }
}
```

--------------------------------

### Configure Vite for WebSpatial Integration

Source: https://github.com/webspatial/doc-website/blob/main/docs/quick-example/index.md

Configure vite.config.ts to include the WebSpatial Vite plugin and the vite-plugin-html to inject the $XR_ENV environment variable. This setup is crucial for building and running WebSpatial applications.

```typescript
import { defineConfig } from "vite";
import react from "@vitejs/plugin-react";
// diff-add
import webSpatial from "@webspatial/vite-plugin";
// diff-add
import { createHtmlPlugin } from "vite-plugin-html";

// https://vite.dev/config/
export default defineConfig({
  plugins: [
    react(),
    // diff-add
    webSpatial(),
    // diff-add
    createHtmlPlugin({
      // diff-add
      inject: {
        // diff-add
        data: {
          // diff-add
          XR_ENV: process.env.XR_ENV,
          // diff-add
        },
        // diff-add
      },
      // diff-add
    }),
  ],
});
```

--------------------------------

### Run DevServer (npm/yarn)

Source: https://github.com/webspatial/doc-website/blob/main/docs/development-guide/enabling-webspatial-in-web-projects/prerequisite-become-a-minimal-pwa/test-pwa-installability.md

Launches the local development server for the React site using npm or yarn.

```bash
npm run dev
```

--------------------------------

### Create Web App Manifest File

Source: https://github.com/webspatial/doc-website/blob/main/docs/quick-example/index.md

This command creates an incomplete Web App Manifest file, which is necessary for the `webspatial-builder run` command. The manifest needs to be completed before deploying to real devices or distributing the application.

```bash
touch public/manifest.webmanifest
```

--------------------------------

### Example Techshop - Displaying Project Screenshots

Source: https://github.com/webspatial/doc-website/blob/main/docs/introduction/built-on-the-existing-web-ecosystem.md

This example showcases the 'Techshop' project, demonstrating its appearance on various platforms. It highlights how only the last screenshot, running as a Packaged WebSpatial App on visionOS, activates spatialized UI. The other screenshots depict the project running in regular browsers without WebSpatial API support, including Safari on visionOS.

```HTML
<div className="row">
  <div className="col col--6">
    <p>Large Screen</p>
    <Image img={require("/assets/intro/techshop-desktop.png")} alt="Large Screen" />
  </div>
  <div className="col col--6">
    <p>Tablet</p>
    <Image img={require("/assets/intro/techshop-pad.jpg")} alt="Tablet" />
  </div>
</div>

<div className="row">
  <div className="col col--6">
    <p>Small Window</p>
    <Image img={require("/assets/intro/techshop-small.jpg")} alt="Small Window" />
  </div>
  <div className="col col--6">
    <p>Phone</p>
    <Image img={require("/assets/intro/techshop-phone.jpg")} alt="Phone" />
  </div>
</div>

<div className="row">
  <div className="col col--6">
    <p>visionOS Safari</p>
    <Image img={require("/assets/intro/techshop-safari.png")} alt="visionOS Safari" />
  </div>
  <div className="col col--6">
    <p>WebSpatial</p>
    <Image img={require("/assets/intro/techshop-spatial.png")} alt="WebSpatial" />
  </div>
</div>
```

--------------------------------

### Create React + Vite + TypeScript Project

Source: https://github.com/webspatial/doc-website/blob/main/docs/quick-example/index.md

Initializes a new web project using Vite with React and TypeScript templates. This command sets up the basic structure for a modern web application that can integrate with the WebSpatial SDK.

```bash
npx create-vite --template react-ts
```

--------------------------------

### Run WebSpatial Builder

Source: https://github.com/webspatial/doc-website/blob/main/docs/quick-example/index.md

Command to run the WebSpatial builder, which packages and deploys the web application to the visionOS simulator. It requires the base URL of the WebSpatial development server, typically obtained from the `XR_ENV=avp npm run dev` command.

```bash
npx webspatial-builder run --base=$XR_DEV_SERVER
```

--------------------------------

### Install Core Build-Time Dependencies

Source: https://github.com/webspatial/doc-website/blob/main/docs/development-guide/enabling-webspatial-in-web-projects/step-1-install-the-webspatial-sdk.md

Installs the WebSpatial builder package, which is crucial for packaging your website into a Packaged WebSpatial App for visionOS development and distribution.

```bash
npm install -D @webspatial/builder
```

--------------------------------

### Create React Project with Rsbuild and TypeScript

Source: https://github.com/webspatial/doc-website/blob/main/docs/development-guide/web-projects-that-support-webspatial/creating-new-web-projects.md

This command initializes a new React project using Rsbuild with TypeScript support. It provides a robust setup for modern web development.

```bash
npx create-rsbuild --template react-ts
```

--------------------------------

### Run Dev Server with webspatial-builder

Source: https://github.com/webspatial/doc-website/blob/main/docs/development-guide/enabling-webspatial-in-web-projects/step-3-integrate-webspatial-sdk-into-web-build-tools/generate-a-webspatial-specific-website.md

This command uses npx to run the webspatial-builder with a specified base URL, which is crucial for packaging and installing a visionOS app in the simulator.

```bash
npx webspatial-builder run --base=http://localhost:3001/webspatial/avp/
```

--------------------------------

### Install Next.js Plugin

Source: https://github.com/webspatial/doc-website/blob/main/docs/development-guide/enabling-webspatial-in-web-projects/step-1-install-the-webspatial-sdk.md

Installs the WebSpatial Next.js plugin for React + Next.js projects. It integrates required optimizations and defaults for WebSpatial when using Next.js.

```bash
npm install -D @webspatial/next-plugin
```

--------------------------------

### Web App Manifest start_url Example

Source: https://github.com/webspatial/doc-website/blob/main/docs/development-guide/enabling-webspatial-in-web-projects/step-2-add-build-tool-for-packaged-webspatial-apps/options-of-the-webspatial-builder.md

Illustrates how the `start_url` in a Web App Manifest interacts with the `--base` option. The `start_url` defines the entry point of the web application, and the `--base` option prepends a specified root path to it.

```json
"start_url": "/home"
```

--------------------------------

### Install Core Runtime Dependencies

Source: https://github.com/webspatial/doc-website/blob/main/docs/development-guide/enabling-webspatial-in-web-projects/step-1-install-the-webspatial-sdk.md

Installs the essential runtime packages for the WebSpatial SDK, including React and Core SDKs, along with model-viewer and three.js. These are necessary for enabling WebSpatial features in your project.

```bash
npm install @webspatial/react-sdk @webspatial/core-sdk @google/model-viewer three
```

--------------------------------

### Initialize Scene with Custom Size (React)

Source: https://github.com/webspatial/doc-website/blob/main/docs/quick-example/index.md

Initializes a scene named 'secondScene' with a custom default size before it opens. This uses the `initScene` API from the WebSpatial React SDK. It also opens the scene in a new window.

```jsx
import { initScene } from "@webspatial/react-sdk";
```

```jsx
initScene("secondScene", prevConfig => {
  return {
    ...prevConfig,
    defaultSize: {
      width: 500,
      height: 500,
    },
  };
});
window.open(`${__XR_ENV_BASE__}/second-page`, "secondScene");
```

--------------------------------

### Create Second Page Component (React)

Source: https://github.com/webspatial/doc-website/blob/main/docs/quick-example/index.md

This React component, `SecondPage.tsx`, demonstrates a simple counter functionality using the `useState` hook. It serves as an example for creating new pages within a WebSpatial application.

```jsx
import { useState } from "react";
import "./App.css";

function SecondPage() {
  const [count, setCount] = useState(0);

  return (
    <div className="App">
      <h1>Second Page</h1>
      <div className="card">
        <button onClick={() => setCount(count => count + 1)}>
          count is {count}
        </button>
      </div>
    </div>
  );
}

export default SecondPage;
```

--------------------------------

### Configure Routing in App.tsx (React)

Source: https://github.com/webspatial/doc-website/blob/main/docs/quick-example/index.md

This JSX code snippet shows how to set up client-side routing using `react-router-dom` in the main `App.tsx` file. It defines routes for the home page and a new `/second-page`, integrating the `SecondPage` component.

```jsx
import { BrowserRouter as Router, Routes, Route, Link } from "react-router-dom";
import SecondPage from "./SecondPage";

  return (
    //diff-add
    <Router basename={__XR_ENV_BASE__}>
      //diff-add
      <Routes>
      //diff-add
        <Route path="/second-page" element={<SecondPage />} />
      //diff-add
        <Route
      //diff-add
          path="/"
      //diff-add
          element={
            /* Move all JSX from the App component in src/App.tsx into here */
      //diff-add
          }
      //diff-add
        />
      //diff-add
      </Routes>
      //diff-add
    </Router>
  );
```

--------------------------------

### Install Rsbuild Plugin

Source: https://github.com/webspatial/doc-website/blob/main/docs/development-guide/enabling-webspatial-in-web-projects/step-1-install-the-webspatial-sdk.md

Installs the WebSpatial Rsbuild plugin for React + Rsbuild projects. This plugin provides essential optimizations and defaults for WebSpatial when Rsbuild is used as the build tool.

```bash
npm install -D @webspatial/rsbuild-plugin
```

--------------------------------

### Example HTML Asset Paths for visionOS

Source: https://github.com/webspatial/doc-website/blob/main/docs/development-guide/enabling-webspatial-in-web-projects/step-3-integrate-webspatial-sdk-into-web-build-tools/generate-a-webspatial-specific-website.md

Illustrates typical HTML asset paths when deploying the visionOS version, including favicon, apple touch icon, and script/stylesheet references with the '/webspatial/avp/' prefix.

```html
<link rel="icon" href="/webspatial/avp/favicon.ico" sizes="any" />
<link
  rel="apple-touch-icon"
  href="/webspatial/avp/icons/apple-touch-icon.png" />
<script
  type="module"
  crossorigin
  src="/webspatial/avp/assets/index-CpANHSXr.js"></script>
<link
  rel="stylesheet"
  crossorigin
  href="/webspatial/avp/assets/index-B4Bp50KL.css" />
```

--------------------------------

### Install Rspack Plugin

Source: https://github.com/webspatial/doc-website/blob/main/docs/development-guide/enabling-webspatial-in-web-projects/step-1-install-the-webspatial-sdk.md

Installs the WebSpatial Rspack plugin for React + Rspack projects. It ensures that the required optimizations and defaults are applied when using Rspack as the build tool.

```bash
npm install -D @webspatial/rspack-plugin
```

--------------------------------

### Install visionOS Platform Support

Source: https://github.com/webspatial/doc-website/blob/main/docs/development-guide/enabling-webspatial-in-web-projects/step-1-install-the-webspatial-sdk.md

Installs the platform-specific package for visionOS, which includes the WebSpatial App Shell required to generate a visionOS app and provide spatial capabilities. This is currently mandatory for visionOS development.

```bash
npm install -D  @webspatial/platform-visionos
```

--------------------------------

### Deploying WebSpatial Version with GitHub Pages (Shell)

Source: https://github.com/webspatial/doc-website/blob/main/docs/development-guide/enabling-webspatial-in-web-projects/step-3-integrate-webspatial-sdk-into-web-build-tools/generate-a-webspatial-specific-website.md

This shell command installs the `gh-pages` package as a development dependency and then uses it to deploy the contents of the `dist/webspatial/avp` directory to GitHub Pages.

```shell
npm install -D gh-pages
gh-pages -d dist/webspatial/avp
```

--------------------------------

### Install Vite Plugin

Source: https://github.com/webspatial/doc-website/blob/main/docs/development-guide/enabling-webspatial-in-web-projects/step-1-install-the-webspatial-sdk.md

Installs the WebSpatial Vite plugin for React + Vite projects. This plugin adds necessary optimizations and defaults for WebSpatial development when using Vite as the build tool.

```bash
npm install -D @webspatial/vite-plugin
```

--------------------------------

### Install Dependencies (npm)

Source: https://github.com/webspatial/doc-website/blob/main/docs/development-guide/enabling-webspatial-in-web-projects/step-2-add-build-tool-for-packaged-webspatial-apps/optional-simplify-webspatial-builder-using-dotenv.md

Installs the necessary dotenv and dotenv-cli packages as development dependencies for managing environment variables in npm scripts.

```bash
npm install -D dotenv dotenv-cli
```

--------------------------------

### Configure JSX Compilation for WebSpatial SDK

Source: https://github.com/webspatial/doc-website/blob/main/docs/quick-example/index.md

Modify tsconfig.app.json and tsconfig.node.json to set the jsxImportSource to '@webspatial/react-sdk' for proper JSX compilation with the WebSpatial SDK.

```json
{
  "compilerOptions": {
    // diff-add
    "jsxImportSource": "@webspatial/react-sdk"
  }
}
```

--------------------------------

### WebSpatial Scene Initialization Example

Source: https://github.com/webspatial/doc-website/blob/main/docs/core-concepts/scenes-and-spatial-layouts.md

Demonstrates how developers can provide preferred initial values for scene properties like default size. The OS ultimately controls these properties based on user actions and environmental context.

```JavaScript
const scene = new Scene({ defaultSize: { width: 1, height: 1, depth: 1 } });
```

--------------------------------

### Add Navigation Links/Buttons (React)

Source: https://github.com/webspatial/doc-website/blob/main/docs/quick-example/index.md

This React code adds a section to the `App.tsx` file that includes a link and a button for navigating to the `/second-page`. The link opens the page in a new tab, while the button uses `window.open` to open it in a new window with a specified name.

```jsx
              <p className="read-the-docs">
                Click on the Vite and React logos to learn more
              </p>
              <div className="card" style={{ marginTop: "0px" }}>
                <h2>Open Second Page</h2>
                <p>
                  <Link to="/second-page" target="_blank">
                    Open Second Page with a Link
                  </Link>
                </p>
                <p>
                  <button
                    onClick={() => {
                      window.open(`${__XR_ENV_BASE__}/second-page`, "secondScene");
                    }}>
                    Open Second Page with a Button
                  </button>
                </p>
              </div>
```

--------------------------------

### WebSpatial Start Scene Configuration

Source: https://github.com/webspatial/doc-website/blob/main/docs/core-concepts/scenes-and-spatial-layouts.md

Illustrates how the initial scene's type and configuration are set via the Web App Manifest's start_url property. This defines the first page loaded when a WebSpatial app launches.

```JSON
{
  "start_url": "/index.html",
  "display": "fullscreen",
  "web_app_spatial": {
    "scenes": [
      {
        "type": "window",
        "initialConfiguration": {
          "defaultSize": {
            "width": 0.8,
            "height": 0.6,
            "depth": 0.1
          }
        }
      }
    ]
  }
}
```

--------------------------------

### Set Transparent Background for XR_ENV Mode (CSS)

Source: https://github.com/webspatial/doc-website/blob/main/docs/quick-example/index.md

Sets the background of the HTML element to transparent and defines the '--xr-background-material' CSS variable for elements in XR_ENV mode. This allows for custom material backgrounds in WebSpatial applications.

```css
html.is-spatial {
  background-color: transparent;
  --xr-background-material: transparent;
}
```

--------------------------------

### Elevate Elements with CSS --xr-back (CSS)

Source: https://github.com/webspatial/doc-website/blob/main/docs/quick-example/index.md

This CSS code targets elements within a `.count-card` and `.link-card` to control their appearance and position in WebSpatial. It uses `--xr-background-material` for visual effects and `--xr-back` to position elements along the Z-axis, effectively 'elevating' them.

```css
.count-card {
    --xr-background-material: thick;
    position: relative;

    p {
      --xr-background-material: transparent;
      position: absolute;
      bottom: -10px;
      left: 0;
      right: 0;
      --xr-back: 20;
    }
  }

  .link-card {
    --xr-background-material: translucent;
    border-radius: 20px;
    position: relative;
    --xr-back: 50;
    top: 20px;
```

--------------------------------

### Web App Manifest for WebSpatial Configuration

Source: https://github.com/webspatial/doc-website/blob/main/docs/introduction/built-on-the-existing-web-ecosystem.md

Defines application-level configurations for a WebSpatial application using the Web App Manifest, a PWA standard. This includes setting the start URL, display mode, main XR scene configuration with default size, and application icons.

```json
{
  "name": "TechShop - Premium Tech Products",
  "start_url": "/",
  "scope": "/",
  "display": "minimal-ui",
  "xr_main_scene": {
    "default_size": {
      "width": 1700,
      "height": 1200
    }
  },
  "icons": [

```

--------------------------------

### Transform and Rotate Elements with CSS (CSS)

Source: https://github.com/webspatial/doc-website/blob/main/docs/quick-example/index.md

This CSS snippet shows how to apply transformations to a `.link-card` element to position and orient it in 3D space. It sets a `transform-origin` and then uses `translateZ` and `rotateX` to move the element along the Z-axis and rotate it around the X-axis.

```css
.link-card {
    --xr-background-material: translucent;
    border-radius: 20px;
    position: relative;
    --xr-back: 50;
    top: 20px;
    //diff-add
    transform-origin: top left;
//diff-add
    transform: translateZ(30px) rotateX(30deg);
```

--------------------------------

### Configure Start Scene Size in Web App Manifest

Source: https://github.com/webspatial/doc-website/blob/main/docs/development-guide/using-the-webspatial-api/manage-multiple-scenes.md

This JSON snippet demonstrates how to configure the initial size of the main scene in a WebSpatial application by adding the `xr_main_scene` property to the Web App Manifest. It specifies the default width and height for the scene.

```json
{
  "start_url": "/",
  "xr_main_scene": {
    "default_size": {
      "width": 500,
      "height": 1000
    }
  }
}
```

--------------------------------

### Controlling HTML Output for WebSpatial

Source: https://github.com/webspatial/doc-website/blob/main/docs/development-guide/web-projects-that-support-webspatial/index.md

This conceptual example illustrates how a web server might serve tailored HTML for WebSpatial. It shows the inclusion of a specific App Shell script, which loads the WebSpatial SDK, enabling spatial computing features for the user.

```html
<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>WebSpatial App</title>
    <!-- Link to your project's CSS -->
    <link rel="stylesheet" href="/styles.css">
</head>
<body>
    <div id="root"></div>
    <!-- WebSpatial App Shell Script -->
    <script type="module" src="/webspatial-app-shell.js"></script>
    <!-- Your project's main JavaScript bundle -->
    <script type="module" src="/main.js"></script>
</body>
</html>
```

--------------------------------

### Create React Project with Vite

Source: https://github.com/webspatial/doc-website/blob/main/docs/development-guide/web-projects-that-support-webspatial/creating-new-web-projects.md

This command initializes a new React project using Vite, a fast build tool. It sets up the basic structure for a modern web application.

```bash
npx create-vite --template react
```

--------------------------------

### Environment Variables (.env.example)

Source: https://github.com/webspatial/doc-website/blob/main/docs/development-guide/enabling-webspatial-in-web-projects/step-2-add-build-tool-for-packaged-webspatial-apps/optional-simplify-webspatial-builder-using-dotenv.md

This snippet shows the structure of a .env.example file, which should be committed to Git. It lists common environment variables used by the WebSpatial Builder.

```ini
XR_DEV_SERVER=
XR_PRE_SERVER=
XR_PROD_SERVER=
XR_BUNDLE_ID=
XR_TEAM_ID=
XR_VERSION=
XR_DEV_NAME=
XR_DEV_PASSWORD=
```

--------------------------------

### Install pnpm Globally with npm

Source: https://github.com/webspatial/doc-website/blob/main/docs/development-guide/web-projects-that-support-webspatial/adding-pnpm.md

This command installs the pnpm package manager globally using npm.

```bash
npm install -g pnpm
```

--------------------------------

### Install TailwindCSS and PostCSS Dependencies

Source: https://github.com/webspatial/doc-website/blob/main/docs/development-guide/web-projects-that-support-webspatial/adding-tailwindcss-and-postcss.md

Installs TailwindCSS, PostCSS, and Autoprefixer as development dependencies using npm or yarn.

```bash
npm install -D tailwindcss postcss autoprefixer
```

```bash
yarn add -D tailwindcss postcss autoprefixer
```

--------------------------------

### Create Production Build (pnpm)

Source: https://github.com/webspatial/doc-website/blob/main/README.md

Generates a production-ready static site build for deployment. The output is placed in the 'build/' directory.

```bash
pnpm run build
```

--------------------------------

### Install vite-plugin-html

Source: https://github.com/webspatial/doc-website/blob/main/docs/development-guide/enabling-webspatial-in-web-projects/step-3-integrate-webspatial-sdk-into-web-build-tools/check-if-running-in-webspatial-mode.md

Demonstrates the command to install the vite-plugin-html package using npm, which is a necessary step for injecting environment variables into HTML files during the Vite build process.

```bash
npm install -D vite-plugin-html
```

--------------------------------

### Create React Project with Rspack

Source: https://github.com/webspatial/doc-website/blob/main/docs/development-guide/web-projects-that-support-webspatial/creating-new-web-projects.md

This command sets up a new React project using Rspack, a fast Rust-based bundler. This template is for JavaScript projects.

```bash
npx create-rspack --template react
```

--------------------------------

### Generate pnpm-lock.yaml

Source: https://github.com/webspatial/doc-website/blob/main/docs/development-guide/web-projects-that-support-webspatial/adding-pnpm.md

These commands remove the existing node_modules directory and then install dependencies using pnpm, which automatically generates the pnpm-lock.yaml file.

```bash
rm -rf node_modules
pnpm install
```

--------------------------------

### Create React Project with Next.js

Source: https://github.com/webspatial/doc-website/blob/main/docs/development-guide/web-projects-that-support-webspatial/creating-new-web-projects.md

This command sets up a new React project using Next.js, a popular React framework for server-side rendering and static site generation. This version is for JavaScript projects.

```bash
npx create-next-app --js
```

--------------------------------

### Create React Project with Rspack and TypeScript

Source: https://github.com/webspatial/doc-website/blob/main/docs/development-guide/web-projects-that-support-webspatial/creating-new-web-projects.md

This command initializes a new React project using Rspack with TypeScript support. It leverages Rspack's performance for building React applications.

```bash
npx create-rspack --template react-ts
```

--------------------------------

### Create React Project with Vite and TypeScript

Source: https://github.com/webspatial/doc-website/blob/main/docs/development-guide/web-projects-that-support-webspatial/creating-new-web-projects.md

This command initializes a new React project using Vite with TypeScript support. It's suitable for projects requiring static typing.

```bash
npx create-vite --template react-ts
```

--------------------------------

### Add npm Scripts for pnpm Operations

Source: https://github.com/webspatial/doc-website/blob/main/docs/development-guide/web-projects-that-support-webspatial/adding-pnpm.md

This snippet shows how to add custom npm scripts to your package.json file to streamline common pnpm operations like clean installs and updates.

```json5
"install:clean": "rm -rf node_modules && pnpm install",
"install:update": "rm -rf node_modules pnpm-lock.yaml package-lock.json && pnpm install"
```

--------------------------------

### Media Component with Various Icon States

Source: https://github.com/webspatial/doc-website/blob/main/src/theme/IdealImageLegacy/components/MediaWithDefaults/README.md

This HTML snippet demonstrates the usage of a `MediaWithDefaults` component, showcasing different states by passing various `icon` prop values. Each instance uses the defined `lqip` for a placeholder and a common image source, illustrating how the component handles states like 'load', 'noicon', 'loading', 'offline', 'loaded', and 'error'.

```html
<table>
  <tbody>
    <tr>
      <th align="left" width="100">
        load
      </th>
      <td>
        <MediaWithDefaults
          width={3500}
          height={2095}
          placeholder={{lqip: lqip}}
          src="andre-spieker-238-unsplash.jpg"
          style={{maxWidth: 200}}
          icon={'load'}
        />
      </td>
      <th align="left" width="100">
        noicon
      </th>
      <td>
        <MediaWithDefaults
          width={3500}
          height={2095}
          placeholder={{lqip: lqip}}
          src="andre-spieker-238-unsplash.jpg"
          style={{maxWidth: 200}}
          icon={'noicon'}
        />
      </td>
    </tr>
    <tr>
      <th align="left">loading</th>
      <td>
        <MediaWithDefaults
          width={3500}
          height={2095}
          placeholder={{lqip: lqip}}
          src="andre-spieker-238-unsplash.jpg"
          style={{maxWidth: 200}}
          icon={'loading'}
        />
      </td>
      <th align="left">offline</th>
      <td>
        <MediaWithDefaults
          width={3500}
          height={2095}
          placeholder={{lqip: lqip}}
          src="andre-spieker-238-unsplash.jpg"
          style={{maxWidth: 200}}
          icon={'offline'}
        />
      </td>
    </tr>
    <tr>
      <th align="left">loaded</th>
      <td>
        <MediaWithDefaults
          width={3500}
          height={2095}
          placeholder={{lqip: lqip}}
          src="andre-spieker-238-unsplash.jpg"
          style={{maxWidth: 200}}
          icon={'loaded'}
        />
      </td>
      <th align="left">error</th>
      <td>
        <MediaWithDefaults
          width={3500}
          height={2095}
          placeholder={{lqip: lqip}}
          src="andre-spieker-238-unsplash.jpg"
          style={{maxWidth: 200}}
          icon={'error'}
        />
      </td>
    </tr>
  </tbody>
</table>
```

--------------------------------

### Create React Project with Next.js and TypeScript

Source: https://github.com/webspatial/doc-website/blob/main/docs/development-guide/web-projects-that-support-webspatial/creating-new-web-projects.md

This command initializes a new React project using Next.js with TypeScript support. It's ideal for building scalable React applications with static typing.

```bash
npx create-next-app --ts
```

--------------------------------

### WebSpatial Rspack Plugin Integration

Source: https://github.com/webspatial/doc-website/blob/main/docs/development-guide/web-projects-that-support-webspatial/index.md

This example shows how to integrate the WebSpatial plugin with Rspack, a fast and powerful build tool. This integration is recommended for Rspack projects to enhance their WebSpatial capabilities.

```javascript
import { defineConfig } from '@rspack/core';
import { pluginReact } from '@rspack/plugin-react';
import { pluginWebSpatial } from '@webspatial/rspack-plugin'; // Assuming this is the plugin path

export default defineConfig({
  plugins: [
    pluginReact(),
    pluginWebSpatial(), // Add the WebSpatial plugin here
  ],
});
```

--------------------------------

### Node.js NestJS Dynamic Web Server

Source: https://github.com/webspatial/doc-website/blob/main/docs/development-guide/enabling-webspatial-in-web-projects/step-3-integrate-webspatial-sdk-into-web-build-tools/generate-a-webspatial-specific-website.md

Example of a Node.js server using the NestJS framework to dynamically serve WebSpatial application files. It checks the User-Agent string to serve content from different directories.

```typescript
import { NestFactory } from '@nestjs/core';
import { AppModule } from './app.module';
import * as express from 'express';
import * as path from 'path';

async function bootstrap() {
  const app = await NestFactory.create(AppModule);

  // Serve static files
  app.use('/static', express.static(path.join(__dirname, '..', 'public', 'static')));

  // Dynamic serving based on User-Agent
  app.use((req, res, next) => {
    const userAgent = req.headers['user-agent'];
    if (userAgent && userAgent.includes('WebSpatialAppShell')) {
      // Serve from dist/webspatial/avp for WebSpatial App Shell
      res.sendFile(path.join(__dirname, '..', 'dist', 'webspatial', 'avp', 'index.html'));
    } else {
      // Serve from dist/ for other users
      res.sendFile(path.join(__dirname, '..', 'dist', 'index.html'));
    }
  });

  await app.listen(3000);
  console.log('Server is running on port 3000');
}
bootstrap();

```

--------------------------------

### Create React Project with Rsbuild

Source: https://github.com/webspatial/doc-website/blob/main/docs/development-guide/web-projects-that-support-webspatial/creating-new-web-projects.md

This command creates a new React project using Rsbuild, a fast and powerful build tool. This template is for JavaScript projects.

```bash
npx create-rsbuild --template react
```

--------------------------------

### Load Environment Variables in Vite (Node.js Scripts)

Source: https://github.com/webspatial/doc-website/blob/main/docs/development-guide/enabling-webspatial-in-web-projects/step-2-add-build-tool-for-packaged-webspatial-apps/optional-simplify-webspatial-builder-using-dotenv.md

Provides an example of using Vite's `loadEnv` function in other Node.js scripts to access environment variables, ensuring consistency across your project.

```javascript
import { loadEnv } from "vite";

const env = loadEnv("", process.cwd(), "");

console.log(env.XR_ENV);
```

--------------------------------

### React Router Setup with Base Path

Source: https://github.com/webspatial/doc-website/blob/main/docs/development-guide/enabling-webspatial-in-web-projects/step-3-integrate-webspatial-sdk-into-web-build-tools/generate-a-webspatial-specific-website.md

This JSX code shows how to configure react-router-dom by setting the 'basename' prop to '__XR_ENV_BASE__'. This ensures that all client-side routing within the application correctly handles the base path.

```jsx
  return (
    <Router basename={__XR_ENV_BASE__}>
      <Routes>

```

--------------------------------

### Add Dedicated Dev Server npm Script

Source: https://github.com/webspatial/doc-website/blob/main/docs/development-guide/enabling-webspatial-in-web-projects/step-3-integrate-webspatial-sdk-into-web-build-tools/generate-a-webspatial-specific-website.md

Demonstrates how to add a dedicated npm script for the WebSpatial development server. This best practice simplifies the process of running the build with the necessary environment variables.

```json
"dev": "vite",
"dev:avp": "XR_ENV=avp vite"
```

--------------------------------

### WebSpatial Next.js Plugin Integration

Source: https://github.com/webspatial/doc-website/blob/main/docs/development-guide/web-projects-that-support-webspatial/index.md

This example shows how to integrate the WebSpatial plugin with Next.js, a framework for building React applications. This integration is recommended for Next.js projects to leverage WebSpatial's capabilities efficiently.

```javascript
// next.config.js
const withWebSpatial = require('@webspatial/nextjs-plugin'); // Assuming this is the plugin path

module.exports = withWebSpatial({
  // Your Next.js configuration options
});
```

--------------------------------

### Deploy to GitHub Pages (pnpm)

Source: https://github.com/webspatial/doc-website/blob/main/README.md

Command to deploy the static site to GitHub Pages or other static hosting platforms.

```bash
pnpm run deploy
```

--------------------------------

### Add XR_ENV Class for Spatial Mode (HTML)

Source: https://github.com/webspatial/doc-website/blob/main/docs/quick-example/index.md

Modifies the root HTML element to include the 'is-spatial' class when the application is running in the XR_ENV mode. This is used to apply specific CSS styles for WebSpatial environments.

```html
<html lang="en" class="is-spatial">
//diff-add
  ` : `
    <html lang="en">
//diff-add
    
```

--------------------------------

### Apply Translucent Material Backgrounds to Cards (CSS)

Source: https://github.com/webspatial/doc-website/blob/main/docs/quick-example/index.md

Defines specific translucent material backgrounds for 'count-card' and 'link-card' elements, as well as their nested links, within the 'is-spatial' context. This customizes the appearance of spatilized elements in WebSpatial.

```css
html.is-spatial {
  background-color: transparent;
  --xr-background-material: transparent;

  .count-card {
    --xr-background-material: thick;
    position: relative;
  }

  .link-card {
    --xr-background-material: translucent;
    border-radius: 20px;
    position: relative;
    top: 20px;

    a {
      display: block;
      --xr-background-material: thick;
      border-radius: 10px;
    }
  }
}
```

--------------------------------

### Web App Manifest start_url Configuration

Source: https://github.com/webspatial/doc-website/blob/main/docs/development-guide/enabling-webspatial-in-web-projects/step-2-add-build-tool-for-packaged-webspatial-apps/options-of-the-webspatial-builder.md

The `start_url` in the Web App Manifest defines the entry point for the WebSpatial application. When used with the `--base` argument, it determines the final URL accessed by the app shell. If `start_url` is a full URL, `--base` might be ignored or used to prepend a different domain.

```json
"start_url": "/home"
```

```json
"start_url": "http://otherdomain.com/home"
```

--------------------------------

### Run Dev Server with npm script and XR_DEV_SERVER

Source: https://github.com/webspatial/doc-website/blob/main/docs/development-guide/enabling-webspatial-in-web-projects/step-3-integrate-webspatial-sdk-into-web-build-tools/generate-a-webspatial-specific-website.md

This command sets the XR_DEV_SERVER environment variable to the dedicated Dev Server URL and then runs the 'run:avp' npm script, achieving the same goal as the previous command.

```bash
XR_DEV_SERVER=http://localhost:3001/webspatial/avp/ npm run run:avp
```

--------------------------------

### Configure Dev Server Base URL ($XR_DEV_SERVER)

Source: https://github.com/webspatial/doc-website/blob/main/docs/development-guide/enabling-webspatial-in-web-projects/step-2-add-build-tool-for-packaged-webspatial-apps/options-of-the-webspatial-builder.md

Sets the root part of the URL for HTML requests in the WebSpatial App Shell. If `start_url` in the Web App Manifest is a full URL, it will be replaced by this base URL. This is useful for directing requests to a dedicated development server, enabling hot reloading and faster iteration.

```bash
export XR_DEV_SERVER="http://localhost:3000/webspatial/avp/"
```
Tokens:
Raw