Deployment Actions
See the viewer
NPM packages
Vectreal is an open platform for preparing, managing, and publishing 3D content for the web.
This monorepo contains the full platform app, reusable React packages, shared libraries, and infrastructure code used to run Vectreal in production.
Built on Three.js, React Three Fiber, glTF-Transform, Supabase, and Nx.
| Area | Path | Purpose |
|---|---|---|
| Platform app | apps/vectreal-platform/ |
Full-stack React Router v7 app with SSR, auth, dashboard, publisher, and preview routes |
| Viewer package | packages/viewer/ |
@vctrl/viewer React 3D viewer component |
| Hooks package | packages/hooks/ |
@vctrl/hooks browser-side loading, optimization, and export hooks |
| Core package | packages/core/ |
@vctrl/core server-side model processing pipeline |
| Embed package | packages/embed/ |
@vctrl/embed framework-agnostic SDK for controlling embedded 3D scenes |
| Shared libraries | shared/ |
Shared UI components and utilities |
| Infrastructure | terraform/ |
Cloudflare DNS, Turnstile widgets, and Fly.io secret sync scripts |
| Section | What you will find |
|---|---|
| Getting Started | Local setup, prerequisites, and a first-model walkthrough |
| Guides | Upload, optimize, publish, and embed workflows |
| Package Reference | API docs for @vctrl/viewer, @vctrl/hooks, and @vctrl/core |
| Operations | Fly.io deployment, Terraform, and CI/CD |
| Contributing | Branching, commits, testing, and PR process |
Use these links to move between product workflows and the package APIs behind them.
The local setup below matches the platform documentation in Installation.
git clone https://github.com/Vectreal/vectreal-platform.git
cd vectreal-platformpnpm installcp .env.development.example .env.developmentThe main variables required for local development are:
| Variable | Description |
|---|---|
SUPABASE_URL |
Local Supabase API URL, usually http://localhost:54321 |
SUPABASE_KEY |
Supabase anon key from supabase status |
SUPABASE_SECRET_KEY |
Supabase service-role key, used server-side for asset storage |
DATABASE_URL |
PostgreSQL connection string for the local Supabase database |
CSRF_SECRET |
Long random string for CSRF token signing |
Model assets are stored in Supabase Storage (the assets bucket), which is created automatically on first upload. Values above are printed by pnpm supabase start.
pnpm supabase start
pnpm nx run vectreal-platform:supabase-db-resetThis starts local Postgres, Auth, Storage, and Studio, then applies the baseline schema.
pnpm nx dev vectreal-platformOpen http://localhost:4200.
- Open the home page.
- Create an account at
/sign-up. - Complete onboarding and confirm you land in the dashboard.
- Upload a model in the Publisher to verify the full asset pipeline.
The documented end-to-end workflow is:
- Open the Publisher at https://vectreal.com/publisher.
- Upload a GLB, glTF bundle, OBJ, or USDZ model.
- Adjust quality, lighting, and camera settings.
- Save the scene to your account.
- Publish it to generate a stable embed URL.
- Copy the iframe snippet into your application.
Full walkthrough: Your First Model.
The monorepo is organised into three layers:
vectreal-platform/
├── apps/vectreal-platform/ # Full-stack React Router v7 app (this site)
├── packages/
│ ├── viewer/ # @vctrl/viewer — React 3D viewer component
│ ├── hooks/ # @vctrl/hooks — browser-side loading and optimisation hooks
│ ├── core/ # @vctrl/core — isomorphic model processing
│ └── embed/ # @vctrl/embed — SDK for controlling embedded scenes
├── shared/
│ ├── components/ # Shared Radix UI component library
│ └── utils/ # Shared utility functions
└── terraform/ # Cloudflare DNS + Turnstile, Fly.io secret sync
The platform app uses:
- React Router v7 in framework mode with SSR
- Supabase for authentication, database, and asset storage
- Drizzle ORM for type-safe SQL access
@vctrl/viewerand@vctrl/hooksfor the in-browser 3D pipeline
| Package | Description | Docs |
|---|---|---|
@vctrl/viewer |
Ready-to-use React 3D viewer component | Viewer docs |
@vctrl/hooks |
Browser-side hooks for loading, optimizing, and exporting models | Hooks docs |
@vctrl/core |
Isomorphic (Node.js + browser) loading, optimization, and export utilities | Core docs |
@vctrl/embed |
Framework-agnostic SDK for controlling embedded 3D scenes | Embed docs |
Vectreal is deployed on Fly.io (region fra) via GitHub Actions, which builds a Docker image and deploys it with flyctl. Cloudflare fronts DNS, caching, and Turnstile bot protection; Terraform manages the Cloudflare configuration. Application secrets are synced to Fly.io from your local .env.development.
Cloudflare infrastructure and Fly.io secret setup:
cd terraform
./scripts/apply-infrastructure.sh # apply Cloudflare DNS + Turnstile config
./scripts/setup-fly-secrets.sh --env prod # sync Fly.io app secretsDatabase migration flow:
pnpm nx run vectreal-platform:drizzle-generate
pnpm nx run vectreal-platform:supabase-db-push-staging
pnpm nx run vectreal-platform:supabase-db-push-prodHigh-level deployment docs: https://vectreal.com/docs/operations/deployment
Canonical infrastructure details: terraform/README.md
We welcome contributions across code, docs, fixes, and performance improvements.
- Start with Contributing
- Read CONTRIBUTING.md
- Follow Conventional Commits
- Update docs whenever you change a public API, route, or environment variable
Useful development commands:
pnpm nx affected --target=lint
pnpm nx affected --target=test
pnpm nx test vectreal-platform- Website: https://vectreal.com
- Discord: https://discord.gg/A9a3nPkZw7
- GitHub Discussions: https://github.com/Vectreal/vectreal-platform/discussions
- GitHub Issues: https://github.com/Vectreal/vectreal-platform/issues
- X: https://x.com/vectreal
- Email: info@vectreal.com
GNU Affero General Public License v3.0.
See LICENSE.md.