Vectreal Platform

Deployment Actions

See the viewer

NPM packages

Product Hunt

---

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.

Quick Links (External)

• Documentation
• Getting Started
• Open Publisher
• Storybook
• Discord community
• Changelog

What Is In This Repo

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
Shared libraries	shared/	Shared UI components and utilities
Infrastructure	terraform/	Google Cloud Run, CDN, IAM, and storage configuration

Documentation Map

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	GCP deployment, Terraform, and CI/CD
Contributing	Branching, commits, testing, and PR process

Workflows And Package Reference

Use these links to move between product workflows and the package APIs behind them.

Workflow guide	Package reference	Source README
Uploading Models	@vctrl/hooks	packages/hooks/README.md
Optimizing & Configuring	@vctrl/hooks, @vctrl/viewer	packages/hooks/README.md, packages/viewer/README.md
Publishing & Embedding	@vctrl/viewer, @vctrl/core	packages/viewer/README.md, packages/core/README.md
Deployment	@vctrl/core	app/routes/docs/operations/deployment.mdx

Local Development

The local setup below matches the platform documentation in Installation.

1. Clone the repository

git clone https://github.com/Vectreal/vectreal-platform.git
cd vectreal-platform

2. Install dependencies

pnpm install

3. Configure environment variables

cp .env.development.example .env.development

The 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
DATABASE_URL	PostgreSQL connection string for the local Supabase database
GOOGLE_CLOUD_STORAGE_CREDENTIALS_FILE	Path to a GCS service account JSON key
GOOGLE_CLOUD_STORAGE_PRIVATE_BUCKET	Bucket used for model assets

Google Cloud Storage is required for upload and asset-serving flows.

4. Start the local Supabase stack

pnpm supabase start
pnpm nx run vectreal-platform:supabase-db-reset

This starts local Postgres, Auth, Storage, and Studio, then applies the baseline schema.

5. Start the platform app

pnpm nx dev vectreal-platform

Open http://localhost:4200.

6. Verify the setup

1. Open the home page.
2. Create an account at /sign-up.
3. Complete onboarding and confirm you land in the dashboard.
4. Upload a model in the Publisher to verify the full asset pipeline.

Your First Model

The documented end-to-end workflow is:

1. Open the Publisher at https://vectreal.com/publisher.
2. Upload a GLB, glTF bundle, OBJ, or USDZ model.
3. Adjust quality, lighting, and camera settings.
4. Save the scene to your account.
5. Publish it to generate a stable embed URL.
6. Copy the iframe snippet into your application.

Full walkthrough: Your First Model.

Architecture Overview

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 — server-side model processing
├── shared/
│   ├── components/           # Shared Radix UI component library
│   └── utils/                # Shared utility functions
└── terraform/                # GCP infrastructure as code

The platform app uses:

• React Router v7 in framework mode with SSR
• Supabase for authentication and database
• Drizzle ORM for type-safe SQL access
• Google Cloud Storage for 3D asset storage
• @vctrl/viewer and @vctrl/hooks for the in-browser 3D pipeline

Package Overview

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	Node.js loading, optimization, and export utilities	Core docs

Deployment

Vectreal is deployed on Google Cloud Run behind a global HTTPS load balancer with CDN. Infrastructure is managed in Terraform and deployments are automated with GitHub Actions.

First-time infrastructure setup:

cd terraform
./scripts/apply-infrastructure.sh
./scripts/setup-github-secrets.sh

Database 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-prod

High-level deployment docs: https://vectreal.com/docs/operations/deployment
Canonical infrastructure details: terraform/README.md

Contributing

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

Community

• 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

License

GNU Affero General Public License v3.0.

See LICENSE.md.