Overhaul readme and add guides [ci skip] #372

gauravtiwari · 2017-05-12T16:28:48Z

Started working on overhauling README plus adding some guides related to advanced usage. Would be nice if everyone can chip in topics they would like to see in the README.

//cc

@Davidzhu001 @bkuhlmann @ytbryan @p0wl @renchap @RavenXce @davetron5000 @kuroda

Davidzhu001 · 2017-05-12T16:42:15Z

@gauravtiwari You mean develop docs?
I am in, but my language might not be good. lol

ytbryan · 2017-05-12T16:53:10Z

README.md

+# For Rails 5.1+
+rails new webpacker-example-app --webpack=react
+rails new webpacker-example-app --webpack=angular
+rails new webpacker-example-app --webpack=vue


./bin/rails new webpacker-app --webpack=elm?

Edited.

Should we use bin/rails everywhere for consistency?

ytbryan · 2017-05-12T16:56:18Z

README.md

+- [Ready for Vue](#ready-for-vue)
+- [Ready for Elm](#ready-for-elm)
+- [Troubleshooting](#troubleshooting)
+- [Wishlist](#wishlist)


WIshlist? Do you think this should be replaced with "contribution" or simply be removed?

Yeah, will nix this 👍

Thanks for the reply @gauravtiwari My reasoning is that we should encourage folks to contribute.

i think they can always send a pull request for any "wishlist" feature.

yep, sounds like good idea 👍

davetron5000 · 2017-05-12T20:41:36Z

README.md

+We recommend using `webpack-dev-server` during development for better experience, however if you don't want that you can run `webpack` binstub in watch mode.
+
+```bash
+./bin/webpack --watch --progress


Does this work without re-configuring the default dev server config? I don't know how --watch works enough to say, but I think by default, Rails expects assets to be available via :8080 in development

Yepp, but you can disable it from development.server.yml. Probably need to rephrase this a bit 👍

I think it's worth noting in the README here that in order for your JS to load in feature specs without having webpack-dev-server running you need to manually set the Capybara puma port to something and then set that same port in the test block of development.server.yml

davetron5000 · 2017-05-12T20:43:01Z

README.md

+
+### Babel
+
+Webpacker ships with [babel](https://babeljs.io/) - a JavaScript compiler so, you can use next generation JavaScript, today. Webpacker installer by default sets up a


Minor language nit:

Webpacker installer by default sets up a standard .babelrc

might be better as

The Webpacker generator sets up a default standard .babelrc

davetron5000 · 2017-05-12T20:43:37Z

README.md

+
+### Hot module replacement
+
+Webpacker out-of-the-box doesn't shipt with HMR just yet. You will need to install additional plugins for Webpack if you want HMR.


Typo: s/shipt/ship

davetron5000 · 2017-05-12T20:45:22Z

README.md

+- [Getting asset path](#getting-asset-path)
+- [Deployment](#deployment)
+- [Linking to sprockets assets](#linking-to-sprockets-assets)
+- [Ready for React](#ready-for-react)


This TOC is awesome and helps navigate this big file! 💯

Now that ELM is in here, should we add a second level? e.g.

## Ready for JavaScript Frameworks «some intro» ### Angular w/ TypeScript «existing content» ### Elm «existing content» ### React «existing content» ### Vue «existing content»

I second the above. It would be nice to add the top-level JavaScript Frameworks section.

💡 BTW, if you want the Ruby equivalent of DocToc, you might want to check out Tocer. I use it for all my projects (both for private and public repos). The nice thing about Tocer is that you can add it as a gem dependency to the project and wire it up a check for README changes prior to deploy (or even part of the build process).

Yep, lets do that 👍

@gauravtiwari ok, I opened a PR for this since I figured it would be easier to review that way. It will create a slight conflict with this PR but the diff shouldn't be too bad.

@gauravtiwari I apologize for the noise but I'm afraid the Tocer gem won't work on this project due to Webpacker needing to support older versions of Ruby. I had forgotten about that. You'll have to stick with DocToc, I guess.

zinkkrysty · 2017-05-12T21:29:17Z

README.md

 ```

-*Note:* Behind the scenes, webpacker will use same `entry` directory name inside `output`
-directory to emit bundles. For ex, `public/packs`
+Please note that you always want to change the source directory.


I'm not sure this is a typo or you mean something I do not quite get. If I always want to change the source directory then what purpose does a default serve?

Lets rephrase this then 👍

javan · 2017-05-20T13:51:14Z

README.md

+already set in the configuration file.
+
+```bash
+./bin/webpack-dev-server --host 0.0.0.0


I didn't realize we allowed/encouraged passing options like --host and probably broke it in 2a94cdf because it constructs ASSET_HOST using development.server.yml exclusively. bin/webpack-dev-server will need updating.

javan · 2017-05-20T13:52:51Z

README.md

 output: public
-config: config/webpack
-node_modules: node_modules


This paths.yml example should be updated to reflect the changes in #397

javan · 2017-05-20T13:53:47Z

README.md

+however `entry` will always be a single directory like `packs` or `modules`.
+
+Behind the scenes, webpacker will use same `entry` directory name inside `output`
+directory to emit bundles. For ex, `public/packs` or `public/modules`


Ditto re: changes in #397

Yepp fixed it 👍 Will make a PR soon

gauravtiwari · 2017-05-23T16:44:39Z

Feel free to leave any comments 👍 Gonna do a few more updates later this evening

More updates to readme Update TOC Separate out integrations Regenerate TOC Cleanup Generate TOC Add typescript and passing down data from view doc Move to how-tos Minor updates Fix typos Nitpicking Udpate TOC Fix typos Fix extension

javan · 2017-05-23T22:51:00Z

README.md


 ## Binstubs

 Webpacker ships with two binstubs: `./bin/webpack` and `./bin/webpack-dev-server`.
-They're thin wrappers around the standard webpack.js executable, just to ensure that the right configuration file is loaded depending on your environment.
+They're thin wrappers around the standard `webpack.js` and `webpack-dev-server.js`


They're not really wrappers around .js files. They wrap each npm module's bin/ script, e.g. node_modules/.bin/webpack.

javan · 2017-05-23T22:52:46Z

README.md

+```
+
+
+### Webpack watcher


Doesn't feel right to call this "Webpack watcher". I'd just document the existence of bin/webpack and that you can pass options like --watch.

javan · 2017-05-23T22:58:45Z

README.md

+### CDN
+
+Webpacker out-of-the-box provides CDN support using `ASSET_HOST` environment variable
+set within your Rails app. You don't need to do anything extra, it just works. Voila!


You don't have to set or know about ASSET_HOST. It's just what our bin/ scripts use internally. Webpacker uses your app's config.action_controller.asset_host. http://guides.rubyonrails.org/asset_pipeline.html#cdns or http://guides.rubyonrails.org/configuring.html#rails-general-configuration

dhh · 2017-05-24T10:28:04Z

What do these changes have to do with the docs? Seems like a bunch of stuff for babelrc?

gauravtiwari · 2017-05-24T11:25:18Z

Basically, a few small things we missed earlier so added it for more polished release. Babel changes are to support some latest ES6 features out of the box.

gauravtiwari · 2017-05-24T11:25:57Z

Could have done it in separate PR but were very small so consolidated in this one :)

dhh · 2017-05-24T11:41:50Z

Yeah, in general, I think it's better if we keep the PRs single purpose. They serve better as history and documentation. Let's split them. Also, I don't actually see any new readme or guide material in this PR? Just a bunch of spacing changes?

…

On Wed, May 24, 2017 at 1:25 PM, Gaurav Tiwari ***@***.***> wrote: Could have done it in separate PR but were very small so consolidated in this one :) — You are receiving this because you commented. Reply to this email directly, view it on GitHub <#372 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AAAKtchv6ldbFwTD-trUm3yfWf3fEKScks5r9BPHgaJpZM4NZgfn> .

gauravtiwari · 2017-05-24T12:26:15Z

Updated the PR and made a new one for other changes - #409 (README contains changes for #409, need to merge them together)

More updates Add css next Minor typos Fix typos Fix typos Remove babelrc and postcss exist check Update changelog Fix typo Ignore vendor Remove declaration Fix typo Fix typo Add more things to doc Remove other changes Remove other changes Remove other changes Nitpicking Fix loader

tonywok · 2018-02-26T13:38:12Z

README.md

+If you are using vim or emacs and want to ignore certain files you can add `ignore-loader`:
+
+```
+yard add ignore-loader


I think you mean yarn :)

ytbryan reviewed May 12, 2017

View reviewed changes

davetron5000 reviewed May 12, 2017

View reviewed changes

zinkkrysty reviewed May 12, 2017

View reviewed changes

a3ammar mentioned this pull request May 14, 2017

add erb extensions to paths.yml? #262

Closed

aguynamedben mentioned this pull request May 18, 2017

In README, better highlight how to add Webpacker to an existing app #399

Closed

javan reviewed May 20, 2017

View reviewed changes

gauravtiwari mentioned this pull request May 21, 2017

Consolidate .yml files into webpacker.yml #403

Merged

gauravtiwari added 3 commits May 22, 2017 19:13

Start updating readme

e847cc1

Updates

1184bdc

More updates to README

a3906bb

gauravtiwari changed the title ~~[WIP] Overhaul readme and add guides~~ Overhaul readme and add guides [ci skip] May 23, 2017

gauravtiwari added 4 commits May 23, 2017 22:15

Add sourcemap support

08058ce

More updates to readme Update TOC Separate out integrations Regenerate TOC Cleanup Generate TOC Add typescript and passing down data from view doc Move to how-tos Minor updates Fix typos Nitpicking Udpate TOC Fix typos Fix extension

Minor language fix

51ee120

Update source entry

0d263e8

Add html template doc for angular

6496705

javan reviewed May 23, 2017

View reviewed changes

dhh merged commit 90749dd into rails:master May 24, 2017

gauravtiwari deleted the overhaul-readme branch May 24, 2017 14:12

tomprats mentioned this pull request Jun 1, 2017

Support for Object Rest/Spread Properties #457

Closed

unikitty37 mentioned this pull request Jul 11, 2017

Many links to README now broken #561

Closed

tonywok reviewed Feb 26, 2018

View reviewed changes


		### Babel

		Webpacker ships with [babel](https://babeljs.io/) - a JavaScript compiler so, you can use next generation JavaScript, today. Webpacker installer by default sets up a


		### Hot module replacement

		Webpacker out-of-the-box doesn't shipt with HMR just yet. You will need to install additional plugins for Webpack if you want HMR.

Overhaul readme and add guides [ci skip] #372

Overhaul readme and add guides [ci skip] #372

Conversation

gauravtiwari commented May 12, 2017

Davidzhu001 commented May 12, 2017

ytbryan May 12, 2017 • 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

zacharyw May 21, 2017 • 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

gauravtiwari commented May 23, 2017

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

dhh commented May 24, 2017

gauravtiwari commented May 24, 2017

gauravtiwari commented May 24, 2017

dhh commented May 24, 2017 via email

gauravtiwari commented May 24, 2017 • edited Loading

Choose a reason for hiding this comment

ytbryan May 12, 2017 •

edited

Loading

zacharyw May 21, 2017 •

edited

Loading

gauravtiwari commented May 24, 2017 •

edited

Loading