threejs-dev-setup

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

When to use this skill

何时使用此skill

ALWAYS use this skill when the user mentions:

Creating or configuring a new three.js project, Vite/Webpack/Rollup entry, or browser
```
importmap
```
Installing the
```
three
```
package, aligning version with documentation, or TypeScript setup (
```
@types/three
```
where applicable)
Import errors for
```
three/addons/...
```
,
```
examples/jsm
```
, ESM vs CJS interop, or bare specifier resolution

IMPORTANT: this skill vs runtime topics

threejs-dev-setup = install paths, bundler, module graph, and where to import addons from.
threejs-renderers =
```
WebGLRenderer
```
/
```
WebGPURenderer
```
, canvas, pixel ratio, render loop—after the project loads.
threejs-loaders =
```
GLTFLoader
```
,
```
DRACOLoader
```
, progress callbacks—after imports resolve.

Trigger phrases include:

"vite three.js", "webpack three", "import map", "three/addons", "cannot find module", "jsm"
"新建项目", "安装 three", "找不到模块", "ESM", "TypeScript three"

当用户提到以下内容时，始终使用此skill：

创建或配置新的three.js项目、Vite/Webpack/Rollup入口或浏览器
```
importmap
```
安装
```
three
```
包、与文档版本对齐，或TypeScript设置（如适用
```
@types/three
```
）
针对
```
three/addons/...
```
、
```
examples/jsm
```
、ESM与CJS互操作或裸说明符解析的导入错误

重要提示：此skill与运行时主题的区别

threejs-dev-setup = 安装路径、打包器、模块图以及从何处导入addons。
threejs-renderers =
```
WebGLRenderer
```
/
```
WebGPURenderer
```
、canvas、像素比、渲染循环——在项目加载之后。
threejs-loaders =
```
GLTFLoader
```
、
```
DRACOLoader
```
、进度回调——在导入解析之后。

触发短语包括：

"vite three.js", "webpack three", "import map", "three/addons", "cannot find module", "jsm"
"新建项目", "安装 three", "找不到模块", "ESM", "TypeScript three"

How to use this skill

如何使用此skill

Confirm delivery model: SPA bundler (Vite/Webpack), Node tooling, or static HTML with
```
importmap
```
—each affects how
```
three/addons/
```
resolves.
Pin
three
version to a release compatible with the docs the user cites; note that addon paths follow the published package layout.
Show canonical imports: core from
```
three
```
; controls/loaders/effects from
```
three/addons/...
```
(mapped to
```
examples/jsm
```
in source tree). See examples/workflow-scaffold.md.
Minimal loop: create renderer + scene + camera + one mesh;
```
requestAnimationFrame
```
—enough to verify toolchain without duplicating threejs-renderers depth.
TypeScript: enable
```
moduleResolution
```
appropriate for bundler; reference types from
```
three
```
package typings; avoid duplicating global script tag patterns unless user targets no-bundler HTML.
On failure: distinguish missing dependency vs wrong path vs SSR context (no
```
window
```
/
```
document
```
).
Deepening: link user to three.js manual first chapter after scaffold works.

确认交付模式：SPA打包器（Vite/Webpack）、Node工具链或带有
```
importmap
```
的静态HTML——每种方式都会影响
```
three/addons/
```
的解析方式。
固定
three
版本，与用户引用的文档兼容的版本；注意addons路径遵循发布包布局。
展示规范导入：核心从
```
three
```
导入；controls/loaders/effects从
```
three/addons/...
```
导入（在源码树中映射到
```
examples/jsm
```
）。参见 examples/workflow-scaffold.md。
最小循环：创建renderer + scene + camera +一个mesh；
```
requestAnimationFrame
```
——足以验证工具链，而无需重复threejs-renderers的深度。
TypeScript：为打包器启用合适的
```
moduleResolution
```
；从
```
three
```
包的类型定义中引用类型；除非用户明确针对无打包器的HTML，否则避免重复全局script标签模式。
失败时：区分缺少依赖、路径错误或SSR上下文（没有
```
window
```
/
```
document
```
）。
深入：在脚手架工作后，将用户引导到three.js手册第一章。

