docs(guides): rewrite of development.md #1405

TheDutchCoder · 2017-07-10T23:53:51Z

This PR contains a rewrite of the Development guide.

There are a couple of issues we need to resolve before considering a merge:

Watch Mode with Chrome DevTools Workspaces has been removed as I found it oddly specific, but we might want to include it somewhere else or rework it a little bit. Thoughts @skipjack ?
webpack-dev-middleware does not work out of the box at all (throws all kinds of fs errors). I'm too green to figure this out (adding the {node: fs: 'empty' } solution doesn't work either, not the {target: 'node'} one. Help is very welcome!

All feedback appreciated!

Initial commit

skipjack · 2017-07-12T02:43:26Z

Haven't worked with webpack-dev-middleware much although maybe it was the same issue with your version of Node that we ran into on build.

Re Watch Mode with Chrome DevTools Workspaces -- I'll let you know once I read through that section. I think it may be related to #90 and could be a separate guide though I may be wrong.

skipjack

Ok I requested a lot of changes but mostly just in regards to semantics -- I'll give some thought to your questions/concerns and touch base with you after you've addressed this first pass. All in all, I think it's coming out great 👍

skipjack · 2017-07-12T02:45:31Z

content/guides/development.md

 ---

-On this page we'll explain how to get started with developing and how to choose one of three tools to develop. It is assumed you already have a webpack configuration file.
+T> This guide uses examples from the [`Webpack Guides Code Examples`](https://github.com/TheDutchCoder/webpack-guides-code-examples) repo.


Maybe hold off on mentioning this yet -- but definitely mention which guide is the prerequisite for this one if there is one.

skipjack · 2017-07-12T02:48:04Z

content/guides/development.md


+W> The tools in this guide are meant for development **only**, do not ever use them in production!


Might sound better as:

The tools in this guide are __only meant for development___, please __avoid__ using them in production!

skipjack · 2017-07-12T02:53:38Z

content/guides/development.md


-Each editor has a different way of disabling this. For the most common ones:
+When webpack creates bundles from your code, it can become difficult to track down errors and warnings in your JavaScript. For example, if you bundle three source files (`a.js`, `b.js`, and `c.js`) into one bundle (`bundle.js`) and one of the source files contains an error, you will see the error in your console coming from `bundle.js` which isn't always very helpful (you want to know which source file the error came from).


I would rephrase this as:

When webpack bundles your source code, it can become difficult to track down errors and warnings to their original location. For example, if you bundle three source files (a.js, b.js, and c.js) into one bundle (bundle.js) and one of the source files contains an error, the stack trace will simply point to bundle.js. This isn't always very helpful as you probably want to know exactly which source file the error came from.

skipjack · 2017-07-12T02:55:10Z

content/guides/development.md

-* **IntelliJ** - use search in the preferences to find "safe write" and disable it.
-* **Vim** - add `:set backupcopy=yes` in your settings.
-* **WebStorm** - uncheck `Use "safe write"` in Preferences > Appearance & Behavior > System Settings
+In order to make it easier to track down errors and warnings, JavaScript offers Source Maps, which maps your compiled code back to your original source code. So if an error originates from `b.js`, the Source Map will tell you exactly that.


/s/So if/If

skipjack · 2017-07-12T02:57:24Z

content/guides/development.md


-## Source Maps
+For this guide, let's use the `inline-source-map` option, which is good for illustrative purposes(but don't use it in production):


You're missing a space between purposes and the ( but I would also rephrase slightly:

For this guide, let's use the inline-source-map option, which is good for illustrative purposes (though not for production):

skipjack · 2017-07-12T03:25:02Z

