webspatial-shop — Vite 电商模板

SHA-256: 3cf34aff31f7fc1d20b632a8a452a942fbc7c0e0ef9aaa677e9cd6ac197ab212

2026-10-02T19:47:44.732Z

# WebSpatial Shop

WebSpatial Shop is a React storefront demo that shows how a conventional ecommerce experience can progressively become spatial. It presents a small catalog of everyday products with responsive browsing, detail pages, thumbnail fallbacks, and WebSpatial-powered 3D model previews for supported runtimes.

The project is designed as a practical reference for building spatial web interfaces without abandoning standard web delivery. It works as a normal Vite app in desktop and mobile browsers, then upgrades product media to interactive WebSpatial models when launched in a compatible spatial environment.

## Highlights

- Responsive storefront with category filters, product cards, and product detail routes.
- Product catalog data model with prices, ratings, availability, highlights, specs, thumbnails, and GLB asset paths.
- Progressive 3D rendering through `@webspatial/react-sdk` with image fallbacks for unsupported browsers.
- Detail-page model animation using WebSpatial model refs when spatial rendering is available.
- Sample public product assets organized for static hosting and Vercel deployment.
- Vite, React, TypeScript, Tailwind CSS, and shadcn/ui-style primitives.

## Demo experience

The app behaves like a lightweight online shop:

1. Visitors land on a catalog page with department filters and featured product cards.
2. Each product card links to a detail page with price, rating, stock status, options, highlights, and specs.
3. In regular browsers, product media renders thumbnail images so the app remains fast and accessible.
4. In WebSpatial-capable runtimes, the same media component renders a WebSpatial `<Model enable-xr>` using the product GLB file.

The progressive rendering logic lives in `src/components/Model3D.tsx`. Product content and asset references live in `src/data/products.ts`.

## Tech stack

- React 19
- TypeScript
- Vite
- React Router
- Tailwind CSS
- shadcn/ui-style components
- WebSpatial SDK
- Vercel-ready static deployment

## Project structure

```text
public/
  manifest.webmanifest        Spatial launch metadata
  models/                     Product thumbnails and GLB models
src/
  components/
    Model3D.tsx               WebSpatial model renderer with image fallback
    ProductCard.tsx           Catalog card UI
    ui/                       Reusable UI primitives
  data/products.ts            Product catalog and static asset paths
  MainPage.tsx                Storefront and category filtering
  ProductPage.tsx             Product detail page and model animation
  Router.tsx                  App route definitions
```

## Prerequisites

- Node.js
- npm
- A modern browser for the standard web preview
- Optional: WebSpatial / visionOS tooling for spatial preview

## Getting started

Install dependencies:

```bash
npm install
```

Start the development server:

```bash
npm run dev
```

Open the local Vite URL, typically:

```text
http://localhost:5173
```

## Available scripts

```bash
npm run dev      # Start the Vite development server
npm run lint     # Run the TypeScript build check
npm run build    # Type-check and create a production build
npm run preview  # Build and preview the production app locally
npm run avp      # Build and launch through the WebSpatial builder flow
```

## Running with WebSpatial tooling

To validate the spatial model path, run:

```bash
npm run avp
```

This builds the app and runs:

```bash
webspatial-builder run --base=http://localhost:5173
```

Use this flow when testing the WebSpatial `<Model>` rendering behavior. Standard browsers will intentionally show thumbnail fallbacks instead.

## Building for production

```bash
npm run build
```

The production output is generated by Vite and can be served by any static host.

## Deployment

The repository includes Vercel configuration and can be deployed with:

```bash
vercel deploy --prod
```

If the repository is connected to Vercel, pushes to the production branch can trigger deployments automatically.

## Customizing the catalog

- Add or edit products in `src/data/products.ts`.
- Place thumbnails and GLB models under `public/models/`.
- Keep product asset paths relative to `import.meta.env.BASE_URL` using the existing `publicAsset` helper.
- Update storefront and product page copy in `src/MainPage.tsx` and `src/ProductPage.tsx`.
- Adjust model sizing and fallback presentation in `src/components/Model3D.css` and the page-level CSS files.

## Asset attribution

The sample catalog uses public product-style 3D assets from Poly Haven. Generated thumbnails and converted GLB files are included under `public/models` for sample convenience.

- Drill 01: <https://polyhaven.com/a/drill_01>
- Chess Set: <https://polyhaven.com/a/chess_set>
- Megaphone 01: <https://polyhaven.com/a/megaphone_01>
- Potted Plant 02: <https://polyhaven.com/a/potted_plant_02>
- Garden Gnome: <https://polyhaven.com/a/garden_gnome>
- Lubricant Spray: <https://polyhaven.com/a/lubricant_spray>

If you redistribute this project or replace the sample assets, review the license and attribution requirements for any assets you add.

## License

Source code in this repository is available under the [MIT License](LICENSE).

The included 3D assets remain subject to their source asset licenses. See [Asset attribution](#asset-attribution) for source links.