Vectreal Core

Vectreal Core is a robust, community-driven, open-source toolkit designed to seamlessly integrate high-performance 3D content into React-based projects. Our mission is to empower developers, designers, and creators with comprehensive resources to build stunning, interactive 3D experiences.

The monorepo is orchestrated using NX within an npm workspaces environment, primarily consisting of React.js projects.

This project provides easy-to-use, fully configured components, hooks, and additional tools built on top of Three.js and React Three Fiber.

Table of Contents

• Vectreal Core
  • Table of Contents
  • Features
  • Project Structure
  • Packages
    • React Packages
    • Docker
  • Applications
  • Examples
  • Getting Started
    • Prerequisites
    • Installation
    • Running Projects
  • Contributing
  • License
  • Contact

Features

• Fully typed components for seamless integration with TypeScript projects
• Optimized performance for smooth 3D rendering
• Support for multiple 3D file formats (glTF, GLB, OBJ, USDZ, and more)
• Extensible architecture for custom implementations
• Comprehensive documentation and examples

Project Structure

This monorepo is organized as follows:

vectreal-core/
├── packages/
│ ├── hooks/
│ └── viewer/
├── apps/
│ └── official-website/
├── docker/
├── examples/
└── docs/

Packages

React Packages

• @vctrl/hooks: A collection of useful React hooks for loading and interacting with 3D files.

  • use-load-model: File or directory loading hooks for various approaches (Event based, React Context, direct)

  • use-optimize-model: Utilizing the gltf-transform js library to optimize models in the browser. May be used standaloe or in conjunction with the use-load-model hook for convenience.

  • use-export-model: Export the scene in multiple formats using a minimal API

• @vctrl/viewer: A fully type-safe and ready-to-use viewer component for React.

  Built with the @vctrl/hooks/use-load-model hook to dynamically load various model file types.

  Supported file formats:

  • glTF (with .bin and textures)
  • GLB
  • OBJ
  • USDZ (limited support, work in progress)

Docker

• Docker images: (Work in Progress) Easily deploy convenient Vectreal tools like file converters in your Docker environment.

Applications

• Official Website: A showcase application built using the components and software provided in this monorepo. Deployed using GitHub Actions and Google Cloud.

Examples

Visit our free online editor toolkit to see Vectreal Core in action. This interactive playground demonstrates the capabilities of our components and provides a hands-on experience for developers.

Getting Started

Prerequisites

• Node.js (v18 or later)
• npm (v9 or later)

Installation

1. Clone the repository:

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

   Install dependencies:

   npm install

Running Projects

To serve one of the app projects, use the following command:

npx nx serve vctrl/official-website

To see all available targets for a project:

npx nx show project vctrl/official-website --web

The optional --web parameter opens a visual overview of all possible commands available for a project.

For more information on working with NX, refer to the official NX documentation.

Contributing

We welcome contributions from developers passionate about React and Three.js.

To contribute:

Please read our Contributing Guidelines for more details.

1. Fork the repository
2. Create a new branch for your feature or bug fix
3. Make your changes and commit them following the commit message format described here by NX
4. Push your changes to your fork
5. Submit a pull request to the main repository

Join our Discord community for support, announcements, and discussions about the future of 3D web content.

License

GNU Affero General Public License

Please refer to the LICENSE file in the package root for licensing information.

Contact

Website: Vectreal Core | Vectreal Platform

Discord: Join our server

X/Twitter: @Vectreal

Email: [email protected]