Skip to content

docs(guides): add doctype to Get Started #1874

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 8 commits into from
Mar 5, 2018
Merged

docs(guides): add doctype to Get Started #1874

Changes from all commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
2c75064
docs(Guides): Fix error in Getting Started
rpalo Feb 26, 2018
650f69e
Updated getting-started.md
TheDutchCoder Feb 27, 2018
f3464fb
Processed first round of feedback
TheDutchCoder Feb 27, 2018
90d4d44
Added diff to package.json example
TheDutchCoder Feb 27, 2018
785a6b7
Added more info about npm, package.json.
TheDutchCoder Feb 28, 2018
b0c08ea
Minor textual edit
TheDutchCoder Feb 28, 2018
78a79cf
Typo + better wording for npm tip
TheDutchCoder Mar 1, 2018
f97ccd9
Added doctype
TheDutchCoder Mar 1, 2018
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
139 changes: 99 additions & 40 deletions src/content/guides/getting-started.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,15 +20,17 @@ Webpack is used to compile JavaScript modules. Once [installed](/guides/installa

## Basic Setup

First let's create a directory, initialize npm, and [install webpack locally](/guides/installation#local-installation):
First let's create a directory, initialize npm, [install webpack locally](/guides/installation#local-installation), and install the webpack-cli (the tool used to run webpack on the command line):

``` bash
mkdir webpack-demo && cd webpack-demo
npm init -y
npm install --save-dev webpack
npm install webpack webpack-cli --save-dev
```

Now we'll create the following directory structure and contents:
T> Throughout the Guides we will use `diff` blocks to show you what changes we're making to directories, files, and code.

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

__project__

Expand Down Expand Up @@ -58,6 +60,7 @@ document.body.appendChild(component());
__index.html__

``` html
<!doctype html>
<html>
<head>
<title>Getting Started</title>
Expand All @@ -69,7 +72,33 @@ __index.html__
</html>
```

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 declared a need for `lodash`; it just assumes that the global variable `_` exists.
We also need to adjust our `package.json` file in order to make sure we mark our package as `private`, as well as removing the `main` entry. This is to prevent an accidental publish of your code.

T> If you want to learn more about the inner workings of `package.json`, then we recommend reading the [npm documentation](https://docs.npmjs.com/files/package.json).

__package.json__
``` diff
{
"name": "webpack-demo",
"version": "1.0.0",
"description": "",
+ "private": true,
- "main": "index.js",
"scripts": {
"test": "echo \"Error: no test specified\" && exit 1"
},
"keywords": [],
"author": "",
"license": "ISC",
"devDependencies": {
"webpack": "^4.0.1",
"webpack-cli": "^2.0.9"
},
"dependencies": {}
}
```

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.

There are problems with managing JavaScript projects this way:

Expand All @@ -96,13 +125,15 @@ __project__
|- index.js
```

To bundle the `lodash` dependency with `index.js`, we'll need to install the library locally...
To bundle the `lodash` dependency with `index.js`, we'll need to install the library locally:

``` bash
npm install --save lodash
```

and then import it in our script...
T> When installing a package that will be bundled into your production bundle, you should use `npm install --save`. If you're installing a package for development purposes (e.g. a linter, testing libraries, etc.) then you should use `npm install --save-dev`. More information can be found in the [npm documentation](https://docs.npmjs.com/cli/install).

Now, lets import `lodash` in our script:

__src/index.js__

Expand All @@ -127,6 +158,7 @@ Now, since we'll be bundling our scripts, we have to update our `index.html` fil
__dist/index.html__

``` diff
<!doctype html>
<html>
<head>
<title>Getting Started</title>
Expand All @@ -144,20 +176,25 @@ In this setup, `index.js` explicitly requires `lodash` to be present, and binds
With that said, let's run `npx webpack` with our script as the [entry point](/concepts/entry-points) and `bundle.js` as the [output](/concepts/output). The `npx` command, which ships with Node 8.2 or higher, runs the webpack binary (`./node_modules/.bin/webpack`) of the webpack package we installed in the beginning:

``` bash
npx webpack src/index.js dist/bundle.js

Hash: 857f878815ce63ad5b4f
Version: webpack 3.9.1
Time: 332ms
Asset Size Chunks Chunk Names
bundle.js 544 kB 0 [emitted] [big] main
[0] ./src/index.js 222 bytes {0} [built]
npx webpack

Hash: dabab1bac2b940c1462b
Version: webpack 4.0.1
Time: 3003ms
Built at: 2018-2-26 22:42:11
Asset Size Chunks Chunk Names
bundle.js 69.6 KiB 0 [emitted] main
Entrypoint main = bundle.js
[1] (webpack)/buildin/module.js 519 bytes {0} [built]
[2] (webpack)/buildin/global.js 509 bytes {0} [built]
[3] (webpack)/buildin/module.js 517 bytes {0} [built]
[3] ./src/index.js 256 bytes {0} [built]
+ 1 hidden module

WARNING in configuration
The 'mode' option has not been set. Set 'mode' option to 'development' or 'production' to enable defaults for this environment.
```

T> Your output may vary a bit, but if the build is successful then you are good to go.
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.

Open `index.html` in your browser and, if everything went right, you should see the following text: 'Hello webpack'.

Expand All @@ -173,7 +210,7 @@ Note that webpack will not alter any code other than `import` and `export` state

## Using a Configuration

Most projects will need a more complex setup, which is why webpack supports a [configuration file](/concepts/configuration). This is much more efficient than having to type in a lot of commands in the terminal, so let's create one to replace the CLI options used above:
As of version 4, webpack doesn't require any configuration, but most projects will need a more complex setup, which is why webpack supports a [configuration file](/concepts/configuration). This is much more efficient than having to manually type in a lot of commands in the terminal, so let's create one to replace the CLI line options used above:

__project__

Expand Down Expand Up @@ -201,20 +238,25 @@ module.exports = {
};
```

Now, let's run the build again but instead using our new configuration:
Now, let's run the build again but instead using our new configuration file:

``` bash
npx webpack --config webpack.config.js

Hash: 857f878815ce63ad5b4f
Version: webpack 3.9.1
Time: 298ms
Asset Size Chunks Chunk Names
bundle.js 544 kB 0 [emitted] [big] main
[0] ./src/index.js 222 bytes {0} [built]
Hash: dabab1bac2b940c1462b
Version: webpack 4.0.1
Time: 328ms
Built at: 2018-2-26 22:47:43
Asset Size Chunks Chunk Names
bundle.js 69.6 KiB 0 [emitted] main
Entrypoint main = bundle.js
[1] (webpack)/buildin/module.js 519 bytes {0} [built]
[2] (webpack)/buildin/global.js 509 bytes {0} [built]
[3] (webpack)/buildin/module.js 517 bytes {0} [built]
[3] ./src/index.js 256 bytes {0} [built]
+ 1 hidden module

WARNING in configuration
The 'mode' option has not been set. Set 'mode' option to 'development' or 'production' to enable defaults for this environment.
```

W> Note that when calling `webpack` via its path on windows, you must use backslashes instead, e.g. `node_modules\.bin\webpack --config webpack.config.js`.
Expand All @@ -230,14 +272,26 @@ Given it's not particularly fun to run a local copy of webpack from the CLI, we

__package.json__

``` json
{
...
"scripts": {
"build": "webpack"
},
...
}
``` diff
{
"name": "webpack-demo",
"version": "1.0.0",
"description": "",
"main": "index.js",
"scripts": {
"test": "echo \"Error: no test specified\" && exit 1",
+ "build": "webpack"
},
"keywords": [],
"author": "",
"license": "ISC",
"devDependencies": {
"webpack": "^4.0.1",
"webpack-cli": "^2.0.9",
"lodash": "^4.17.5"
}
}

```

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).
Expand All @@ -247,15 +301,20 @@ Now run the following command and see if your script alias works:
``` bash
npm run build

Hash: 857f878815ce63ad5b4f
Version: webpack 3.9.1
Time: 294ms
Asset Size Chunks Chunk Names
bundle.js 544 kB 0 [emitted] [big] main
[0] ./src/index.js 222 bytes {0} [built]
Hash: dabab1bac2b940c1462b
Version: webpack 4.0.1
Time: 323ms
Built at: 2018-2-26 22:50:25
Asset Size Chunks Chunk Names
bundle.js 69.6 KiB 0 [emitted] main
Entrypoint main = bundle.js
[1] (webpack)/buildin/module.js 519 bytes {0} [built]
[2] (webpack)/buildin/global.js 509 bytes {0} [built]
[3] (webpack)/buildin/module.js 517 bytes {0} [built]
[3] ./src/index.js 256 bytes {0} [built]
+ 1 hidden module

WARNING in configuration
The 'mode' option has not been set. Set 'mode' option to 'development' or 'production' to enable defaults for this environment.
```

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`.
Expand Down