Proposal to Promote Best Practices in Using TresJS Library

[alvarosabu]

Introduction

TresJS has been an invaluable tool in integrating Three.js with Vue, allowing developers to manage complex 3D scenes using a more declarative approach. Historically, our examples and documentation have emphasized a single-file component approach. While this method simplifies initial learning and setup, it may not promote the best practices for scalability and maintainability in larger applications.

Problem Statement

The current single-file usage pattern encouraged by TresJS documentation and examples limits the scalability and maintainability of applications built with the library. Most composables require the context of the TresCanvas, making it cumbersome to manage larger, more complex scenes within a single file.

Proposal

To address these limitations, we propose revising our examples, documentation, and other resources to demonstrate and encourage a modular approach. Specifically, we aim to promote a structure where components related to the 3D scene are encapsulated in separate subcomponents, much like how UI elements are managed in larger Vue applications.

Instead of

<script setup lang="ts">
import { TresCanvas } from '@tresjs/core'
</script>

<template>
  <TresCanvas clear-color="#c0ffee" window-size>
    <TresPerspectiveCamera :position="[3, 3, 3]" />
    <TresGridHelper :size="10" />
    <TresAmbientLight :intensity="1" />
  </TresCanvas>
</template>

We promote:

App.vue:

<script setup lang="ts">
import { TresCanvas } from '@tresjs/core'
import TheExperience from './components/TheExperience.vue'
</script>

<template>
  <TresCanvas clear-color="#c0ffee" window-size>
    <TheExperience />
  </TresCanvas>
</template>

TheExperience.vue:

<script setup lang="ts">
// Here they can access the context for `useUpdate`, `useRender`, `useTres`
</script>

<template>
    <TresPerspectiveCamera :position="[3, 3, 3]" />
    <TresGridHelper :size="10" />
    <TresAmbientLight :intensity="1" />
</template>

Detailed Changes

• Playground Enhancements: Update the TresJS playground to include examples that showcase the use of subcomponents in a TresJS project.
• StackBlitz and Starter Repositories: Revise existing examples on platforms like StackBlitz and starter repositories to reflect a modular component structure, providing newcomers with templates that follow best practices.
• Documentation Update: Overhaul the official documentation to:
• Include a section on "Best Practices" that advocates for a component-based architecture.
  • Provide step-by-step guides on breaking down a complex scene into manageable subcomponents.
  • Highlight the benefits of this approach, such as easier maintenance, better reusability, and improved scalability.
  • Community Engagement: Solicit feedback from the community on these changes and encourage contributions that align with this modular approach.

Rationale

The proposed changes align with the core philosophy of Vue, which is to build applications through a modular and declarative approach. By promoting a structure that separates concerns and encapsulates functionality, we can enhance the development experience, making TresJS projects easier to manage, scale, and understand.

Benefits

• Enhanced Maintainability: Smaller, focused components are easier to debug and maintain.
• Increased Scalability: Modular architecture makes it simpler to expand and enhance 3D scenes as project requirements grow.
• Improved Reusability: Components can be reused across different parts of the application or even across projects.
• Community Growth: By adopting and promoting best practices, we can attract a broader audience and encourage more developers to contribute to the TresJS ecosystem.

Conclusion

Transitioning to a component-based architecture for TresJS examples and documentation will set a standard that helps developers create more robust and maintainable applications. This proposal aims to foster a shift in how TresJS is used and perceived, from a tool for quick 3D integrations to a powerful framework for building sophisticated 3D web applications.