vue-threejs

A Vue 3 renderer for Three.js, ported from react-three-fiber. Declarative scene authoring with Vue composables, DOM/3D slot composition, and reactive demand rendering.

npm install @bluera/vue-threejs three vue

Quick Start

<script setup lang="ts">
import type { Mesh } from 'three'
import { Canvas, useFrame, useObjectRef } from '@bluera/vue-threejs'

const box = useObjectRef<Mesh>()

useFrame((_, delta) => {
  if (box.object.value) {
    box.object.value.rotation.x += delta
    box.object.value.rotation.y += delta * 0.5
  }
})
</script>

<template>
  <Canvas>
    <ambientLight :intensity="0.5" />
    <pointLight :position="[10, 10, 10]" />
    <mesh :ref="box.ref">
      <boxGeometry />
      <meshStandardMaterial color="orange" />
    </mesh>
  </Canvas>
</template>

Features

| | | | ---------------------- | --------------------------------------------------------------------------------- | | Declarative scenes | Vue components map directly to Three.js objects | | Fiber-compatible | Canvas, useFrame, useThree, useLoader, createPortal, extend | | Vue-native | useObjectRef, useRenderCommit, useNextFrame, watchInvalidate | | DOM + 3D | Canvas #overlay and #error slots, provide/inject across boundaries | | Demand rendering | frameloop="demand" + watchInvalidate for zero-waste rendering | | Plugin system | defineFiberPlugin for root-scoped extensions (postprocessing, physics, helpers) |

API

| Composable | Purpose | | ------------------------------------------- | ----------------------------------------------- | | useFrame(cb, priority?) | Run logic each rendered frame | | useThree(selector?) | Access renderer state (gl, scene, camera, size) | | useLoader(loader, url, ext?, onProgress?) | Load and cache assets | | useObjectRef<T>() | Raw THREE object access with lifecycle tracking | | useRenderCommit() | Wait for Vue flush + rendered frame | | useNextFrame() | Promise that resolves after one frame | | useAfterRender(cb) | Post-render hook with auto cleanup | | watchInvalidate(source, opts?) | Vue reactivity to demand-mode invalidation | | createPortal(children, container) | Render into another scene container |

• Refs are proxy-backed. instanceof works, === identity does not. Use useObjectRef for the raw object.
• Suspense keeps previous content visible during re-entrance. Use manual loading patterns for transitions.
• Events are raycaster-based, not DOM-based. Pointer capture semantics differ.

See Known Limitations and Compatibility Contract.

Ecosystem

Built-in packages ported from Poimandres:

| Package | Origin | What it provides | | -------------- | ------------------------------------------------------------------------------------------------------------ | ---------------------------------------------- | | drei | @react-three/drei | Controls, loaders, staging, materials, helpers | | postprocessing | @react-three/postprocessing | GPU postprocessing effects | | rapier | @react-three/rapier | Rigid-body physics | | test-renderer | @react-three/test-renderer | Node.js testing |

Documentation

blueraai.github.io/vue-threejs

• Installation
• Interactive Examples
• Vue-Native Patterns
• Architecture
• Support Matrix

git clone https://github.com/blueraai/vue-threejs.git
cd vue-threejs
yarn install && yarn build

yarn examples      # docs site with demos
yarn test          # test suite
yarn typecheck     # TypeScript checks
yarn eslint        # lint

License

MIT. Includes substantial code from react-three-fiber by Poimandres, licensed under the same terms. Ecosystem packages ported from drei, react-postprocessing, and react-three-rapier.