How shapediver/appbuildersdk works
Project type and purpose
• A single-page React application (SPA) implemented in TypeScript.
• Serves as the front end (“App Builder”) for ShapeDiver: it loads a JSON “skeleton” from the ShapeDiver Platform, opens a 3D session, and renders containers, tabs, widgets and elements via React components.
• Supports theming via JSON files, and can be extended with custom widgets.
File structure
Top level:
• Configuration (.eslintrc.json, .prettierrc.json, tsconfig.json, vite.config.ts)
• Build scripts (scripts/build-appbuilder.sh)
• Public assets (public/*.json, robots.txt, manifest.json)
• src/ – the entire React codebase
– Entry points: AppBuilderRoot.tsx, ExampleRoot.tsx, LibraryRoot.tsx
– Components: AppBuilderBase.tsx, ExampleBase.tsx, LibraryBase.tsx
– Pages: HomePage, example pages (ModelSelectPage, ViewPage, etc.)
– Hooks: custom hooks for ShapeDiver sessions, parameters, UI
– State stores via zustand (session, viewport, parameters/export)
– Instrumentation: plausible, sentry, webvitals
• package.json / pnpm-lock.yaml – dependencies: React, Vite, Mantine, zustand, ShapeDiver viewer API
README for additional insights
• The app fetches a JSON “AppBuilder” data output from the ShapeDiver Platform to define its skeleton.
• Two page templates (AppShell and grid) selectable by theme property.
• Session & viewport management, parameter & export management are encapsulated in zustand stores and custom hooks.
• Theming is handled via Mantine’s theme object, overridable by passing a JSON file with the g query parameter.
• Analytics & error monitoring via plausible and Sentry.
A. Browser / Client (in user’s browser)
– Loads index.html + JS bundle from Static Hosting (e.g., CDN / GitHub Pages / shapediver.com)
– Parses query parameters (slug, ticket, modelViewUrl, g)
– If g present, fetches theme/settings JSON (from public or external URL)
– Opens a session to the ShapeDiver Platform API (using ticket or slug)
– Retrieves the “AppBuilder” skeleton JSON from the data output endpoint
– Initializes zustand stores: session store, viewport store, parameters/export store
– Instantiates React components (via AppBuilderWidgetsComponent and TemplateSelector)
– Renders 3D viewer in viewport(s) and UI widgets (parameters, exports)
– Captures analytics and errors (plausible, Sentry)
B. Static Hosting / CDNs
– Serves index.html, JS/CSS bundles, public JSON assets (example configurations, themes)
C. ShapeDiver Platform Backend
– Authentication & session management endpoints
– Data output endpoint providing skeleton JSON
– ShapeDiver 3D Viewer library (imported by SPA)
D. Build & Deployment Pipeline
– Developer machine: run pnpm start (Vite dev server)
– CI/CD: pnpm build → dist folder → pnpm run publish drives deployment to latest, staging, etc.
– scripts/build-appbuilder.sh for specialized builds
Architectural patterns & design principles
• Modular component hierarchy: Root → Base components → Widgets → UI elements
• Separation of concerns via hooks + zustand stores for state management
• Theming via external JSON and Mantine’s useProps/useTheme
• Extensibility points: skeleton type definitions + validators → new widget properties
• Single source of truth for session, viewport, parameter state