Doc map (official)

文档地图（官方）

Docs section	Representative links
Manual (getting started)	https://threejs.org/manual/
Docs index	https://threejs.org/docs/
Package / install context	https://www.npmjs.com/package/three

文档部分	代表性链接
手册（入门）	https://threejs.org/manual/
文档索引	https://threejs.org/docs/
包/安装上下文	https://www.npmjs.com/package/three

Scope

范围

In scope: npm/install, bundlers, import maps, TypeScript basics for three, addon import paths, minimal verification snippet.
Out of scope: WebGL theory, full render target or post stack (threejs-renderers, threejs-postprocessing), physics, deployment beyond "build runs".

范围内：npm/安装、打包器、import maps、three的TypeScript基础、addon导入路径、最小验证代码片段。
范围外：WebGL理论、完整的渲染目标或后处理栈（threejs-renderers、threejs-postprocessing）、物理、部署（仅限于“构建运行”）。

Common pitfalls and best practices

常见陷阱和最佳实践

Mixing multiple
```
three
```
copies in one page breaks singletons; dedupe with bundler aliases.
Importing addons from deep
```
node_modules/.../examples/jsm
```
paths is fragile; prefer package exports
```
three/addons/...
```
when available.
Always match r152+ style color management docs when giving snippet defaults (output color space)—point to threejs-renderers/textures for details.
SSR frameworks need dynamic import or client-only components for WebGL context.

在一个页面中混合多个
```
three
```
副本会破坏单例；使用打包器别名去重。
从深度
```
node_modules/.../examples/jsm
```
路径导入addons是脆弱的；优先使用包导出
```
three/addons/...
```
（可用时）。
在给出代码片段默认值时，始终匹配**r152+**风格的颜色管理文档（输出色彩空间）——细节请参阅threejs-renderers/textures。
SSR框架需要对WebGL上下文使用动态导入或仅客户端组件。

Documentation and version

文档和版本

Toolchain and import paths follow the three npm package version the user installs. The Manual and docs are updated with the library; addon paths (

three/addons/...

) must match the package layout for that release—when in doubt, cite the version number and the exact import line from the current docs.

工具链和导入路径遵循用户安装的three npm包版本。手册和文档随库更新；addon路径（

three/addons/...

）必须与该版本的包布局匹配——如有疑问，请引用版本号和当前文档中的确切导入行。

Agent response checklist

Agent响应检查清单

When answering under this skill, prefer responses that:

Name the bundler or runtime (Vite, Webpack, bare ESM,
```
importmap
```
) and the intended
```
three
```
version.
Link https://threejs.org/manual/ and/or https://threejs.org/docs/ for authoritative setup context.
Distinguish threejs-dev-setup (resolution) from threejs-renderers (runtime API) failures.
Never assume global script tags unless the user explicitly uses CDN/no-bundler HTML.
Recommend deduplicating
```
three
```
in
```
package.json
```
/ lockfile when duplicate singleton issues appear.

在此skill下回答时，响应应倾向于：

指明打包器或运行时（Vite、Webpack、纯ESM、
```
importmap
```
）和预期的
```
three
```
版本。
链接https://threejs.org/manual/ 和/或 https://threejs.org/docs/ 作为权威设置上下文。
区分threejs-dev-setup（解析）与threejs-renderers（运行时API）的失败。
除非用户明确使用CDN/无打包器HTML，否则不要假设全局script标签。
当出现重复单例问题时，建议在
```
package.json
```
/lockfile中去重
```
three
```
。

References

参考

Keywords

关键词

English: three.js, vite, webpack, rollup, import map, typescript, npm, three/addons, examples jsm, module resolution, scaffold

中文： three.js 安装、构建、importmap、模块解析、three/addons、脚手架、Vite、Webpack

英文： three.js, vite, webpack, rollup, import map, typescript, npm, three/addons, examples jsm, module resolution, scaffold

中文： three.js 安装、构建、importmap、模块解析、three/addons、脚手架、Vite、Webpack