content/guides/development.md

 ```

-After installing, you can use the middleware like this:
+Now we can run `npm run server` from the command line and we will see our browser automatically loading up a new page (usually `localhost:8080`). If you now change any of the source files and save them, the web server will automatically reload after the code has been compiled. Give it a try!


"usually localhost:8080"? Isn't it always localhost:8080?

Fair enough, it isn't in my case as I already run a dev server there and have to change the port, but it's 8080 out of the box of course. Will change! :)

Unless a port is specified, webpack-dev-server runs portfinder to find the first open port starting at 8080: https://github.com/webpack/webpack-dev-server/blob/140da4573c7d36771d2dae3e0925f66394b27522/bin/webpack-dev-server.js#L347-L362

Interesting, it would consistently fail on 8080 for me because there's my nginx proxy we use for docker.

Might be my setup though, so I took it out of the doc regardless :)

Thanks for explaining!

skipjack · 2017-07-12T03:26:47Z

content/guides/development.md


-var app = express();
-var compiler = webpack(webpackConfig);
+T> Now that your server is working, you might want to give [`Hot Module Replacement`](/guides/hot-module-replacement) a try. It's a logical next step!


I would leave off the last bit and just end the first sentence with the exclamation point, e.g.

... a try!

skipjack · 2017-07-12T03:27:11Z

content/guides/development.md



-## References
+ ## Conclusion


Extra space?

Friggin auto formatting 😄

skipjack · 2017-07-12T03:27:27Z

content/guides/development.md


-* [SurviveJS - Automatic Browser Refresh](http://survivejs.com/webpack/developing-with-webpack/automatic-browser-refresh/)
-* [webpack your Chrome DevTools Workspaces](https://medium.com/@rafaelideleon/webpack-your-chrome-devtools-workspaces-cb9cca8d50da)
+ Now that you've learned how to automatically compile your code whenever you save a file, and how to run a simple development server, you can check out the next guide that covers [`Hot Module Replacement`](/guides/hot-module-replacement).


Extra space?

You can leave out the second "how to" in this sentence and probably the "whenever you save a file bit" as well...

Now that you've learned how to automatically compile your code and run a simple development server, you can check out...

skipjack · 2017-07-12T03:31:50Z

content/guides/development.md


-Depending on what you've used in `output.publicPath` and `output.filename`, your bundle should now be available on `http://localhost:3000/bundle.js`.
+W> This section is currently not working out of the box.


Let me give this some thought. webpack-dev-middleware is what webpack-dev-server uses under the hood so it could just be mentioned in that respect but a small example probably wouldn't be bad either.

Yeah I like an example here, as people might have a need for middleware.

I'll take another stab at it later (maybe it was my node version again)

TheDutchCoder · 2017-07-12T03:39:32Z

Love all the feedback! Will update tomorrow morning!

Initial commit

…o patch-9

TheDutchCoder · 2017-07-12T13:37:44Z

Hm, something must have gone wrong in my merge.

Do you want me to do an interactive rebase for this @skipjack ?

skipjack · 2017-07-13T22:11:38Z

@TheDutchCoder don't worry about it, we'll "Squash and Merge" this sucker when it's done.

skipjack · 2017-07-14T03:08:58Z

@TheDutchCoder seeing a couple of minor markdown formatting errors from the CI process:

./content/guides/development.md: 249: MD006 Consider starting bulleted lists at the beginning of the line
./content/guides/development.md: 249: MD007 Unordered list indentation
./content/guides/development.md: 86: MD040 Fenced code blocks should have a language specified

Once those are fixed I can give this another quick review and hopefully ship it!

skipjack · 2017-07-15T14:12:45Z

Ok it looks like there's just two more things from proselint and then this should be good:

content/guides/development.md:20:346: weasel_words.very Substitute 'damn' every time you're inclined to write 'very;' your editor will delete it and the writing will be just as it should be.
content/guides/development.md:156:24: cliches.write_good 'keep an eye on' is a cliché.

The "very" should be removed but "keep an eye on" we could add an exception for. I'll do one last review now so we can get this merged soon.

skipjack

Some minor requests, aside from those this is looking really, really 🎉 .

skipjack · 2017-07-15T14:21:13Z

content/guides/development.md

-* **IntelliJ** - use search in the preferences to find "safe write" and disable it.
-* **Vim** - add `:set backupcopy=yes` in your settings.
-* **WebStorm** - uncheck `Use "safe write"` in Preferences > Appearance & Behavior > System Settings
+In order to make it easier to track down errors and warnings, JavaScript offers Source Maps, which maps your compiled code back to your original source code. If an error originates from `b.js`, the Source Map will tell you exactly that.


Maybe link to somewhere else for an intro to source maps and rephrase slightly:

