threejs-dev-setup
Bootstrap and toolchain guidance for three.js applications using npm, Vite/Webpack/Rollup, bare ESM import maps, and TypeScript. Covers canonical import paths for three core versus three/addons/ (examples/jsm re-exports), version alignment with threejs.org docs, and fixing module not found for loaders and controls. Use when scaffolding a new 3D project, migrating bundler, or debugging resolution of addons; do not use for rendering API details (see threejs-renderers) or asset loading logic (see threejs-loaders).
Best use case
threejs-dev-setup is best used when you need a repeatable AI agent workflow instead of a one-off prompt. It is especially useful for teams working in multi. Bootstrap and toolchain guidance for three.js applications using npm, Vite/Webpack/Rollup, bare ESM import maps, and TypeScript. Covers canonical import paths for three core versus three/addons/ (examples/jsm re-exports), version alignment with threejs.org docs, and fixing module not found for loaders and controls. Use when scaffolding a new 3D project, migrating bundler, or debugging resolution of addons; do not use for rendering API details (see threejs-renderers) or asset loading logic (see threejs-loaders).
Bootstrap and toolchain guidance for three.js applications using npm, Vite/Webpack/Rollup, bare ESM import maps, and TypeScript. Covers canonical import paths for three core versus three/addons/ (examples/jsm re-exports), version alignment with threejs.org docs, and fixing module not found for loaders and controls. Use when scaffolding a new 3D project, migrating bundler, or debugging resolution of addons; do not use for rendering API details (see threejs-renderers) or asset loading logic (see threejs-loaders).
Users should expect a more consistent workflow output, faster repeated execution, and less time spent rewriting prompts from scratch.
Practical example
Example input
Use the "threejs-dev-setup" skill to help with this workflow task. Context: Bootstrap and toolchain guidance for three.js applications using npm, Vite/Webpack/Rollup, bare ESM import maps, and TypeScript. Covers canonical import paths for three core versus three/addons/ (examples/jsm re-exports), version alignment with threejs.org docs, and fixing module not found for loaders and controls. Use when scaffolding a new 3D project, migrating bundler, or debugging resolution of addons; do not use for rendering API details (see threejs-renderers) or asset loading logic (see threejs-loaders).
Example output
A structured workflow result with clearer steps, more consistent formatting, and an output that is easier to reuse in the next run.
When to use this skill
- Use this skill when you want a reusable workflow rather than writing the same prompt again and again.
When not to use this skill
- Do not use this when you only need a one-off answer and do not need a reusable workflow.
- Do not use it if you cannot install or maintain the related files, repository context, or supporting tools.
Installation
Claude Code / Cursor / Codex
Manual Installation
- Download SKILL.md from GitHub
- Place it in
.claude/skills/threejs-dev-setup/SKILL.mdinside your project - Restart your AI agent — it will auto-discover the skill
How threejs-dev-setup Compares
| Feature / Agent | threejs-dev-setup | Standard Approach |
|---|---|---|
| Platform Support | Not specified | Limited / Varies |
| Context Awareness | High | Baseline |
| Installation Complexity | Unknown | N/A |
Frequently Asked Questions
What does this skill do?
Bootstrap and toolchain guidance for three.js applications using npm, Vite/Webpack/Rollup, bare ESM import maps, and TypeScript. Covers canonical import paths for three core versus three/addons/ (examples/jsm re-exports), version alignment with threejs.org docs, and fixing module not found for loaders and controls. Use when scaffolding a new 3D project, migrating bundler, or debugging resolution of addons; do not use for rendering API details (see threejs-renderers) or asset loading logic (see threejs-loaders).
Where can I find the source code?
You can find the source code on GitHub using the link provided at the top of the page.
Related Guides
AI Agents for Coding
Browse AI agent skills for coding, debugging, testing, refactoring, code review, and developer workflows across Claude, Cursor, and Codex.
Cursor vs Codex for AI Workflows
Compare Cursor and Codex for AI coding workflows, repository assistance, debugging, refactoring, and reusable developer skills.
SKILL.md Source
## When to use this 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"
## How to use this skill
1. **Confirm delivery model**: SPA bundler (Vite/Webpack), Node tooling, or static HTML with `importmap`—each affects how `three/addons/` resolves.
2. **Pin `three` version** to a release compatible with the docs the user cites; note that addon paths follow the published package layout.
3. **Show canonical imports**: core from `three`; controls/loaders/effects from `three/addons/...` (mapped to `examples/jsm` in source tree). See [examples/workflow-scaffold.md](examples/workflow-scaffold.md).
4. **Minimal loop**: create renderer + scene + camera + one mesh to verify toolchain works.
5. **TypeScript**: enable `moduleResolution` appropriate for bundler; reference types from `three` package typings; avoid duplicating global script tag patterns unless user targets no-bundler HTML.
6. **On failure**: distinguish missing dependency vs wrong path vs SSR context (no `window`/`document`).
7. **Deepening**: link user to [three.js manual](https://threejs.org/manual/) first chapter after scaffold works.
### Example: Vite + three.js minimal verification
```bash
npm create vite@latest my-3d-app -- --template vanilla && cd my-3d-app
npm install three
```
```javascript
// main.js — canonical imports and minimal render loop
import * as THREE from 'three';
import { OrbitControls } from 'three/addons/controls/OrbitControls.js';
const scene = new THREE.Scene();
const camera = new THREE.PerspectiveCamera(75, innerWidth / innerHeight, 0.1, 100);
camera.position.z = 3;
const renderer = new THREE.WebGLRenderer();
renderer.setSize(innerWidth, innerHeight);
document.body.appendChild(renderer.domElement);
const mesh = new THREE.Mesh(
new THREE.BoxGeometry(),
new THREE.MeshStandardMaterial({ color: 0x00ff00 })
);
scene.add(mesh, new THREE.AmbientLight(0xffffff, 0.5));
renderer.setAnimationLoop(() => renderer.render(scene, camera));
```
## 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 |
## 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".
## 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.
## Documentation and version
Toolchain and import paths follow the **three** npm package version the user installs. The [Manual](https://threejs.org/manual/) and [docs](https://threejs.org/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.
## Agent response checklist
When answering under this skill, prefer responses that:
1. Name the bundler or runtime (Vite, Webpack, bare ESM, `importmap`) and the intended `three` version.
2. Link https://threejs.org/manual/ and/or https://threejs.org/docs/ for authoritative setup context.
3. Distinguish **threejs-dev-setup** (resolution) from **threejs-renderers** (runtime API) failures.
4. Never assume global script tags unless the user explicitly uses CDN/no-bundler HTML.
5. Recommend deduplicating `three` in `package.json` / lockfile when duplicate singleton issues appear.
## Keywords
**English:** three.js, vite, webpack, rollup, import map, typescript, npm, three/addons, examples jsm, module resolution, scaffold
**中文:** three.js 安装、构建、importmap、模块解析、three/addons、脚手架、Vite、WebpackRelated Skills
threejs-webxr
WebXR integration for three.js: WebXRManager and XRManager on the renderer, session initialization patterns, VRButton and ARButton helpers, XRControllerModelFactory and hand model families, XREstimatedLight, XRPlanes, and related addon Webxr utilities. Use for immersive sessions and controller/hand tracking—not for standard desktop camera projection (threejs-camera) or composer post effects (threejs-postprocessing).
threejs-textures
three.js textures: Texture, DataTexture, CubeTexture, CompressedTexture variants, DepthTexture, VideoTexture, CanvasTexture, 3D/array textures, Source; sampling parameters, mipmaps, anisotropy, wrap/mag/min filters; PMREMGenerator in Extras for environment map prefiltering. Use when configuring GPU texture objects and PMREM; for Draco/KTX2 transcoder file paths use threejs-loaders; for material map slots use threejs-materials; for output color pipeline use threejs-renderers.
threejs-scenes
three.js Scene graph root object, linear Fog and exponential FogExp2, Scene.background for solid colors or textures, and high-level environment background concepts that tie to PMREM and loaders in other skills. Use when configuring world container, atmospheric fog, or background; for HDR env map file loading use threejs-loaders; for GPU texture settings after load use threejs-textures; for tone mapping use threejs-renderers.
threejs-renderers
Core rendering pipeline for three.js using WebGLRenderer and WebGPURenderer, canvas sizing, device pixel ratio, color space and tone mapping, output encoding, WebGL/WebGPU render targets, Info statistics, and addon overlay renderers (CSS2D/CSS3D/SVG). Use when tuning the draw loop, performance, or switching WebGPU vs WebGL; for EffectComposer passes use threejs-postprocessing; for XR session lifecycle use threejs-webxr; for shader graphs use threejs-node-tsl.
threejs-postprocessing
Addon screen-space post-processing for three.js using EffectComposer, Pass base class, RenderPass, and stock passes such as UnrealBloomPass, SSAOPass, SSRPass, BokehPass, OutlinePass, FXAAPass/SMAAPass, TAARenderPass, and ShaderPass; references the Shaders addon group for underlying shader modules. Use when building composer chains for bloom, SSAO, or other screen-space effects; not for basic renderer tone mapping alone (threejs-renderers).
threejs-objects
three.js scene graph objects: Object3D transforms and hierarchy, Group, Mesh, InstancedMesh, SkinnedMesh, BatchedMesh, LOD, Line/LineLoop/LineSegments, Points, Sprite, Bone, Skeleton, ClippingGroup; interaction via Raycaster, Layers masks, and EventDispatcher patterns. Use when building scene hierarchies, picking objects with Raycaster, or configuring instanced/skinned meshes; for pure vector math use threejs-math; for skeletal clips use threejs-animation.
threejs-node-tsl
three.js node-based shading: Nodes API surface, NodeMaterial and MeshStandardNodeMaterial-style families, TSL (Three.js Shading Language) entry at TSL.html, WebGPURenderer pairing, and core PostProcessing (class) versus addon EffectComposer at a high level. Use when authoring shaders as graphs, using TSL builtins, compute-oriented nodes, or modern WebGPU pipelines; for classic ShaderMaterial GLSL use threejs-materials; for stock EffectComposer passes use threejs-postprocessing; for WebGLRenderer-only tuning use threejs-renderers.
threejs-math
three.js math library: Vector2/3/4, Matrix3/4, Quaternion, Euler, Color, Box2/Box3, Sphere, Plane, Ray, Line3, Triangle, Frustum, Cylindrical/Spherical coords, MathUtils, and Interpolant base classes; addon math utilities such as OBB, Octree, Capsule, ConvexHull, MeshSurfaceSampler. Use for transforms, intersection tests, and spatial queries; for keyframe interpolation tied to AnimationMixer use threejs-animation; for picking implementation use threejs-objects with Raycaster.
threejs-materials
Classic three.js materials (non-Node): MeshStandardMaterial, MeshPhysicalMaterial, Phong/Lambert/Toon/Basic, Line/Points/Sprite materials, MeshMatcapMaterial, MeshNormalMaterial, depth/distance materials, ShaderMaterial and RawShaderMaterial. Use when tuning PBR maps, transparency, depth write, skinning flags, or writing GLSL in ShaderMaterial; for TSL/NodeMaterial/WebGPU shader graphs use threejs-node-tsl instead.
threejs-loaders
three.js asset I/O using LoadingManager, Cache, FileLoader, image and texture loaders, GLTFLoader with DRACOLoader and KTX2Loader, and common format loaders under Addons; symmetric exporters such as GLTFExporter and texture/buffer exporters. Use when loading or exporting models, HDR, LUT, fonts, or compressed textures; for runtime Texture object parameters after load use threejs-textures; for scene graph placement use threejs-objects.
threejs-lights
three.js lighting: AmbientLight, HemisphereLight, DirectionalLight, PointLight, SpotLight, RectAreaLight, LightProbe, IESSpotLight, ProjectorLight, shadow subtypes, and addon helpers such as RectAreaLightUniformsLib, RectAreaLightTexturesLib, LightProbeGenerator, TiledLighting. Use when configuring direct/indirect light, shadows, probes, or area lights; for IES file loading use threejs-loaders; for node-based light graphs use threejs-node-tsl; for debug helpers use threejs-helpers.
threejs-helpers
Debug and visualization helpers in three.js Core Helpers (AxesHelper, GridHelper, CameraHelper, light helpers, SkeletonHelper, bounding box helpers, PlaneHelper, PolarGridHelper, ArrowHelper) and Addons Helpers (VertexNormalsHelper, VertexTangentsHelper, RectAreaLightHelper, LightProbeHelper, ViewHelper, OctreeHelper, TextureHelper, PositionalAudioHelper, AnimationPathHelper, RapierHelper). Use only for development and editor overlays—not for shipping art; for gizmo-style manipulation use threejs-controls.