Webpack-CLI Documentation #112

evenstensberg · 2017-04-14T22:08:20Z

What kind of change does this PR introduce?

Adds Documentation for the cli

Did you add tests for your changes?

N/A

If relevant, did you update the documentation?

Yes 😸

Summary

Adds documentation to the CLI.

Does this PR introduce a breaking change?

No

Other information

V1 🎉

bebraw · 2017-04-23T20:02:40Z

README.md

@@ -11,13 +11,22 @@

 # Webpack CLI

-This project intends to be the main cli package of webpack. Here we will encapsulate all the features and code related to the command line. From sending options to the compiler, to initialize and migrate from version to version.
+This project intends to be the main cli package of webpack. Here we will encapsulate all the features and code related to the command line. From sending options to the compiler, to initialize and migrate from version to version. To avoid breaking changes and making people unhappy, we are keeping the old features. While we keep the old features, we've added some other, `init`and `migrate`. 


I would rewrite like this:

Webpack CLI encapsulates all code related to CLI handling. It captures options and sends them to webpack compiler. You can also find functionality for initializing a project and migrating between versions. For the time being, it is backwards-compatible with the CLI included in webpack itself.

bebraw · 2017-04-23T20:04:13Z

README.md


-# Roadmap to the first release
+The `migrate` feature aims to ease the transition version 1, to version 2 of webpack. This feature will allow users to switch to the new version of webpack, without having to refactor themselves.


Better just to go with "eases" over "aims to ease". Same with "will". Better use "allows".

bebraw · 2017-04-23T20:04:33Z

SCAFFOLDING.md

@@ -0,0 +1,19 @@
+# Introduction
+
+Let's face it. Setting up webpack for the first time is hard. Writing advanced configurations like support for [PWA](https://developers.google.com/web/progressive-web-apps/)'s are even harder. The `init` feature is designed to support people to create their own configuration or initializing other projects people have created.


No need for "Let's face it" as that's filler.

bebraw · 2017-04-23T20:04:50Z

SCAFFOLDING.md

+
+To create an addon, you create a [`yeoman-generator`](http://yeoman.io/authoring/). In the generator, you can create all the properties webpack has, as well as custom logic on top.
+
+Before going forward, please read [How do I compose a webpack-addon?]()


Missing link.

Also fixes some text at «Scaffolding»

evenstensberg · 2017-04-27T17:59:33Z

@bebraw Mind taking a second look? Will merge this as apart of the initial documentation if it is ok. Need to get some help with the documentation part, as this isn't my best area, and I really don't have a clue about what we should include here.

addyosmani

Leaving some thoughts as I read through.

addyosmani · 2017-04-27T19:26:10Z

README.md

@@ -11,13 +11,13 @@

 # Webpack CLI

-This project intends to be the main cli package of webpack. Here we will encapsulate all the features and code related to the command line. From sending options to the compiler, to initialize and migrate from version to version. To avoid breaking changes and making people unhappy, we are keeping the old features. While we keep the old features, we've added some other, `init`and `migrate`. 
+Webpack CLI encapsulates all code related to CLI handling. It captures options and sends them to webpack compiler. You can also find functionality for initializing a project and migrating between versions. For the time being, it is backwards-compatible with the CLI included in webpack itself.


Webpack CLI encapsulates all code related to CLI handling I know you've already changed this once. I wonder if there's a terse one liner that can explain what CLI handling gives end-users in this context.

Webpack CLI interacts with your build - it offers everything webpack's current CLI does, in addition to project scaffolding and migration. or something.

Old commit, have a look at the newest

addyosmani · 2017-04-27T19:27:38Z

SCAFFOLDING.md

@@ -1,19 +1,28 @@
 # Introduction

-Let's face it. Setting up webpack for the first time is hard. Writing advanced configurations like support for [PWA](https://developers.google.com/web/progressive-web-apps/)'s are even harder. The `init` feature is designed to support people to create their own configuration or initializing other projects people have created.
+Setting up webpack for the first time is hard. Writing advanced configurations like offline support for [PWA](https://developers.google.com/web/progressive-web-apps/)'s are even harder. The `init` feature is designed to support people that want to create their own configuration or initializing other projects people create.


Writing advanced configurations for performance optimization or PWAs can be even harder?

So this was meant as emphasizing with the user :) Want this removed or rephrased I assume.

Yep! rephrased I think :)

evenstensberg

This is an old commit, but I'll take some of the comments into consideration, as some of these are kept in the updated one. Mind having another look? Thanks in forehand, tell me if I can do anything do prevent you from reading old commits, know other people have been doing the same, and it could be my fault :)

evenstensberg · 2017-04-27T19:38:20Z

