react-three-start

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

react-three-start

@react-three/start

is a client-first app shell for React Three Fiber. It owns Vite/React bootstrapping, the root element, a fullscreen Canvas, scene discovery, DOM overlays, and wrapper composition. The app author mostly adds files under

src/

@react-three/start

是一款面向React Three Fiber的客户端优先应用框架。它负责Vite/React的启动流程、根元素、全屏Canvas、场景发现、DOM覆盖层以及包装器组合。应用开发者主要在

src/

目录下添加文件。

Project Shape

项目结构

txt

src/
  cube.scene.tsx      # rendered inside <Canvas>
  lights.scene.tsx    # rendered inside <Canvas>
  hud.dom.tsx         # rendered in the DOM overlay
start.config.ts       # optional framework config

Use

react-three-start dev

react-three-start build

, and

react-three-start preview

;

r3s

is the short alias. Create apps with

npx @react-three/start create my-app

txt

src/
  cube.scene.tsx      # 在<Canvas>内渲染
  lights.scene.tsx    # 在<Canvas>内渲染
  hud.dom.tsx         # 在DOM覆盖层中渲染
start.config.ts       # 可选的框架配置文件

使用

react-three-start dev

、

react-three-start build

和

react-three-start preview

命令；

r3s

是其简写别名。可通过

npx @react-three/start create my-app

创建应用。

Entry Files

入口文件

```
src/**/*.scene.tsx
```
files are the 3D layer. Default-export R3F objects, lights, cameras, controls, physics bodies, or providers.
```
src/**/*.dom.tsx
```
files are the DOM overlay layer. Default-export normal React DOM UI.
Entries are discovered automatically and sorted by path. Do not create a manual scene registry for ordinary app composition.
DOM overlay content is fixed over the viewport. With the default injected Canvas, the overlay container has
```
pointer-events: none
```
, so interactive DOM controls should set
```
pointerEvents: 'auto'
```
.

```
src/**/*.scene.tsx
```
文件属于3D层。默认导出R3F对象、光源、相机、控制器、物理体或提供者。
```
src/**/*.dom.tsx
```
文件属于DOM覆盖层。默认导出普通React DOM UI。
入口文件会被自动发现并按路径排序。普通应用组合无需手动创建场景注册表。
DOM覆盖层内容固定在视口上方。在默认注入的Canvas中，覆盖层容器设置了
```
pointer-events: none
```
，因此交互式DOM控件需手动设置
```
pointerEvents: 'auto'
```
。

Slots And Wrappers

插槽与包装器

Import

Scene

Dom

from

@react-three/start

only inside discovered

*.scene.tsx

and

*.dom.tsx

entry files. The Vite plugin rewrites those imports to continuation components.

A scene file that imports and renders

<Scene />

becomes a scene wrapper. Use wrappers for providers that must surround the rest of the 3D scene: XR, physics, Suspense, controls, environment setup. Sorted filenames define nesting order.

tsx

// src/00-xr.scene.tsx
import { Scene } from '@react-three/start'
import { Physics } from '@react-three/rapier'

export default function PhysicsWrapper() {
  return (
    <Physics>
      <Scene />
    </Physics>
  )
}

txt

00-xr.scene.tsx       # outer wrapper
10-physics.scene.tsx  # inner wrapper
cube.scene.tsx        # leaf scene entry

A DOM file that imports and renders

<Dom />

becomes a DOM wrapper. A DOM file may also import

<Scene />

when manually owning the Canvas.

仅在已被发现的

*.scene.tsx

和

*.dom.tsx

入口文件中从

@react-three/start

导入

Scene

或

Dom

。Vite插件会将这些导入重写为延续组件。

导入并渲染

<Scene />

的场景文件将成为场景包装器。包装器适用于必须包裹其余3D场景的提供者：XR、物理、Suspense、控制器、环境设置。文件名的数字前缀定义了嵌套顺序。

tsx

// src/00-xr.scene.tsx
import { Scene } from '@react-three/start'
import { Physics } from '@react-three/rapier'

export default function PhysicsWrapper() {
  return (
    <Physics>
      <Scene />
    </Physics>
  )
}

txt

00-xr.scene.tsx       # 外层包装器
10-physics.scene.tsx  # 内层包装器
cube.scene.tsx        # 叶子场景入口

导入并渲染

<Dom />

的DOM文件将成为DOM包装器。DOM文件也可在手动管理Canvas时导入

<Scene />

。

Manual Canvas

手动配置Canvas

By default, react-three-start injects a fullscreen Canvas and renders

<Scene />

inside it. When layout, shadows, camera props, XR buttons, or multiple panels need ownership, disable injection and render the Canvas from a DOM entry.

// start.config.ts
export default {
  injectCanvas: false,
  title: 'My R3F app'
}

tsx

// src/app.dom.tsx
import { Canvas } from '@react-three/fiber'
import { Scene } from '@react-three/start'

export default function App() {
  return (
    <Canvas shadows camera={{ position: [0, 2, 6], fov: 45 }}>
      <Scene />
    </Canvas>
  )
}

start.config.ts

may export

injectCanvas

title

, and a nested

vite

config object. The CLI merges

vite

with the generated Vite config and passes the remaining options to

reactThreeStart()

. Prefer

start.config.ts

; add

vite.config.ts

only when normal Vite ownership is needed.

默认情况下，react-three-start会注入一个全屏Canvas并在其中渲染

<Scene />

。当需要自定义布局、阴影、相机属性、XR按钮或多面板时，可禁用自动注入并从DOM入口渲染Canvas。

// start.config.ts
export default {
  injectCanvas: false,
  title: 'My R3F app'
}

tsx

// src/app.dom.tsx
import { Canvas } from '@react-three/fiber'
import { Scene } from '@react-three/start'

export default function App() {
  return (
    <Canvas shadows camera={{ position: [0, 2, 6], fov: 45 }}>
      <Scene />
    </Canvas>
  )
}

start.config.ts

可导出

injectCanvas

、

title

以及嵌套的

vite

配置对象。CLI会将

vite

配置与生成的Vite配置合并，并将其余选项传递给

reactThreeStart()

。优先使用

start.config.ts

；仅当需要完全掌控Vite时才添加

vite.config.ts

。

Agent Rules Of Thumb

Agent使用经验法则

Add new visual content as small
```
*.scene.tsx
```
leaves unless it must wrap other scene entries.
Add UI as
```
*.dom.tsx
```
; keep interactive overlay elements explicitly pointer-enabled.
Use numeric filename prefixes for wrapper order, not import order.
Keep
```
Scene
```
and
```
Dom
```
imports in entry files only; pass ordinary React components through normal imports.
Reach for manual Canvas only when the default fullscreen Canvas is too limiting.

除非必须包裹其他场景入口，否则将新视觉内容添加为小型
```
*.scene.tsx
```
叶子文件。
将UI添加为
```
*.dom.tsx
```
文件；确保交互式覆盖元素显式启用指针事件。
使用文件名的数字前缀定义包装器顺序，而非导入顺序。
仅在入口文件中保留
```
Scene
```
和
```
Dom
```
导入；普通React组件通过常规导入传递。
仅当默认全屏Canvas无法满足需求时，才考虑手动配置Canvas。