Skip to content

Commit 3ba8016

Browse files
chenxsanchenxsan
authored
docs(guides): update getting-started against webpack 5 (#4134)
1 parent 75d8a90 commit 3ba8016

File tree

1 file changed

+95
-93
lines changed

1 file changed

+95
-93
lines changed

‎src/content/guides/getting-started.md

Lines changed: 95 additions & 93 deletions
Original file line numberDiff line numberDiff line change
@@ -25,9 +25,9 @@ contributors:
2525
- anshumanv
2626
---
2727

28-
webpack is used to compile JavaScript modules. Once [installed](/guides/installation), you can interface with webpack either from its [CLI](/api/cli) or [API](/api/node). If you're still new to webpack, please read through the [core concepts](/concepts) and [this comparison](/comparison) to learn why you might use it over the other tools that are out in the community.
28+
webpack is used to compile JavaScript modules. Once [installed](/guides/installation), you can interact with webpack either from its [CLI](/api/cli) or [API](/api/node). If you're still new to webpack, please read through the [core concepts](/concepts) and [this comparison](/comparison) to learn why you might use it over the other tools that are out in the community.
2929

30-
W> Since webpack v5.0.0-beta.1 the minimum Node.js version to run webpack is 10.13.0 (LTS)
30+
W> The minimum Node.js version to run webpack 5 is 10.13.0 (LTS)
3131

3232
## Basic Setup
3333

@@ -40,7 +40,13 @@ npm init -y
4040
npm install webpack webpack-cli --save-dev
4141
```
4242

43-
T> Throughout the Guides we will use `diff` blocks to show you what changes we're making to directories, files, and code.
43+
Throughout the Guides we will use __`diff`__ blocks to show you what changes we're making to directories, files, and code. For instance:
44+
45+
```diff
46+
+ this is a new line you shall copy into your code
47+
- and this is a line to be removed from your code
48+
and this is a line not to touch.
49+
```
4450

4551
Now we'll create the following directory structure, files and their contents:
4652

@@ -72,12 +78,12 @@ document.body.appendChild(component());
7278
__index.html__
7379

7480
``` html
75-
<!doctype html>
81+
<!DOCTYPE html>
7682
<html>
7783
<head>
78-
<meta charset="utf-8"/>
84+
<meta charset="utf-8" />
7985
<title>Getting Started</title>
80-
<script src="https://unpkg.com/lodash@4.16.6"></script>
86+
<script src="https://unpkg.com/lodash@4.17.20"></script>
8187
</head>
8288
<body>
8389
<script src="./src/index.js"></script>
@@ -92,24 +98,23 @@ T> If you want to learn more about the inner workings of `package.json`, then we
9298
__package.json__
9399

94100
``` diff
95-
{
96-
"name": "webpack-demo",
97-
"version": "1.0.0",
98-
"description": "",
99-
+ "private": true,
100-
- "main": "index.js",
101-
"scripts": {
102-
"test": "echo \"Error: no test specified\" && exit 1"
103-
},
104-
"keywords": [],
105-
"author": "",
106-
"license": "ISC",
107-
"devDependencies": {
108-
"webpack": "^4.20.2",
109-
"webpack-cli": "^3.1.2"
110-
},
111-
"dependencies": {}
112-
}
101+
{
102+
"name": "webpack-demo",
103+
"version": "1.0.0",
104+
"description": "",
105+
- "main": "index.js",
106+
+ "private": true,
107+
"scripts": {
108+
"test": "echo \"Error: no test specified\" && exit 1"
109+
},
110+
"keywords": [],
111+
"author": "",
112+
"license": "ISC",
113+
"devDependencies": {
114+
"webpack": "^5.4.0",
115+
"webpack-cli": "^4.2.0"
116+
}
117+
}
113118
```
114119

115120
In this example, there are implicit dependencies between the `<script>` tags. Our `index.js` file depends on `lodash` being included in the page before it runs. This is because `index.js` never explicitly declared a need for `lodash`; it just assumes that the global variable `_` exists.
@@ -151,61 +156,58 @@ Now, lets import `lodash` in our script:
151156
__src/index.js__
152157

153158
``` diff
154-
+ import _ from 'lodash';
159+
+import _ from 'lodash';
155160
+
156-
function component() {
157-
const element = document.createElement('div');
158-
159-
- // Lodash, currently included via a script, is required for this line to work
160-
+ // Lodash, now imported by this script
161-
element.innerHTML = _.join(['Hello', 'webpack'], ' ');
162-
163-
return element;
164-
}
165-
166-
document.body.appendChild(component());
161+
function component() {
162+
const element = document.createElement('div');
163+
164+
- // Lodash, currently included via a script, is required for this line to work
165+
+ // Lodash, now imported by this script
166+
element.innerHTML = _.join(['Hello', 'webpack'], ' ');
167+
168+
return element;
169+
}
170+
171+
document.body.appendChild(component());
167172
```
168173

169174
Now, since we'll be bundling our scripts, we have to update our `index.html` file. Let's remove the lodash `<script>`, as we now `import` it, and modify the other `<script>` tag to load the bundle, instead of the raw `/src` file:
170175

171176
__dist/index.html__
172177

173178
``` diff
174-
<!doctype html>
175-
<html>
179+
<!DOCTYPE html>
180+
<html>
176181
<head>
177-
<meta charset="utf-8"/>
182+
<meta charset="utf-8" />
178183
<title>Getting Started</title>
179-
- <script src="https://unpkg.com/lodash@4.16.6"></script>
184+
- <script src="https://unpkg.com/lodash@4.17.20"></script>
180185
</head>
181186
<body>
182187
- <script src="./src/index.js"></script>
183188
+ <script src="main.js"></script>
184189
</body>
185-
</html>
190+
</html>
186191
```
187192

188193
In this setup, `index.js` explicitly requires `lodash` to be present, and binds it as `_` (no global scope pollution). By stating what dependencies a module needs, webpack can use this information to build a dependency graph. It then uses the graph to generate an optimized bundle where scripts will be executed in the correct order.
189194

190195
With that said, let's run `npx webpack`, which will take our script at `src/index.js` as the [entry point](/concepts/entry-points), and will generate `dist/main.js` as the [output](/concepts/output). The `npx` command, which ships with Node 8.2/npm 5.2.0 or higher, runs the webpack binary (`./node_modules/.bin/webpack`) of the webpack package we installed in the beginning:
191196

192197
``` bash
193-
npx webpack
194-
195-
...
196-
Built at: 13/06/2018 11:52:07
197-
Asset Size Chunks Chunk Names
198-
main.js 70.4 KiB 0 [emitted] main
199-
...
200-
201-
WARNING in configuration
202-
The 'mode' option has not been set, webpack will fallback to 'production' for this value. Set 'mode' option to 'development' or 'production' to enable defaults for each environment.
203-
You can also set it to 'none' to disable any default behavior. Learn more: https://webpack.js.org/configuration/mode/
198+
$ npx webpack
199+
[webpack-cli] Compilation finished
200+
asset main.js 69.3 KiB [emitted] [minimized] (name: main) 1 related asset
201+
runtime modules 1000 bytes 5 modules
202+
cacheable modules 530 KiB
203+
./src/index.js 257 bytes [built] [code generated]
204+
./node_modules/lodash/lodash.js 530 KiB [built] [code generated]
205+
webpack 5.4.0 compiled successfully in 3619 ms
204206
```
205207

206208
T> Your output may vary a bit, but if the build is successful then you are good to go. Also, don't worry about the warning, we'll tackle that later.
207209

208-
Open `index.html` from the `dist` directory in your browser and, if everything went right, you should see the following text: 'Hello webpack'.
210+
Open `index.html` from the `dist` directory in your browser and, if everything went right, you should see the following text: `'Hello webpack'`.
209211

210212
W> If you are getting a syntax error in the middle of minified JavaScript when opening `index.html` in the browser, set [`development mode`](/configuration/mode/#mode-development) and run `npx webpack` again. This is related to running `npx webpack` on latest Node.js (v12.5+) instead of [LTS version](https://nodejs.org/en/).
211213

@@ -214,7 +216,7 @@ W> If you are getting a syntax error in the middle of minified JavaScript when o
214216

215217
The [`import`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/import) and [`export`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/export) statements have been standardized in [ES2015](https://babeljs.io/docs/en/learn/). They are supported in most of the browsers at this moment, however there are some browsers that don't recognize the new syntax. But don't worry, webpack does support them out of the box.
216218

217-
Behind the scenes, webpack actually "transpiles" the code so that older browsers can also run it. If you inspect `dist/main.js`, you might be able to see how webpack does this, it's quite ingenious! Besides `import` and `export`, webpack supports various other module syntaxes as well, see [Module API](/api/module-methods) for more information.
219+
Behind the scenes, webpack actually "__transpiles__" the code so that older browsers can also run it. If you inspect `dist/main.js`, you might be able to see how webpack does this, it's quite ingenious! Besides `import` and `export`, webpack supports various other module syntaxes as well, see [Module API](/api/module-methods) for more information.
218220

219221
Note that webpack will not alter any code other than `import` and `export` statements. If you are using other [ES2015 features](http://es6-features.org/), make sure to [use a transpiler](/loaders/#transpiling) such as [Babel](https://babeljs.io/) or [Bublé](https://buble.surge.sh/guide/) via webpack's [loader system](/concepts/loaders/).
220222

@@ -252,16 +254,14 @@ module.exports = {
252254
Now, let's run the build again but instead using our new configuration file:
253255

254256
``` bash
255-
npx webpack --config webpack.config.js
256-
257-
...
258-
Asset Size Chunks Chunk Names
259-
main.js 70.4 KiB 0 [emitted] main
260-
...
261-
262-
WARNING in configuration
263-
The 'mode' option has not been set, webpack will fallback to 'production' for this value. Set 'mode' option to 'development' or 'production' to enable defaults for each environment.
264-
You can also set it to 'none' to disable any default behavior. Learn more: https://webpack.js.org/configuration/mode/
257+
$ npx webpack --config webpack.config.js
258+
[webpack-cli] Compilation finished
259+
asset main.js 69.3 KiB [compared for emit] [minimized] (name: main) 1 related asset
260+
runtime modules 1000 bytes 5 modules
261+
cacheable modules 530 KiB
262+
./src/index.js 257 bytes [built] [code generated]
263+
./node_modules/lodash/lodash.js 530 KiB [built] [code generated]
264+
webpack 5.4.0 compiled successfully in 3516 ms
265265
```
266266

267267
T> If a `webpack.config.js` is present, the `webpack` command picks it up by default. We use the `--config` option here only to show that you can pass a configuration of any name. This will be useful for more complex configurations that need to be split into multiple files.
@@ -276,46 +276,48 @@ Given it's not particularly fun to run a local copy of webpack from the CLI, we
276276
__package.json__
277277

278278
``` diff
279-
{
280-
"name": "webpack-demo",
281-
"version": "1.0.0",
282-
"description": "",
283-
"scripts": {
284-
- "test": "echo \"Error: no test specified\" && exit 1"
285-
+ "test": "echo \"Error: no test specified\" && exit 1",
286-
+ "build": "webpack"
287-
},
288-
"keywords": [],
289-
"author": "",
290-
"license": "ISC",
291-
"devDependencies": {
292-
"webpack": "^4.20.2",
293-
"webpack-cli": "^3.1.2"
294-
},
295-
"dependencies": {
296-
"lodash": "^4.17.5"
297-
}
298-
}
279+
{
280+
"name": "webpack-demo",
281+
"version": "1.0.0",
282+
"description": "",
283+
"private": true,
284+
"scripts": {
285+
- "test": "echo \"Error: no test specified\" && exit 1"
286+
+ "test": "echo \"Error: no test specified\" && exit 1",
287+
+ "build": "webpack"
288+
},
289+
"keywords": [],
290+
"author": "",
291+
"license": "ISC",
292+
"devDependencies": {
293+
"webpack": "^5.4.0",
294+
"webpack-cli": "^4.2.0"
295+
},
296+
"dependencies": {
297+
"lodash": "^4.17.20"
298+
}
299+
}
299300
```
300301

301302
Now the `npm run build` command can be used in place of the `npx` command we used earlier. Note that within `scripts` we can reference locally installed npm packages by name the same way we did with `npx`. This convention is the standard in most npm-based projects because it allows all contributors to use the same set of common scripts (each with flags like `--config` if necessary).
302303

303304
Now run the following command and see if your script alias works:
304305

305306
``` bash
306-
npm run build
307+
$ npm run build
307308

308-
...
309-
Asset Size Chunks Chunk Names
310-
main.js 70.4 KiB 0 [emitted] main
311309
...
312310

313-
WARNING in configuration
314-
The 'mode' option has not been set, webpack will fallback to 'production' for this value. Set 'mode' option to 'development' or 'production' to enable defaults for each environment.
315-
You can also set it to 'none' to disable any default behavior. Learn more: https://webpack.js.org/configuration/mode/.
311+
[webpack-cli] Compilation finished
312+
asset main.js 69.3 KiB [compared for emit] [minimized] (name: main) 1 related asset
313+
runtime modules 1000 bytes 5 modules
314+
cacheable modules 530 KiB
315+
./src/index.js 257 bytes [built] [code generated]
316+
./node_modules/lodash/lodash.js 530 KiB [built] [code generated]
317+
webpack 5.4.0 compiled successfully in 3764 ms
316318
```
317319

318-
T> Custom parameters can be passed to webpack by adding two dashes between the `npm run build` command and your parameters, e.g. `npm run build -- --colors`.
320+
T> Custom parameters can be passed to webpack by adding two dashes between the `npm run build` command and your parameters, e.g. `npm run build -- --color`.
319321

320322

321323
## Conclusion
@@ -336,7 +338,7 @@ webpack-demo
336338
|- /node_modules
337339
```
338340

339-
T> If you're using npm 5, you'll probably also see a `package-lock.json` file in your directory.
341+
T> If you're using npm 5+, you'll probably also see a `package-lock.json` file in your directory.
340342

341343
W> Do not compile untrusted code with webpack. It could lead to execution of malicious code on your computer, remote servers, or in the Web browsers of the end users of your application.
342344

0 commit comments

Comments
 (0)