SCAFFOLDING.md

@@ -1,19 +1,28 @@
 # Introduction

-Let's face it. Setting up webpack for the first time is hard. Writing advanced configurations like support for [PWA](https://developers.google.com/web/progressive-web-apps/)'s are even harder. The `init` feature is designed to support people to create their own configuration or initializing other projects people have created.
+Setting up webpack for the first time is hard. Writing advanced configurations like offline support for [PWA](https://developers.google.com/web/progressive-web-apps/)'s are even harder. The `init` feature is designed to support people that want to create their own configuration or initializing other projects people create.


So this was meant as emphasizing with the user :) Want this removed or rephrased I assume.

evenstensberg · 2017-04-27T19:38:55Z

README.md

@@ -11,13 +11,13 @@

 # Webpack CLI

-This project intends to be the main cli package of webpack. Here we will encapsulate all the features and code related to the command line. From sending options to the compiler, to initialize and migrate from version to version. To avoid breaking changes and making people unhappy, we are keeping the old features. While we keep the old features, we've added some other, `init`and `migrate`. 
+Webpack CLI encapsulates all code related to CLI handling. It captures options and sends them to webpack compiler. You can also find functionality for initializing a project and migrating between versions. For the time being, it is backwards-compatible with the CLI included in webpack itself.


Old commit, have a look at the newest

addyosmani · 2017-04-27T23:49:57Z

README.md


 **Note** The package is still in work in progress. In case you want to contribute, reach to us, so we can point you out how and when you can help us.

 ## Migration from webpack v1 to v2

-The `migrate` feature aims to ease the transition version 1, to version 2 of webpack. This feature will allow users to switch to the new version of webpack, without having to refactor themselves.
+The `migrate` feature eases the transition from version 1, to version 2 of webpack. This feature allows users to switch to the new version of webpack, without having to refactor themselves.


To help users who are unsure what version of Webpack they are using (in particular if it was autogenerated by another CLI or tool), it might be useful linking up to something (a release or docs commit?) for Webpack 1 and linking up Webpack 2 to the latest notes. Just so they can compare easily if needed vs being unsure.

addyosmani · 2017-04-27T23:55:36Z

SCAFFOLDING.md