In order to make it easier to track down errors and warnings, JavaScript offers [source maps](http://blog.teamtreehouse.com/introduction-source-maps), which map your compiled code back to your original source code. If an error originates from `b.js`, the mapping will direct you to that file.

I would also lowercase "Source Maps" => "source maps" everywhere (except in titles).

skipjack · 2017-07-15T14:23:29Z

content/guides/development.md

-to continue editing and saving your changes from Chrome or source files.
+ 1. webpack's Watch Mode
+ 2. webpack-dev-server
+ 3. webpack-dev-middlware


webpack-dev-middlware => webpack-dev-middleware

skipjack · 2017-07-15T14:27:07Z

content/guides/development.md


-var app = express();
-var compiler = webpack(webpackConfig);
+T> Now that your server is working, you might want to give [`Hot Module Replacement`](/guides/hot-module-replacement) a try!


Take "Hot Module Replacement" out of the backticks (``) as it's not code.

skipjack · 2017-07-15T14:29:26Z

content/guides/development.md


-Depending on what you've used in `output.publicPath` and `output.filename`, your bundle should now be available on `http://localhost:3000/bundle.js`.
+?> This section is currently not working out of the box.


Maybe update this as a call to action? e.g.

?> Familiar with `webpack-dev-middleware`? We need your help! Please submit a PR to fill in the missing instructions and example here. Make sure to keep it simple as this guide is intended for beginners.

…o patch-9

TheDutchCoder · 2017-07-15T14:37:22Z

@skipjack cool, thanks for all the help, just pushed the latest changes, so ready for a (hopefully) final check!

TheDutchCoder and others added 4 commits June 30, 2017 12:05

Rewrite of development.md

eb5f53a

Initial commit

Prelim changes

a50cc8d

First batch of changes

5092a87

fix: rewrote development.md

745695a

TheDutchCoder requested a review from skipjack July 10, 2017 23:53

Merge branch 'master' into patch-9

3f40a39

skipjack added the Guides label Jul 11, 2017

skipjack requested changes Jul 12, 2017

View reviewed changes

TheDutchCoder and others added 6 commits July 12, 2017 09:14

Rewrite of development.md

4facf70

Initial commit

Prelim changes

01df453

First batch of changes

9bd9326

fix: rewrote development.md

79ada90

Reworded things based on excellent feedback!

bce038d

Merge branch 'patch-9' of github.com:TheDutchCoder/webpack.js.org int…

e5fa599

…o patch-9

Merge branch 'master' into patch-9

c2ae76a

TheDutchCoder and others added 2 commits July 14, 2017 08:41

Fixed markdown issues

84137c7

Merge branch 'master' into patch-9

ab145b9

skipjack mentioned this pull request Jul 15, 2017

Guides - Review and Simplify #1258

Closed

skipjack requested changes Jul 15, 2017

View reviewed changes

TheDutchCoder added 2 commits July 15, 2017 10:36

Processed feedback + fixed markdown lint errors

0de3a84

Merge branch 'patch-9' of github.com:TheDutchCoder/webpack.js.org int…

7e5df33

…o patch-9

Merge branch 'master' into patch-9

b8f8563

skipjack approved these changes Jul 15, 2017

View reviewed changes

skipjack merged commit 5f05177 into webpack:master Jul 15, 2017

TheDutchCoder deleted the patch-9 branch July 15, 2017 16:07

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs(guides): rewrite of development.md #1405

docs(guides): rewrite of development.md #1405

TheDutchCoder commented Jul 10, 2017

skipjack commented Jul 12, 2017

skipjack left a comment •

edited

Loading

skipjack Jul 12, 2017

skipjack Jul 12, 2017

skipjack Jul 12, 2017

skipjack Jul 12, 2017

skipjack Jul 12, 2017

skipjack Jul 12, 2017

TheDutchCoder Jul 12, 2017

simon04 Jul 12, 2017

TheDutchCoder Jul 12, 2017

skipjack Jul 12, 2017

skipjack Jul 12, 2017

TheDutchCoder Jul 12, 2017

skipjack Jul 12, 2017

skipjack Jul 12, 2017

skipjack Jul 12, 2017

TheDutchCoder Jul 12, 2017

TheDutchCoder commented Jul 12, 2017

TheDutchCoder commented Jul 12, 2017

skipjack commented Jul 13, 2017

skipjack commented Jul 14, 2017

skipjack commented Jul 15, 2017

skipjack left a comment

skipjack Jul 15, 2017

skipjack Jul 15, 2017

skipjack Jul 15, 2017

skipjack Jul 15, 2017

TheDutchCoder commented Jul 15, 2017


		W> The tools in this guide are meant for development only, do not ever use them in production!


		Each editor has a different way of disabling this. For the most common ones:
		When webpack creates bundles from your code, it can become difficult to track down errors and warnings in your JavaScript. For example, if you bundle three source files (`a.js`, `b.js`, and `c.js`) into one bundle (`bundle.js`) and one of the source files contains an error, you will see the error in your console coming from `bundle.js` which isn't always very helpful (you want to know which source file the error came from).


		## Source Maps
		For this guide, let's use the `inline-source-map` option, which is good for illustrative purposes(but don't use it in production):


		Depending on what you've used in `output.publicPath` and `output.filename`, your bundle should now be available on `http://localhost:3000/bundle.js`.
		W> This section is currently not working out of the box.


		Depending on what you've used in `output.publicPath` and `output.filename`, your bundle should now be available on `http://localhost:3000/bundle.js`.
		?> This section is currently not working out of the box.

docs(guides): rewrite of development.md #1405

docs(guides): rewrite of development.md #1405

Conversation

TheDutchCoder commented Jul 10, 2017

skipjack commented Jul 12, 2017

skipjack left a comment • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

TheDutchCoder commented Jul 12, 2017

TheDutchCoder commented Jul 12, 2017

skipjack commented Jul 13, 2017

skipjack commented Jul 14, 2017

skipjack commented Jul 15, 2017

skipjack left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

TheDutchCoder commented Jul 15, 2017

skipjack left a comment •

edited

Loading