Você pode instalar o three.js através do [link:https://www.npmjs.com/ npm] e modernas ferramentas de build ou começar rapidamente apenas com hospedagem estática ou um CDN. Para a maioria dos usuários, instalar pelo npm é a melhor opção.
Seja qual for a maneira que escolher, seja consistente e importe todos os arquivos na mesma versão da biblioteca. A mistura de arquivos de versões diferentes pode causar a inclusão de código duplicado ou até mesmo quebrar a aplicação de maneiras inesperadas.
Todos os métodos de instalação do three.js dependem dos ES modules (veja [link:https://eloquentjavascript.net/10_modules.html#h_hF2FmOVxw7 Eloquent JavaScript: ECMAScript Modules]), que permitem incluir somente as partes necessárias da biblioteca no projeto final.
Para instalar o módulo do npm do [link:https://www.npmjs.com/package/three three], abra uma janela do terminal na sua pasta do projeto e execute:
npm install three
O pacote será baixado e instalado. Então você estará pronto para importar no seu código:
// Option 1: Import the entire three.js core library.
import * as THREE from 'three';
const scene = new THREE.Scene();
// Option 2: Import just the parts you need.
import { Scene } from 'three';
const scene = new Scene();
Ao instalar a partir do npm, você quase sempre usará algum tipo de [link:https://eloquentjavascript.net/10_modules.html#h_zWTXAU93DC ferramenta de build] para combinar todos os pacotes que seu projeto precisa em um único arquivo JavaScript. Embora alguns modernos empacotadores JavaScript possam ser usados com o three.js, a escolha mais popular é o [link:https://webpack.js.org/ webpack].
Nem todos os recursos são acessados diretamente pelo módulo three. Outras partes populares da biblioteca - tais como controls, loaders e post-processing effects - devem ser importados da subpasta [link:https://github.com/mrdoob/three.js/tree/dev/examples/jsm examples/jsm]. Para aprender mais, veja o Exemplo abaixo.
Aprenda mais sobre módulos do npm em [link:https://eloquentjavascript.net/20_node.html#h_J6hW/SmL/a Eloquent JavaScript: Installing with npm].
A biblioteca three.js pode ser utilizada sem nenhum sistema de build, seja fazendo o upload dos arquivos para seu próprio servidor web ou usando um CDN existente. Como a biblioteca depende dos ES modules, qualquer script que faça referência a eles deve usar type="module" como mostrado abaixo. Também é necessário definir um mapa de importação que resolva a importação direta do `three`.
<script async src="https://unpkg.com/es-module-shims@1.3.6/dist/es-module-shims.js"></script>
<script type="importmap">
{
"imports": {
"three": "https://unpkg.com/three@<version>/build/three.module.js"
}
}
</script>
<script type="module">
import * as THREE from 'three';
const scene = new THREE.Scene();
</script>
Nem todos os recursos disponíveis são acessados diretamente através do módulo three. Outras partes populares da biblioteca - tais como controls, loaders e post-processing effects - devem ser importados da subpasta [link:https://github.com/mrdoob/three.js/tree/dev/examples/jsm examples/jsm]. Para aprender mais, veja o Exemplo abaixo.
Como os mapas de importação ainda não são suportados por todos os navegadores, é necessário adicionar o polyfill *es-module-shims.js*.
O núcleo do three.js está focado nos componentes mais importantes de uma engine 3D. Muitos outros componentes úteis - como controls, loaders e post-processing effects - fazem parte da pasta [link:https://github.com/mrdoob/three.js/tree/dev/examples/jsm examples/jsm]. Eles são chamados de "exemplos" porque embora você possa usá-los diretamente, eles também podem ser remixados e personalizados. Esses componentes são sempre mantidos em sincronia com a biblioteca principal, enquanto pacotes semelhantes de terceiros no npm são mantidos por pessoas diferentes e podem estar desatualizados.
Os addons não precisam ser instalados separadamente, mas precisam ser importados separadamente. Se o three.js foi instalado com npm, você pode carregar o componente [page:OrbitControls] com:
import { OrbitControls } from 'three/addons/controls/OrbitControls.js';
const controls = new OrbitControls( camera, renderer.domElement );
Se o three.js foi instalado de um CDN, use o mesmo CDN para instalar outros componentes:
<script async src="https://unpkg.com/es-module-shims@1.3.6/dist/es-module-shims.js"></script>
<script type="importmap">
{
"imports": {
"three": "https://unpkg.com/three@<version>/build/three.module.js",
"three/addons/": "https://unpkg.com/three@<version>/examples/jsm/"
}
}
</script>
<script type="module">
import * as THREE from 'three';
import { OrbitControls } from 'three/addons/controls/OrbitControls.js';
const controls = new OrbitControls( camera, renderer.domElement );
</script>
É importante que todos os arquivos utilizem a mesma versão. Não importe diferentes addons de diferentes versões, ou use addons de uma versão diferente que a própria biblioteca three.js.
Embora a maioria dos bundlers JavaScript modernos atualmente suportem os ES modules por padrão, algumas ferramentas de build mais antigas podem não suportar. Nesses casos você provavelmente pode configurar o bundler para entender os ES modules: [link:http://browserify.org/ Browserify] precisa apenas do plugin [link:https://github.com/babel/babelify babelify], por exemplo.
Como o three.js foi desenvolvido para a web, ele depende do navegador e das APIs DOM que nem sempre existem no Node.js. Alguns desses problemas podem ser resolvidos usando ferramentas como [link:https://github.com/stackgl/headless-gl headless-gl], ou substituindo componentes como [page:TextureLoader] por alternativas personalizadas. Outras APIs DOM podem ser profundamente entrelaçadas com o código que as utiliza, e serão mais difíceis de contornar. Aceitamos solicitações de pull simples e fáceis de manter para melhorar o suporte ao Node.js, mas recomendo abrir uma issue para discutir suas melhorias primeiro.
Certifique-se de adicionar `{ "type": "module" }` ao seu `package.json` para habilitar os ES6 modules em seu projeto Node.js.