@@ -0,0 +1,81 @@
+# Introduction
+
+Setting up webpack for the first time is hard. Writing advanced configurations like offline support for [PWA](https://developers.google.com/web/progressive-web-apps/)'s are even harder. The `init` feature is designed to support people that want to create their own configuration or initializing other projects people create.


See the suggested edits left on some of the older commits for this part.

addyosmani · 2017-04-27T23:55:55Z

SCAFFOLDING.md

+
+Setting up webpack for the first time is hard. Writing advanced configurations like offline support for [PWA](https://developers.google.com/web/progressive-web-apps/)'s are even harder. The `init` feature is designed to support people that want to create their own configuration or initializing other projects people create.
+
+Through yeoman, the `webpack --init` feature allows people to create scaffolds and generate new projects quickly. An npm dependency that scaffolds a `webpack.config.js` through `webpack-cli` is what we refer to as an **addon**.


Link up to https://yeoman.io for folks that are unaware of what it is.

addyosmani · 2017-04-27T23:57:01Z

SCAFFOLDING.md

+## Writing a good scaffold
+
+Before writing any code, you should analyze your purpose for the scaffold. Should it be generalistic? Should it be targeted for a library, such as [react](https://facebook.github.io/react/)? Furthermore, you should decide if you want to make user interactions in your `addon`, or just scaffold an boilerplate with preconfigured settings.
+


Suggested edit:

Before writing a webpack-cli scaffold, think about what you're trying to achieve. Do you want a "general" scaffold that could be used by any project or type of app? Do you want something very focused - like a scaffold that writes both your Webpack config and your framework code? It's also useful to think about the user experience for your scaffold.

webpack-cli offers an experience that is interactive and you can prompt users for questions (like, "What is your entry point?") to help customize the output accordingly.

addyosmani

LGTM

evenstensberg · 2017-04-28T22:01:30Z

Merging post #105 acceptance

addyosmani · 2017-04-30T18:44:04Z

👍

* feat: initial commit on last structure and transforms * feat: ast for entry * feat: ast for output * feat: ast for context * feat: work in progress on resolve * feat: add transform structure for all * fix: remove rx from the project * fix: return ast on no prop at resolve * feat: ast for resolve * feat: ast for devtool * feat: art for target * feat: ast for watch * feat: sat for watchOptions * fix: rename dev-tool to devtool * feat: ast for externals * feat: ast for node * feat: sat for performance * feat: ast for stats * feat: ast for other * feat: allow multiple packages in CLI command * feat: allow dynamic entry points * feat: allow promises as entry points * feat: function decl for resolve.cachePredictate * feat: allow function for performance.assetFilter * feat: allow regex and functions in external prop * feat: regexp for outputPrefix * feat: use property without strings * feat: allow regex for unsafeCache * feat: ast for module * feat: ast for plugins * feat: art for paths * feat: prettier, topScope and runtime flow Adds the runtime flow, with prettier as well as some fixes to transformations + a top scope transformation. * feat: ast for cache * feat: module regexp fix * feat: fix generator methods * chore: bump add ons dep * feat: introduce scaffold for external runs * feat: don't use jscodeshift to parse unknown values * feat: allow name conventions * feat: allow multiple config creations * feat: allow using inject for resolve and module * feat: allow merge in scaffold * fix: make build more readable * feat: add HOC to each transform * feat: find correct folder for packages * fix: example transform in generator and fix to path * Add your first test (#114) * Tests for entry.js (#115) * Add failing test * Pass the test on entry with array and update snapshots * If entry is an object * Add failing test case for externals * Fix bug with externals regexp * fix: add identifier creation and fix entry tests * Add more tests (#116) * Test watch transform * Test watch transform (Doesnt look for existing obj) * Test target transform (Doesnt look for existing obj) * Test plugins transform (Doesnt look for existing obj) * Add failing test case for node * Add test case for node * Add first instance of duplicate check and override * Extract a function * Make a util to override object params * Cleanup the ast branch transformation (#117) * refactor watch options * refactor target * refactor context * refactor devtool * refactor node * refactor plugins * refactor amd * refactor bail * Moar tests * feat: add new tests for entry & regex for validateOptions * feat: more tests for obj ref Adds more tests to object references and the context transform * fix: fix devtool property and add tests for it * add externals test and fix identifier util Adds tests to externals, some fixes to the externals transform as well as a fix to utils, where it becomes a literal despite being an identifier. * feat: add test to array with obj reference in ext * fix: fix silly mistake on devtools props Sorry Pavithra.. * tests: add tests for every transform * feat: add more utility for tests * enhancements: use abstractions & utils * utils: add regex util * chore: add JSdocs to each transform * enhancements: use more utility on transforms * enhancements: use createpushval for all transforms * enhancements: use new utility to create single properties * enhancements: add test for utility functions * fix: don't use await for promise * enhancements: send each transform object to respective transform * enhancements: remove createsingular Replaced by pushCreateProperty * enhancements: use more utility and remove boilerplate code * chore: remove fixme flag * chore: prettify ast.find * enhancements: use objKey util for entry and externals * enhancements: use utility on resolve * enhancements: fix merge & utilize module folder * enhancements: use prettier node API * fix: don't print success msg more than one time * enhancements: fix windows paths * Webpack-CLI Documentation (#112) * chore: init * chore: add section about init and migrate * chore: add migrate and scaffold link * Create SCAFFOLDING.md * Create MIGRATE.md * chore: add docs on scaffolding * chore: add initial on addons * chore: fix initial documentation Also fixes some text at «Scaffolding» * chore: revise section on good scaffold * chore: add some API docs * chore: rephrase docs * chore: syntax sugar * chore: more syntax sugar * chore: lint webpack-cli properly * chore: prepare to update webpack/bin to ours * chore: refactor against webpack/lib * remove shebang * chore: remove old rx code * enhancements: default generator and exitCode Introduces a default generator and swapped exitCode(0) with exitCode = * chore: update addons pkg and reformat extractAnswer * enhancements: better bin resolves & default generator Thanks to Sindre Sorhus & Addy Osmani for the review. Fixed some better resolves in bin folder, removed some code in default generator to better scaffold for beginners. * enhancements: use validation to force answers * enhancements: check identifiers with properties * enhancements: revise anti pattern for promise Thanks to Sindre Sørhus for this fix. Object references are now making sure our callbacks are held, and removed the return of the promise and rather used the object we want to return. * enhancements: rename write to type and split params to newline * enhancements: add better scaffold to generator * enhancements: make default generator more User Friendly * enhancements: ask if user wants to make the config at end * enhancements: make default generator better * enhancements: add styling option to generator * fix: remove sourceMap from postcss prop * enhancements: separate dev and prod build * enhancements: add contentHash & name * enhancements: prompt for better answers * fix: remove unused module * chore: final fixes before release

evenstensberg added 6 commits April 14, 2017 21:14

chore: init

ec1b84c

chore: add section about init and migrate

0e438aa

chore: add migrate and scaffold link

80f165f

Create SCAFFOLDING.md

e50e604

Create MIGRATE.md

61e3676

chore: add docs on scaffolding

6b78d84

evenstensberg added CLI Documentation v1 labels Apr 14, 2017

evenstensberg added this to the v1 milestone Apr 14, 2017

chore: add initial on addons

92f1b98

bebraw reviewed Apr 23, 2017

View reviewed changes

evenstensberg added 3 commits April 27, 2017 19:27

chore: fix initial documentation

bcbf680

Also fixes some text at «Scaffolding»

chore: revise section on good scaffold

c5e04af

chore: add some API docs

d2b7c9b

addyosmani reviewed Apr 27, 2017

View reviewed changes

evenstensberg commented Apr 27, 2017

View reviewed changes

addyosmani reviewed Apr 27, 2017

View reviewed changes

evenstensberg added 4 commits April 28, 2017 10:05

chore: rephrase docs

8719cfb

chore: syntax sugar

8684c44

chore: more syntax sugar

a5ee74c

chore: lint webpack-cli properly

b07ec53

addyosmani approved these changes Apr 28, 2017

View reviewed changes

evenstensberg changed the title ~~[WIP] Webpack-CLI Documentation~~ Webpack-CLI Documentation Apr 28, 2017

evenstensberg changed the base branch from master to feature/init-ast April 30, 2017 18:41

evenstensberg merged commit b6c0926 into feature/init-ast Apr 30, 2017

evenstensberg deleted the chore/documentation branch April 30, 2017 18:45

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Webpack-CLI Documentation #112

Webpack-CLI Documentation #112

evenstensberg commented Apr 14, 2017 •

edited

Loading

bebraw Apr 23, 2017

bebraw Apr 23, 2017

bebraw Apr 23, 2017

bebraw Apr 23, 2017

evenstensberg commented Apr 27, 2017

addyosmani left a comment

addyosmani Apr 27, 2017

evenstensberg Apr 27, 2017

addyosmani Apr 27, 2017

evenstensberg Apr 27, 2017

addyosmani Apr 27, 2017

evenstensberg left a comment

evenstensberg Apr 27, 2017

evenstensberg Apr 27, 2017

addyosmani Apr 27, 2017

addyosmani Apr 27, 2017

addyosmani Apr 27, 2017

addyosmani Apr 27, 2017

addyosmani left a comment

evenstensberg commented Apr 28, 2017

addyosmani commented Apr 30, 2017


		# Roadmap to the first release
		The `migrate` feature aims to ease the transition version 1, to version 2 of webpack. This feature will allow users to switch to the new version of webpack, without having to refactor themselves.

		@@ -0,0 +1,19 @@
		# Introduction

		Let's face it. Setting up webpack for the first time is hard. Writing advanced configurations like support for [PWA](https://developers.google.com/web/progressive-web-apps/)'s are even harder. The `init` feature is designed to support people to create their own configuration or initializing other projects people have created.


		To create an addon, you create a [`yeoman-generator`](http://yeoman.io/authoring/). In the generator, you can create all the properties webpack has, as well as custom logic on top.

		Before going forward, please read [How do I compose a webpack-addon?]()

		@@ -0,0 +1,81 @@
		# Introduction

		Setting up webpack for the first time is hard. Writing advanced configurations like offline support for [PWA](https://developers.google.com/web/progressive-web-apps/)'s are even harder. The `init` feature is designed to support people that want to create their own configuration or initializing other projects people create.


		Setting up webpack for the first time is hard. Writing advanced configurations like offline support for [PWA](https://developers.google.com/web/progressive-web-apps/)'s are even harder. The `init` feature is designed to support people that want to create their own configuration or initializing other projects people create.

		Through yeoman, the `webpack --init` feature allows people to create scaffolds and generate new projects quickly. An npm dependency that scaffolds a `webpack.config.js` through `webpack-cli` is what we refer to as an addon.

		## Writing a good scaffold

		Before writing any code, you should analyze your purpose for the scaffold. Should it be generalistic? Should it be targeted for a library, such as [react](https://facebook.github.io/react/)? Furthermore, you should decide if you want to make user interactions in your `addon`, or just scaffold an boilerplate with preconfigured settings.

Webpack-CLI Documentation #112

Webpack-CLI Documentation #112

Conversation

evenstensberg commented Apr 14, 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

evenstensberg commented Apr 27, 2017

addyosmani 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

Choose a reason for hiding this comment

evenstensberg 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

Choose a reason for hiding this comment

Choose a reason for hiding this comment

addyosmani left a comment

Choose a reason for hiding this comment

evenstensberg commented Apr 28, 2017

addyosmani commented Apr 30, 2017

evenstensberg commented Apr 14, 2017 •

edited

Loading