Installation

Structure du projet

Tout projet three.js nécessite au moins un fichier HTML pour définir la page web, et un fichier JavaScript pour exécuter votre code three.js. La structure et les choix de noms ci-dessous ne sont pas obligatoires, mais seront utilisés tout au long de ce guide par souci de cohérence.

index.html

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8">
    <title>Ma première application three.js</title>
    <style>
      body { margin: 0; }
    </style>
  </head>
  <body>
    <script type="module" src="/main.js"></script>
  </body>
</html>

main.js
```
import * as THREE from 'three';

...
```
public/
- Le dossier public/ est parfois aussi appelé dossier "static", car les fichiers qu'il contient sont poussés vers le site web sans modification. Généralement, les textures, l'audio et les modèles 3D s'y trouvent.

Maintenant que nous avons mis en place la structure de base du projet, nous avons besoin d'un moyen pour exécuter le projet localement et y accéder via un navigateur web. L'installation et le développement local peuvent être accomplis avec npm et un outil de build, ou en important three.js depuis un CDN. Les deux options sont expliquées dans les sections ci-dessous.

Option 1 : Installation avec NPM et un outil de build

Développement

L'installation depuis le [link:https://www.npmjs.com/ registre de packages npm] et l'utilisation d'un [link:https://eloquentjavascript.net/10_modules.html#h_zWTXAU93DC outil de build] est l'approche recommandée pour la plupart des utilisateurs — plus votre projet a de dépendances, plus vous êtes susceptible de rencontrer des problèmes que l'hébergement statique ne peut pas facilement résoudre. Avec un outil de build, l'importation de fichiers JavaScript locaux et de packages npm devrait fonctionner directement, sans cartes d'importation.

