Proposal: Introducing a Plugin System for Tres.js

[JaimeTorrealba]

Hello everyone 👋

We’d like to open a discussion around the creation of a potential plugin system for Tres.js, with the goal of expanding our ecosystem in a scalable and maintainable way.

This is an early-stage proposal, and we’d love community feedback on API design, ergonomics, and limitations.

---

🎯 Motivation

As the Tres.js ecosystem grows, we see an opportunity to:

• Encourage small, focused packages that extend Tres.js
• Provide official or semi-official integration points for third-party libraries built for or commonly used with Three.js
• Avoid bloating core packages (and existing ones like @tresjs/cientos) with many third-party dependencies
• Make it easier for contributors to create and maintain extensions

📦 Dependency Separation (Cientos as an Example)

One of the key motivations is moving third-party dependencies into their own packages.

For example:

• stats-gl is currently used in @tresjs/cientos
• The underlying package lives here:
  https://github.com/RenaudRohlinger/stats-gl

A plugin system could allow:

• A lightweight Tres.js wrapper around stats-gl
• Independent versioning
• Clear ownership and maintenance boundaries

The idea is not to replace large, feature-rich packages (e.g. tres-rapier, postprocessing, leches), but rather to support small wrappers with concise APIs and possibly one-page documentation.

---

🧩 Scope of the Plugin System

• Focused on small integrations / wrappers
• Each plugin would likely:
  • Live in its own npm package
  • Wrap or adapt a third-party dependency
  • Be designed specifically for usage with Tres.js
• Plugins may be targeted, but not strictly limited, to Three.js-related tools
• Provided a single

Examples of potential candidates:

• stats-gl
• lenis
• theatre.js
• LineMesh2
• Similar utility or helper libraries

---

🧠 Existing Patterns in Tres.js

Currently, much of our ecosystem already relies on Vue’s provide / inject pattern, which could serve as a solid foundation for a plugin system.

This is worth highlighting, as it aligns well with Vue’s own recommended approaches.

---

🔌 Possible API Designs

Option 1: Vue-style Plugin API

Following Vue’s official plugin documentation:

https://vuejs.org/guide/reusability/plugins.html#provide-inject-with-plugins

Example usage:

import { createApp } from 'vue'

const app = createApp({})

app.use(myPlugin, {
  /* optional options */
})

Pros

• Familiar to Vue users
• Clear lifecycle and registration point
• Works naturally with provide / inject

Cons

• Slightly more setup
• Less declarative in templates

Option 2: Component-based Abstraction (Cientos-like)

A simpler, component-first approach:

<script setup>
import { MyPlugin } from 'my-plugin-for-tres'
</script>

<template>
  <TresCanvas>
    <MyPlugin />
  </TresCanvas>
</template>

---

Pros

• Very declarative
• Easy to adopt
• Minimal setup

Cons

• Potentially more limited
• Less flexibility for global configuration or shared state
• Might not fit all plugin use cases

---

📚 Documentation Strategy

As part of a potential plugin system, we’d like to centralize documentation by maintaining a single site for all official Tres.js plugins.

Each plugin would remain independent in terms of repository and versioning, but its documentation would live alongside other official plugins to provide a unified and discoverable experience for users.

---

❓ Open Questions for the Community

We’d love your thoughts on the following:

• Which API feels more appropriate for Tres.js?
• Should we support both patterns, or strongly encourage one?
• How much abstraction should plugins provide?
• What expectations should exist around documentation and maintenance?
• Are there existing libraries you’d like to see adapted as plugins?

---

🤝 Invitation to Discuss

This proposal is meant to start a conversation, not define a final direction.

If you:

• Maintain a Tres.js-related package
• Have experience designing plugin systems
• Or simply have opinions on DX and API design

👉 Please join the discussion and share your ideas.

Looking forward to hearing your thoughts and shaping this together 🚀

[alvarosabu]

Hey @JaimeTorrealba love to see this here ❤️

Option 1 (Vue-style app.use()) vs Option 2 (component-based):

I'd push back on presenting these as alternatives. They solve different problems:

• app.use() makes sense for global setup — registering things once, configuring shared state, injecting context.
• Component-based makes sense for scene-scoped things — a component that lives inside and provides context to children. (This is how most of the ecosystem operates, cientos, postprocessing etc)

The real question is: what level does a given plugin operate at? stats-gl probably wants to be inside the canvas. theatre.js might need
app-level setup.

Some further questions

• How do plugins interact with the Tres renderer lifecycle (dispose, onBeforeRender, etc.)? That's not just Vue app lifecycle.
• "Single site for all official plugins" is a maintenance burden — who owns it when plugin maintainers go quiet?
• No mention of TypeScript plugin contracts / interfaces. Without a defined plugin interface, "plugin system" is just a naming
  convention.

wdyt?