Vectreal

Vectreal Platform

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.

Quick Links (External)

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

What Is In This Repo

Documentation Map

Workflows And Package Reference

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

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:

CSRF_SECRET is not in the example file and is optional locally: outside production the app falls back to a development value. Set it in production.

Model assets are stored in Supabase Storage (the assets bucket), which is created automatically on first upload. SUPABASE_URL, SUPABASE_KEY and SUPABASE_SECRET_KEY are printed by the supabase-start target in the next step.

4. Start the local Supabase stack

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

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

The Supabase project lives at apps/vectreal-platform/supabase/, so go through the Nx target rather than calling the CLI from the repo root, where it would not find config.toml.

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 model: GLB, a glTF bundle, STL, FBX, or an OBJ with its .mtl and textures.
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 organized 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 optimization 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/viewer and @vctrl/hooks for the in-browser 3D pipeline

Package Overview

Deployment

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 secrets

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/self-hosting/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.