Installez [link:https://nodejs.org/ Node.js]. Nous en aurons besoin pour gérer les dépendances et exécuter notre outil de build.
Installez three.js et un outil de build, [link:https://vitejs.dev/ Vite], en utilisant un [link:https://www.joshwcomeau.com/javascript/terminal-for-js-devs/ terminal] dans le dossier de votre projet. Vite sera utilisé pendant le développement, mais ne fait pas partie de la page web finale. Si vous préférez utiliser un autre outil de build, c'est bien — nous supportons les outils de build modernes qui peuvent importer les [link:https://eloquentjavascript.net/10_modules.html#h_zWTXAU93DC Modules ES].
```
# three.js
npm install --save three

# vite
npm install --save-dev vite
```
L'installation a ajouté les dossiers node_modules/ et package.json à mon projet. De quoi s'agit-il ?

npm utilise package.json pour décrire quelles versions de chaque dépendance vous avez installées. Si vous travaillez sur le projet avec d'autres personnes, elles peuvent installer les versions originales de chaque dépendance simplement en exécutant npm install. Si vous utilisez l'historique des versions, commitez package.json.

npm installe le code de chaque dépendance dans un nouveau dossier node_modules/. Lorsque Vite construit votre application, il voit les importations pour 'three' et extrait automatiquement les fichiers three.js de ce dossier. Le dossier node_modules/ est utilisé uniquement pendant le développement, et ne doit pas être téléversé chez votre hébergeur web ou commité dans l'historique des versions.
Améliorez l'auto-complétion de votre éditeur avec jsconfig ou tsconfig

Placez un fichier jsconfig.json (ou tsconfig.json pour les projets TypeScript) à la racine de votre projet. L'ajout de la configuration ci-dessous aide votre éditeur à localiser les fichiers three.js pour une auto-complétion améliorée.
```
{
  "compilerOptions": {
    // other options...
    "paths": {
      "three/webgpu": ["node_modules/three/build/three.webgpu.js"],
      "three/tsl": ["node_modules/three/build/three.tsl.js"],
    },
  }
}
```
Depuis votre terminal, exécutez :
```
npx vite 
```
Qu'est-ce que npx ?

npx est installé avec Node.js, et exécute des programmes en ligne de commande comme Vite afin que vous n'ayez pas à chercher vous-même le bon fichier dans node_modules/. Si vous préférez, vous pouvez mettre les [link:https://vitejs.dev/guide/#command-line-interface commandes courantes de Vite] dans la liste [link:https://docs.npmjs.com/cli/v9/using-npm/scripts package.json:scripts], et utiliser npm run dev à la place.
Si tout s'est bien passé, vous verrez une URL comme http://localhost:5173 apparaître dans votre terminal, et vous pourrez ouvrir cette URL pour voir votre application web.

La page sera vide — vous êtes prêt à créer une scène.

Si vous voulez en savoir plus sur ces outils avant de continuer, consultez :

[link:https://threejs-journey.com/lessons/local-server three.js journey : Serveur local]
[link:https://vitejs.dev/guide/cli.html Vite : Interface en ligne de commande]
[link:https://developer.mozilla.org/en-US/docs/Learn/Tools_and_testing/Understanding_client-side_tools/Package_management MDN : Principes de base de la gestion des packages]

Production

Plus tard, lorsque vous serez prêt à déployer votre application web, il vous suffira d'indiquer à Vite d'exécuter une build de production — npx vite build. Tout ce qui est utilisé par l'application sera compilé, optimisé et copié dans le dossier dist/. Le contenu de ce dossier est prêt à être hébergé sur votre site web.

Option 2 : Importation depuis un CDN

Développement

L'installation sans outils de build nécessitera quelques modifications de la structure du projet donnée ci-dessus.

Nous avons importé du code depuis 'three' (un package npm) dans main.js, et les navigateurs web ne savent pas ce que cela signifie. Dans index.html, nous devrons ajouter une [link:https://developer.mozilla.org/en-US/docs/Web/HTML/Element/script/type/importmap carte d'importation] définissant où obtenir le package. Placez le code ci-dessous à l'intérieur de la balise <head></head>, après les styles.
```
<script type="importmap">
{
  "imports": {
    "three": "https://cdn.jsdelivr.net/npm/three@<version>/build/three.module.js",
    "three/addons/": "https://cdn.jsdelivr.net/npm/three@<version>/examples/jsm/"
  }
}
</script>
```
N'oubliez pas de remplacer <version> par une version réelle de three.js, comme "v0.149.0". La version la plus récente peut être trouvée sur la [link:https://www.npmjs.com/package/three?activeTab=versions liste des versions npm].
Nous aurons également besoin d'exécuter un serveur local pour héberger ces fichiers à une URL accessible par le navigateur web. Bien qu'il soit techniquement possible de double-cliquer sur un fichier HTML et de l'ouvrir dans votre navigateur, des fonctionnalités importantes que nous implémenterons plus tard ne fonctionnent pas lorsque la page est ouverte de cette manière, pour des raisons de sécurité.

Installez [link:https://nodejs.org/ Node.js], puis exécutez [link:https://www.npmjs.com/package/serve serve] pour démarrer un serveur local dans le répertoire du projet :
```
npx serve .
```
Si tout s'est bien passé, vous verrez une URL comme http://localhost:3000 apparaître dans votre terminal, et vous pourrez ouvrir cette URL pour voir votre application web.

La page sera vide — vous êtes prêt à [link:#manual/introduction/Creating-a-scene créer une scène].

De nombreux autres serveurs statiques locaux sont disponibles — certains utilisent des langages différents au lieu de Node.js, et d'autres sont des applications de bureau. Ils fonctionnent tous fondamentalement de la même manière, et nous avons fourni quelques alternatives ci-dessous.

Plus de serveurs locaux

Ligne de commande

Les serveurs locaux en ligne de commande s'exécutent depuis une fenêtre de terminal. Le langage de programmation associé peut devoir être installé au préalable.

npx http-server (Node.js)
npx five-server (Node.js)
python -m SimpleHTTPServer (Python 2.x)
python -m http.server (Python 3.x)
php -S localhost:8000 (PHP 5.4+)

GUI

Les serveurs locaux GUI s'exécutent sous forme de fenêtre d'application sur votre ordinateur, et peuvent avoir une interface utilisateur.

[link:https://greggman.github.io/servez Servez]

Plugins d'éditeur de code

Certains éditeurs de code disposent de plugins qui lancent un simple serveur à la demande.

[link:https://marketplace.visualstudio.com/items?itemName=yandeu.five-server Five Server] pour Visual Studio Code
[link:https://marketplace.visualstudio.com/items?itemName=ritwickdey.LiveServer Live Server] pour Visual Studio Code
[link:https://atom.io/packages/atom-live-server Live Server] pour Atom

Production

Lorsque vous êtes prêt à déployer votre application web, poussez les fichiers source chez votre hébergeur web — pas besoin de build ou de compiler quoi que ce soit. L'inconvénient de ce compromis est que vous devrez veiller à maintenir la carte d'importation à jour avec toutes les dépendances (et les dépendances des dépendances !) dont votre application a besoin. Si le CDN hébergeant vos dépendances tombe temporairement, votre site web cessera également de fonctionner.

IMPORTANT : Importez toutes les dépendances depuis la même version de three.js et depuis le même CDN. Mélanger des fichiers de différentes sources peut entraîner l'inclusion de code dupliqué, ou même casser l'application de manière inattendue.

Addons

Par défaut, three.js inclut les fondamentaux d'un moteur 3D. Les autres composants de three.js — tels que les contrôles, les chargeurs et les effets de post-traitement — font partie du répertoire [link:https://github.com/mrdoob/three.js/tree/dev/examples/jsm addons/]. Les Addons n'ont pas besoin d'être installés séparément, mais doivent être importés séparément.

L'exemple ci-dessous montre comment importer three.js avec les addons `OrbitControls` et `GLTFLoader`. Si nécessaire, cela sera également mentionné dans la documentation ou les exemples de chaque addon.

import * as THREE from 'three';
import { OrbitControls } from 'three/addons/controls/OrbitControls.js';
import { GLTFLoader } from 'three/addons/loaders/GLTFLoader.js';

const controls = new OrbitControls( camera, renderer.domElement );
const loader = new GLTFLoader();

D'excellents projets tiers sont également disponibles pour three.js. Ceux-ci doivent être installés séparément — voir Bibliothèques et Plugins.

Étapes suivantes

Vous êtes maintenant prêt à créer une scène.