troisjs

library0.3.4jsnpmunverified

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.

web-framework ai-ml

npm install troisjs

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · TROISJS

troisjs

web-frameworkjavascriptv0.3.4

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

TroisJSVuePlugin

✓ import { TroisJSVuePlugin } from 'troisjs'

✗ import TroisJSVuePlugin from 'troisjs'

This named export is the primary way to register all TroisJS components globally with your Vue 3 application via `app.use()`.

Renderer

✓ import { Renderer } from 'troisjs'

✗ import Renderer from 'troisjs'

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.

useRenderer

✓ import { useRenderer } from 'troisjs'

This composition API hook allows access to the Three.js renderer instance within a Vue component, useful for imperative Three.js operations.

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.

import { createApp } from 'vue' import { TroisJSVuePlugin } from 'troisjs' import { ref, onMounted } from 'vue' const app = createApp({ template: ` <renderer ref="rendererRef" antialias orbit-ctrl resize="window"> <camera :position="{ z: 10 }"></camera> <scene> <point-light :position="{ y: 50, z: 50 }"></point-light> <box ref="boxRef" :rotation="{ y: rotation.y, z: rotation.z }"> <lambert-material></lambert-material> </box> </scene> </renderer> `, setup() { const rendererRef = ref(null) const boxRef = ref(null) const rotation = ref({ y: Math.PI / 4, z: Math.PI / 4 }) onMounted(() => { // Access the Three.js scene, camera, etc. via rendererRef.value.scene, etc. if (rendererRef.value && boxRef.value) { console.log('Renderer and Box components mounted.') // Example: animate box rotation rendererRef.value.onBeforeRender(() => { rotation.value.y += 0.01 rotation.value.z += 0.005 }) } }) return { rendererRef, boxRef, rotation } } }) app.use(TroisJSVuePlugin).mount('#app')

Debug

Known issues

breakingVersion 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.

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.

affects: >=0.3.0

gotchaEvent 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.

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.

affects: <0.3.2

gotchaWhen using `ShaderMaterial` with custom textures, issues might arise where the texture is not correctly applied or rendered.

fix

Upgrade to TroisJS version 0.3.1 or later, which includes a bug fix addressing texture application for `ShaderMaterial`.

affects: <0.3.1

Errors

Common errors & fixes

Error: Cannot find module 'troisjs'

The `troisjs` package has not been installed or correctly linked in your project.

fix

Run `npm install troisjs three vue` or `yarn add troisjs three vue` to install the package and its core peer dependencies.

[Vue warn]: Failed to resolve component: <component-name>

TroisJS components (e.g., <Renderer>, <Box>) are not globally registered or locally imported in your Vue application.

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.

TypeError: Cannot read properties of null (reading 'scene')

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.

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.

Upgrade

Version history

0.3.4latest on npm

Audit

Dependencies

vuerequiredTroisJS is a Vue 3 component library and requires Vue as a peer dependency.

threerequiredTroisJS is a wrapper around Three.js and depends on it for 3D rendering capabilities.

Agent activity

16 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/troisjs/trois ↗

packagehttps://www.npmjs.com/package/troisjs ↗

homepagehttps://troisjs.github.io/ ↗