From e15874e94e3c213c1589093562e6e01c5322feac Mon Sep 17 00:00:00 2001 From: Don McCurdy Date: Wed, 10 Jun 2020 19:28:22 -0700 Subject: [PATCH 1/2] Docs: Update 'Installation' section for ES Module migration. --- docs/list.js | 2 +- .../en/introduction/Import-via-modules.html | 81 ---------- docs/manual/en/introduction/Installation.html | 149 ++++++++++++++++++ .../zh/introduction/Import-via-modules.html | 80 ---------- docs/manual/zh/introduction/Installation.html | 149 ++++++++++++++++++ 5 files changed, 299 insertions(+), 162 deletions(-) delete mode 100644 docs/manual/en/introduction/Import-via-modules.html create mode 100644 docs/manual/en/introduction/Installation.html delete mode 100644 docs/manual/zh/introduction/Import-via-modules.html create mode 100644 docs/manual/zh/introduction/Installation.html diff --git a/docs/list.js b/docs/list.js index 8e8f306af74a6d..cbfbdb3d35e201 100644 --- a/docs/list.js +++ b/docs/list.js @@ -6,7 +6,7 @@ var list = { "Getting Started": { "Creating a scene": "manual/en/introduction/Creating-a-scene", - "Import via modules": "manual/en/introduction/Import-via-modules", + "Installation": "manual/en/introduction/Installation", "Browser support": "manual/en/introduction/Browser-support", "WebGL compatibility check": "manual/en/introduction/WebGL-compatibility-check", "How to run things locally": "manual/en/introduction/How-to-run-things-locally", diff --git a/docs/manual/en/introduction/Import-via-modules.html b/docs/manual/en/introduction/Import-via-modules.html deleted file mode 100644 index 47e775a94d7972..00000000000000 --- a/docs/manual/en/introduction/Import-via-modules.html +++ /dev/null @@ -1,81 +0,0 @@ - - - - - - - - - - -

[name]

- -

- While importing three.js via script tags is a great way to get up and running fast, it has a few drawbacks for longer lived projects, for example: -

-

- -

Using a dependency manager like npm avoids these caveats by allowing you to simply download and import your desired version of the library onto your machine.

- -

Installation via npm

- -

Three.js is published as an npm module, see: [link:https://www.npmjs.com/package/three npm]. This means all you need to do to include three.js into your project is run "npm install three"

- -

Importing the module

- -

Assuming that you're bundling your files with a tool such as [link:https://webpack.github.io/ Webpack] or [link:https://github.com/substack/node-browserify Browserify], which allow you to "require('modules')" in the browser by bundling up all of your dependencies.

- -

- You should now be able to import the module into your source files and continue to use it as per normal. -

- - - var THREE = require('three'); - - var scene = new THREE.Scene(); - ... - - -

- You're also able to leverage [link:https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/import ES6 import syntax]: -

- - - import * as THREE from 'three'; - - const scene = new THREE.Scene(); - ... - - -

- or if you wish to import only select parts of three.js library, for example Scene: -

- - - import { Scene } from 'three'; - - const scene = new Scene(); - ... - - -

Importable Examples

-

- The core of three.js is focused on the most important components of a 3D engine. Many other components like loaders or controls are part of the - examples directory. three.js ensures that these files are kept in sync with the core but users have to import them separately if they are required - for a project. You can find them in the [link:https://github.com/mrdoob/three.js/tree/master/examples/jsm examples/jsm] directory. If you install three.js - via npm, import example files like so: -

- - import { OrbitControls } from 'three/examples/jsm/controls/OrbitControls.js'; - -

- Note: When using code from the examples directory, it's important that all files match the version of - your three.js main file. For example, it's not acceptable to use *GLTFLoader* and *OrbitControls* from R96 together - with three.js R103. -

- - diff --git a/docs/manual/en/introduction/Installation.html b/docs/manual/en/introduction/Installation.html new file mode 100644 index 00000000000000..97694f18acf0a5 --- /dev/null +++ b/docs/manual/en/introduction/Installation.html @@ -0,0 +1,149 @@ + + + + + + + + + + +

[name]

+ +

+ You can install three.js with [link:https://www.npmjs.com/ npm] and modern build tools, or get started quickly with just static hosting or a CDN. For most users, installing from npm is the best choice. +

+ +

+ Whichever you choose, be consistent and import all files from the same version of the library. Mixing files from different sources may cause duplicate code to be included, or even break the application in unexpected ways. +

+ +

+ All methods of installing three.js depend on ES modules (see [link:https://eloquentjavascript.net/10_modules.html#h_hF2FmOVxw7 Eloquent JavaScript: ECMAScript Modules], which allow you to include only the parts of the library needed in the final project. +

+ +

Install from npm

+ +

+ Three.js is published as [link:https://www.npmjs.com/package/three three] on npm. To install the three.js npm module, open a terminal window in your project folder and run: +

+ + + npm install --save three + + +

+ The package will be downloaded and installed. Then you're ready to import it in your code: +

+ + + /////////////////////////////////////////////////////// + // 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(); + + +

+ When installing from npm, you'll almost always use some sort of [link:https://eloquentjavascript.net/10_modules.html#h_zWTXAU93DC bundling tool] to combine all of the packages your project requires into a single JavaScript file. While any modern JavaScript bundler can be used with three.js, the most popular choice is [link:https://webpack.js.org/ webpack]. +

+ +

+ Not all features are accessed directly through the three module (also called a "bare import"). Other popular parts of the library — such as controls, loaders, and post-processing effects — must be imported from the [link:https://github.com/mrdoob/three.js/tree/dev/examples/jsm examples/jsm] subfolder. To learn more, see Examples below. +

+ +

+ Learn more about npm modules from [link:https://eloquentjavascript.net/20_node.html#h_J6hW/SmL/a Eloquent JavaScript: Installing with npm]. +

+ +

Install from CDN or static hosting

+ +

+ Three.js can be used without any build system, either by uploading files to your own web server or by using an existing CDN. Because the library relies on ES modules, any script that references it must use type="module" as shown below: +

+ + + <script type="module"> + + // Find the latest version by visiting https://unpkg.com/three. The URL will + // redirect to the newest stable release. + import * as THREE from 'https://unpkg.com/three@<VERSION>/build/three.module.js'; + + const scene = new THREE.Scene(); + + </script> + + +

+ Not all features are accessed through the build/three.module.js module. Other popular parts of the library — such as controls, loaders, and post-processing effects — must be imported from the [link:https://github.com/mrdoob/three.js/tree/dev/examples/jsm examples/jsm] subfolder. To learn more, see Examples below. +

+ + +

Examples

+ +

+ The core of three.js is focused on the most important components of a 3D engine. Many other useful components — such as controls, loaders, and post-processing effects — are part of the [link:https://github.com/mrdoob/three.js/tree/dev/examples/jsm examples/jsm] directory. They are referred to as "examples," because while you can use them off the shelf, they're also meant to be remixed and customized. These components are always kept in sync with the core library, whereas similar third-party packages on npm are maintained by different people and may not be up to date. +

+ +

+ Examples do not need to be installed separately, but do need to be imported separately. If three.js was installed with npm, you can load the [page:OrbitControls] component with: +

+ + + + import { OrbitControls } from 'three/examples/jsm/controls/OrbitControls.js'; + + const controls = new OrbitControls(); + + +

+ If three.js was installed from a CDN, use the same CDN to install other components: +

+ + + <script type="module"> + + // Find the latest version by visiting https://unpkg.com/three. The URL will + // redirect to the newest stable release. + import { OrbitControls } from 'https://unpkg.com/three@<VERSION>/examples/jsm/controls/OrbitControls.js'; + + const controls = new OrbitControls(); + + </script> + + +

+ It's important that all files use the same version. Do not import different examples from different versions, or use examples from a different version than the three.js library itself. +

+ +

Compatibility

+ +

CommonJS imports

+ +

+ While most modern JavaScript bundlers now support ES modules by default, some older build tools might not. In those cases you can likely configure the bundler to understand ES modules: [link:http://browserify.org/ Browserify] just needs the [link:https://github.com/babel/babelify babelify] plugin, for example. +

+ +

Node.js

+ +

+ Using three.js in [link:https://eloquentjavascript.net/20_node.html Node.js] can be difficult, for two reasons: +

+ +

+ First, because three.js is built for the web, it depends on browser and DOM APIs that don't always exist Node.js. Some of these issues can be resolved by using shims like [link:https://github.com/stackgl/headless-gl headless-gl], or by replacing components like [page:TextureLoader] with custom alternatives. Other DOM APIs may be deeply intertwined with the code that uses them, and will be harder to work around. We welcome simple and maintainable pull requests to improve Node.js support, but recommend opening an issue to discuss your improvements first. +

+ +

+ Second, Node.js support for ES modules is ... complicated. As of Node.js v12, the core library can be imported as a CommonJS module, with require('three'). However, most example components in examples/jsm cannot. Future versions of Node.js may resolve this, but in the meantime you may need to use workarounds like [link:https://github.com/standard-things/esm esm] to enable your Node.js application to recognize ES modules. +

+ + + diff --git a/docs/manual/zh/introduction/Import-via-modules.html b/docs/manual/zh/introduction/Import-via-modules.html deleted file mode 100644 index 48543a39b079dd..00000000000000 --- a/docs/manual/zh/introduction/Import-via-modules.html +++ /dev/null @@ -1,80 +0,0 @@ - - - - - - - - - - -

通过模块来引入（[name]）

- -

- 虽然通过script标签来引入three.js是一个能够快速起步、快速运行的方式，但这种方式对于一些具有较长生命周期的项目来说是有一些缺点。比如： - -

-

- -

使用像npm这样的依赖包管理器，你只需在你的机器上下载并导入你所需要的版本的库就很好地避免这些需要注意的问题。

- -

通过npm来安装

- -

Three.js目前已经作为一个npm模块来进行了发布，详情请参阅：[link:https://www.npmjs.com/package/three npm]。这意味着你只需运行"npm install three"就可以使你的项目包含three.js库。

- -

导入这个模块

- -

假设你正在使用[link:https://webpack.github.io/ Webpack]或者[link:https://github.com/substack/node-browserify Browserify]等允许你“通过打包所有依赖，来在浏览器中使用require('modules')”的打包工具对你的文件进行打包。

- -

你现在可以在你的源代码中引入模块，并继续像往常一样使用这个库。 -

- - - var THREE = require('three'); - - var scene = new THREE.Scene(); - ... - - -

- 你也可以使用[link:https://developer.mozilla.org/zh-CN/docs/Web/JavaScript/Reference/Statements/import ES6 import]（在ES6标准中新增的import语句） -

- - - import * as THREE from 'three'; - - const scene = new THREE.Scene(); - ... - - -

- 或者，如果你希望只导入three.js库中的特定部分，例如Scene： -

- - - import { Scene } from 'three'; - - const scene = new Scene(); - ... - - -

可引入的示例

-

- The core of three.js is focused on the most important components of a 3D engine. Many other components like loaders or controls are part of the - examples directory. three.js ensures that these files are kept in sync with the core but users have to import them separately if they are required - for a project. You can find them in the [link:https://github.com/mrdoob/three.js/tree/master/examples/jsm examples/jsm] directory. If you install three.js - via npm, import example files like so: -

- - import { OrbitControls } from 'three/examples/jsm/controls/OrbitControls.js'; - -

- 请注意：当你在使用来自示例（examples）文件夹中的代码时，其中的所有文件和你的three.js主文件版本相匹配是很重要的。 - 比如说，three.js的R103版本不能够接受和来自R96版本的*GLTFLoader*和*OrbitControls*一起使用。 -

- - diff --git a/docs/manual/zh/introduction/Installation.html b/docs/manual/zh/introduction/Installation.html new file mode 100644 index 00000000000000..41850a59b400c4 --- /dev/null +++ b/docs/manual/zh/introduction/Installation.html @@ -0,0 +1,149 @@ + + + + + + + + + + +

通过模块来引入（[name]）

+ +

+ You can install three.js with [link:https://www.npmjs.com/ npm] and modern build tools, or get started quickly with just static hosting or a CDN. For most users, installing from npm is the best choice. +

+ +

+ Whichever you choose, be consistent and import all files from the same version of the library. Mixing files from different sources may cause duplicate code to be included, or even break the application in unexpected ways. +

+ +

+ All methods of installing three.js depend on ES modules (see [link:https://eloquentjavascript.net/10_modules.html#h_hF2FmOVxw7 Eloquent JavaScript: ECMAScript Modules], which allow you to include only the parts of the library needed in the final project. +

+ +

Install from npm

+ +

+ Three.js is published as [link:https://www.npmjs.com/package/three three] on npm. To install the three.js npm module, open a terminal window in your project folder and run: +

+ + + npm install --save three + + +

+ The package will be downloaded and installed. Then you're ready to import it in your code: +

+ + + /////////////////////////////////////////////////////// + // 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(); + + +

+ When installing from npm, you'll almost always use some sort of [link:https://eloquentjavascript.net/10_modules.html#h_zWTXAU93DC bundling tool] to combine all of the packages your project requires into a single JavaScript file. While any modern JavaScript bundler can be used with three.js, the most popular choice is [link:https://webpack.js.org/ webpack]. +

+ +

+ Not all features are accessed directly through the three module (also called a "bare import"). Other popular parts of the library — such as controls, loaders, and post-processing effects — must be imported from the [link:https://github.com/mrdoob/three.js/tree/dev/examples/jsm examples/jsm] subfolder. To learn more, see Examples below. +

+ +

+ Learn more about npm modules from [link:https://eloquentjavascript.net/20_node.html#h_J6hW/SmL/a Eloquent JavaScript: Installing with npm]. +

+ +

Install from CDN or static hosting

+ +

+ Three.js can be used without any build system, either by uploading files to your own web server or by using an existing CDN. Because the library relies on ES modules, any script that references it must use type="module" as shown below: +

+ + + <script type="module"> + + // Find the latest version by visiting https://unpkg.com/three. The URL will + // redirect to the newest stable release. + import * as THREE from 'https://unpkg.com/three@<VERSION>/build/three.module.js'; + + const scene = new THREE.Scene(); + + </script> + + +

+ Not all features are accessed through the build/three.module.js module. Other popular parts of the library — such as controls, loaders, and post-processing effects — must be imported from the [link:https://github.com/mrdoob/three.js/tree/dev/examples/jsm examples/jsm] subfolder. To learn more, see Examples below. +

+ + +

Examples

+ +

+ The core of three.js is focused on the most important components of a 3D engine. Many other useful components — such as controls, loaders, and post-processing effects — are part of the [link:https://github.com/mrdoob/three.js/tree/dev/examples/jsm examples/jsm] directory. They are referred to as "examples," because while you can use them off the shelf, they're also meant to be remixed and customized. These components are always kept in sync with the core library, whereas similar third-party packages on npm are maintained by different people and may not be up to date. +

+ +

+ Examples do not need to be installed separately, but do need to be imported separately. If three.js was installed with npm, you can load the [page:OrbitControls] component with: +

+ + + + import { OrbitControls } from 'three/examples/jsm/controls/OrbitControls.js'; + + const controls = new OrbitControls(); + + +

+ If three.js was installed from a CDN, use the same CDN to install other components: +

+ + + <script type="module"> + + // Find the latest version by visiting https://unpkg.com/three. The URL will + // redirect to the newest stable release. + import { OrbitControls } from 'https://unpkg.com/three@<VERSION>/examples/jsm/controls/OrbitControls.js'; + + const controls = new OrbitControls(); + + </script> + + +

+ It's important that all files use the same version. Do not import different examples from different versions, or use examples from a different version than the three.js library itself. +

+ +

Compatibility

+ +

CommonJS imports

+ +

+ While most modern JavaScript bundlers now support ES modules by default, some older build tools might not. In those cases you can likely configure the bundler to understand ES modules: [link:http://browserify.org/ Browserify] just needs the [link:https://github.com/babel/babelify babelify] plugin, for example. +

+ +

Node.js

+ +

+ Using three.js in [link:https://eloquentjavascript.net/20_node.html Node.js] can be difficult, for two reasons: +

+ +

+ First, because three.js is built for the web, it depends on browser and DOM APIs that don't always exist Node.js. Some of these issues can be resolved by using shims like [link:https://github.com/stackgl/headless-gl headless-gl], or by replacing components like [page:TextureLoader] with custom alternatives. Other DOM APIs may be deeply intertwined with the code that uses them, and will be harder to work around. We welcome simple and maintainable pull requests to improve Node.js support, but recommend opening an issue to discuss your improvements first. +

+ +

+ Second, Node.js support for ES modules is ... complicated. As of Node.js v12, the core library can be imported as a CommonJS module, with require('three'). However, most example components in examples/jsm cannot. Future versions of Node.js may resolve this, but in the meantime you may need to use workarounds like [link:https://github.com/standard-things/esm esm] to enable your Node.js application to recognize ES modules. +

+ + + From 88127a0d4d79591101996d2c80ab73ea9c973508 Mon Sep 17 00:00:00 2001 From: Don McCurdy Date: Wed, 10 Jun 2020 22:03:50 -0700 Subject: [PATCH 2/2] Docs: Three.js -> three.js --- docs/manual/en/introduction/Installation.html | 4 ++-- docs/manual/zh/introduction/Installation.html | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/manual/en/introduction/Installation.html b/docs/manual/en/introduction/Installation.html index 97694f18acf0a5..41fea257d8ccbb 100644 --- a/docs/manual/en/introduction/Installation.html +++ b/docs/manual/en/introduction/Installation.html @@ -25,7 +25,7 @@

[name]

Install from npm

- Three.js is published as [link:https://www.npmjs.com/package/three three] on npm. To install the three.js npm module, open a terminal window in your project folder and run: + To install the [link:https://www.npmjs.com/package/three three] npm module, open a terminal window in your project folder and run:

@@ -66,7 +66,7 @@

Install from npm

Install from CDN or static hosting

- Three.js can be used without any build system, either by uploading files to your own web server or by using an existing CDN. Because the library relies on ES modules, any script that references it must use type="module" as shown below: + The three.js library can be used without any build system, either by uploading files to your own web server or by using an existing CDN. Because the library relies on ES modules, any script that references it must use type="module" as shown below:

diff --git a/docs/manual/zh/introduction/Installation.html b/docs/manual/zh/introduction/Installation.html index 41850a59b400c4..31558a4bc6bc75 100644 --- a/docs/manual/zh/introduction/Installation.html +++ b/docs/manual/zh/introduction/Installation.html @@ -25,7 +25,7 @@

通过模块来引入（[name]）

Install from npm

- Three.js is published as [link:https://www.npmjs.com/package/three three] on npm. To install the three.js npm module, open a terminal window in your project folder and run: + To install the [link:https://www.npmjs.com/package/three three] npm module, open a terminal window in your project folder and run:

@@ -66,7 +66,7 @@

Install from npm

Install from CDN or static hosting

- Three.js can be used without any build system, either by uploading files to your own web server or by using an existing CDN. Because the library relies on ES modules, any script that references it must use type="module" as shown below: + The three.js library can be used without any build system, either by uploading files to your own web server or by using an existing CDN. Because the library relies on ES modules, any script that references it must use type="module" as shown below: