Skip to content
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

Jump to bottom

Webpack-CLI Documentation #112

Merged
merged 14 commits into from
Apr 30, 2017
Merged

Webpack-CLI Documentation #112

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
14 commits
Select commit Hold shift + click to select a range
ec1b84c
chore: init
evenstensberg Apr 14, 2017
0e438aa
chore: add section about init and migrate
evenstensberg Apr 14, 2017
80f165f
chore: add migrate and scaffold link
evenstensberg Apr 14, 2017
e50e604
Create SCAFFOLDING.md
evenstensberg Apr 14, 2017
61e3676
Create MIGRATE.md
evenstensberg Apr 14, 2017
6b78d84
chore: add docs on scaffolding
evenstensberg Apr 14, 2017
92f1b98
chore: add initial on addons
evenstensberg Apr 14, 2017
bcbf680
chore: fix initial documentation
evenstensberg Apr 27, 2017
c5e04af
chore: revise section on good scaffold
evenstensberg Apr 27, 2017
d2b7c9b
chore: add some API docs
evenstensberg Apr 27, 2017
8719cfb
chore: rephrase docs
evenstensberg Apr 28, 2017
8684c44
chore: syntax sugar
evenstensberg Apr 28, 2017
a5ee74c
chore: more syntax sugar
evenstensberg Apr 28, 2017
b07ec53
chore: lint webpack-cli properly
evenstensberg Apr 28, 2017
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
4 changes: 2 additions & 2 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Old commit, have a look at the newest


**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.
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.


`webpack --migrate <config>`

Expand Down
25 changes: 17 additions & 8 deletions SCAFFOLDING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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.
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yep! rephrased I think :)

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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


Through yeoman, the `webpack --init` feature allows people to create scaffolds and generate new projects quickly, or to integrate a scaffold with other tools. A dependency with an scaffold, is what we refer to as an **addon**.
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**.
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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


## 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 ask users for your scaffold such as **"What is your entry point?"**. Through yeoman, we support building up a configuration based on user interactions. You can also avoid any input from the user if you simply want to create a configuration to start working with.
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 ask users for your scaffold such as **"What is your entry point?"**, or scaffold a boilerplate.

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

## API
## webpack-addons

To build a great scaffold, you got to know the API. As we are running the scaffolding through yeoman, we support [their API](http://yeoman.io/learning/).
[`webpack-addons`](https://github.com/webpack-contrib/webpack-addons) is a utility suite for creating addons. It contains functions that could be of use for creating an addon yourself.

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.
## webpack-addons-yourpackage

Before going forward, please read [How do I compose a webpack-addon?]()
In order for `webpack-cli` to compile your package, it relies on a prefix of `webpack-addons`. The package must also be published on npm. If you are curious on how to create your very own `addon`, please read [How do I compose a webpack-addon?](https://github.com/ev1stensberg/webpack-addons-demo).

## webpack-addons
## API

To build a great scaffold, you got to know the API. As we are running the scaffolding through yeoman, we support [their API](http://yeoman.io/learning/). To create an addon, you must 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.

- `opts.env.configuration`
- `opts.env.configuration.myObj`
- `myObj.webpackOptions`
- `merge`
- `myObj.topScope`
- `myObj.configName`