{"id":15487,"library":"troisjs","title":"TroisJS: Three.js for Vue 3","description":"TroisJS is a powerful and lightweight library designed to facilitate the creation of 3D graphics and animations within Vue 3 applications, leveraging the capabilities of Three.js and the performance benefits of Vite. Currently stable at version 0.3.4, the library maintains a relatively active release cadence, frequently pushing bug fixes and minor features as seen in recent patch versions (e.g., 0.3.4, 0.3.2). Its primary differentiator is providing a `react-three-fiber`-like component-based API specifically tailored for the Vue ecosystem, allowing developers to compose complex Three.js scenes declaratively using Vue components. It ships with comprehensive TypeScript types, ensuring robust development and better maintainability for large-scale projects. The library aims to abstract away much of the boilerplate associated with direct Three.js integration into a Vue environment, making 3D development more accessible to Vue developers.","status":"active","version":"0.3.4","language":"javascript","source_language":"en","source_url":"https://github.com/troisjs/trois","tags":["javascript","threejs","vuejs","webgl","vitejs","typescript"],"install":[{"cmd":"npm install troisjs","lang":"bash","label":"npm"},{"cmd":"yarn add troisjs","lang":"bash","label":"yarn"},{"cmd":"pnpm add troisjs","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"TroisJS is a Vue 3 component library and requires Vue as a peer dependency.","package":"vue","optional":false},{"reason":"TroisJS is a wrapper around Three.js and depends on it for 3D rendering capabilities.","package":"three","optional":false}],"imports":[{"note":"This named export is the primary way to register all TroisJS components globally with your Vue 3 application via `app.use()`.","wrong":"import TroisJSVuePlugin from 'troisjs'","symbol":"TroisJSVuePlugin","correct":"import { TroisJSVuePlugin } from 'troisjs'"},{"note":"While components are typically registered via `TroisJSVuePlugin`, you can also import them individually as named exports for local component registration or specific use cases, benefiting from tree-shaking. Other components like `Camera`, `Scene`, `Box`, `PointLight`, etc., follow the same named import pattern.","wrong":"import Renderer from 'troisjs'","symbol":"Renderer","correct":"import { Renderer } from 'troisjs'"},{"note":"This composition API hook allows access to the Three.js renderer instance within a Vue component, useful for imperative Three.js operations.","symbol":"useRenderer","correct":"import { useRenderer } from 'troisjs'"}],"quickstart":{"code":"import { createApp } from 'vue'\nimport { TroisJSVuePlugin } from 'troisjs'\nimport { ref, onMounted } from 'vue'\n\nconst app = createApp({\n  template: `\n    <renderer ref=\"rendererRef\" antialias orbit-ctrl resize=\"window\">\n      <camera :position=\"{ z: 10 }\"></camera>\n      <scene>\n        <point-light :position=\"{ y: 50, z: 50 }\"></point-light>\n        <box ref=\"boxRef\" :rotation=\"{ y: rotation.y, z: rotation.z }\">\n          <lambert-material></lambert-material>\n        </box>\n      </scene>\n    </renderer>\n  `,\n  setup() {\n    const rendererRef = ref(null)\n    const boxRef = ref(null)\n    const rotation = ref({ y: Math.PI / 4, z: Math.PI / 4 })\n\n    onMounted(() => {\n      // Access the Three.js scene, camera, etc. via rendererRef.value.scene, etc.\n      if (rendererRef.value && boxRef.value) {\n        console.log('Renderer and Box components mounted.')\n        // Example: animate box rotation\n        rendererRef.value.onBeforeRender(() => {\n          rotation.value.y += 0.01\n          rotation.value.z += 0.005\n        })\n      }\n    })\n\n    return { rendererRef, boxRef, rotation }\n  }\n})\n\napp.use(TroisJSVuePlugin).mount('#app')","lang":"typescript","description":"This quickstart demonstrates a basic TroisJS setup using Vue 3's `createApp` and `script setup` composition API. It initializes a 3D scene with a camera, light, and a rotating box, showing how to register TroisJS components globally via `TroisJSVuePlugin` and access Three.js objects for animation."},"warnings":[{"fix":"Review the type definitions and adjust component props or API calls to match the new TypeScript interfaces. Ensure your project's TypeScript configuration is set up correctly for Vue components.","message":"Version 0.3.0 introduced TypeScript support. While not explicitly listed as a breaking change in the changelog for this specific transition, users migrating from pre-0.3.0 JavaScript versions to 0.3.0+ TypeScript projects might encounter type-related issues or require adjustments to their codebase to conform to new type definitions and stricter API contracts.","severity":"breaking","affected_versions":">=0.3.0"},{"fix":"Update to TroisJS version 0.3.2 or newer, as specific bug fixes for Raycaster issues (e.g., with GltfModel clicks) were implemented in that release. Ensure your scene setup aligns with the library's recommended practices for raycasting.","message":"Event handling for pointer interactions (e.g., click, hover) on 3D objects sometimes fails to register correctly, particularly with complex GLTF models or specific camera setups.","severity":"gotcha","affected_versions":"<0.3.2"},{"fix":"Upgrade to TroisJS version 0.3.1 or later, which includes a bug fix addressing texture application for `ShaderMaterial`.","message":"When using `ShaderMaterial` with custom textures, issues might arise where the texture is not correctly applied or rendered.","severity":"gotcha","affected_versions":"<0.3.1"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"fix":"Run `npm install troisjs three vue` or `yarn add troisjs three vue` to install the package and its core peer dependencies.","cause":"The `troisjs` package has not been installed or correctly linked in your project.","error":"Error: Cannot find module 'troisjs'"},{"fix":"Ensure you have called `app.use(TroisJSVuePlugin)` during your Vue application initialization, or explicitly import and register the component locally within your Vue SFCs if not using the plugin.","cause":"TroisJS components (e.g., <Renderer>, <Box>) are not globally registered or locally imported in your Vue application.","error":"[Vue warn]: Failed to resolve component: <component-name>"},{"fix":"Use Vue's lifecycle hooks like `onMounted` or `nextTick` to ensure the component is rendered and its internal Three.js objects are available before attempting to interact with them programmatically. Use `ref` and optional chaining (`?.`) for safer access.","cause":"Attempting to access properties of a TroisJS component's underlying Three.js object (e.g., `renderer.scene`) before the component has fully mounted and initialized.","error":"TypeError: Cannot read properties of null (reading 'scene')"}],"ecosystem":"npm"}