diff --git a/MIGRATE.md b/MIGRATE.md new file mode 100644 index 00000000000..8b137891791 --- /dev/null +++ b/MIGRATE.md @@ -0,0 +1 @@ + diff --git a/README.md b/README.md index cfe291bcb49..16b9b078b4b 100644 --- a/README.md +++ b/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. +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. **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 -# Roadmap to the first release +The `migrate` feature eases the transition from [version 1](http://webpack.github.io/docs/) to [version 2](https://gist.github.com/sokra/27b24881210b56bbaff7). `migrate` also allows users to switch to the new version of webpack without having to extensively [refactor](https://webpack.js.org/guides/migrating/). -- Migrate to webpack-cli all the current cli options available in webpack -- Create a `webpack-cli init` command that serves to set a configuration of webpack to the user -- create a `webpack-cli migrate` command that serves to migrate an existing configuration from webpack 1 to webpack 2. +`webpack --migrate ` + +[Read more about migrating](MIGRATE.md) + +## Creating new webpack projects + +The `init` feature allows users to get started with webpack, fast. Through scaffolding, people can create their own configuration in order to faster initialize new projects for various of use cases. + +`webpack --init [webpack-addons-]` + +[Read more about scaffolding](SCAFFOLDING.md) diff --git a/SCAFFOLDING.md b/SCAFFOLDING.md new file mode 100644 index 00000000000..de17fcd641a --- /dev/null +++ b/SCAFFOLDING.md @@ -0,0 +1,83 @@ +# Introduction + +Setting up webpack for the first time is hard. Writing advanced configurations to optimize performance is 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](http://yeoman.io/), 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 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.js` 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. + +## webpack-addons + +[`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. + +## webpack-addons-yourpackage + +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 about how you can create your very own `addon`, please read [How do I compose a webpack-addon?](https://github.com/ev1stensberg/webpack-addons-demo). + +## API + +To create an `addon`, you must create a [`yeoman-generator`](http://yeoman.io/authoring/). Because of that, you can optionally extend your generator to include methods from the [Yeoman API](http://yeoman.io/learning/). Its worth noting that we support all the properties of a regular webpack configuration. In order for us to do this, there's a thing you need to remember. + +Objects are made using strings, while strings are made using double strings. This means that in order for you to create an string, you have to wrap it inside another string for us to validate it correctly. + + +### `opts.env.configuration`(Required) + +Initialized inside the constructor of your generator in order for the CLI to work. + +```js +constructor(args, opts) { + super(args, opts); + opts.env.configuration = {}; + } +``` +### `opts.env.configuration.myObj` (required) + +`myObj` is your scaffold. This is where you will add options for the CLI to transform into a configuration. You can name it anything, and you can also add more objects, that could represent a `dev.config` or `prod.config`. + +```js +constructor(args, opts) { + super(args, opts); + opts.env.configuration = { + dev: {}, + prod: {} + }; + } +``` + +### `myObj.webpackOptions` (required) + +As with a regular webpack configuration, this property behaves the same. Inside `webpackOptions` you can declare the properties you want to scaffold. You can for instance, scaffold `entry`, `output` and `context`. + +(Inside a yeoman method) +```js +this.options.env.configuration.dev.webpackOptions = { +entry: '\'app.js\'', +output: {....}, +merge: 'myConfig' +}; +``` +If you want to use `webpack-merge`, you can supply `webpackOptions` with the merge property, and the configuration you want to merge it with. + +### `myObj.topScope`(optional) + +The `topScope` property is a way for the authors to add special behaviours, like functions that could be called inside a configuration, or variable initializations and module imports. + +```js +this.options.env.configuration.dev.topScope = [ +'var webpack = require(\'webpack\');' +'var path = require(\'path\');' +]; +``` + +### `myObj.configName`(optional) + +If you want to name your `webpack.config.js` something special, you can do that. + +```js +this.options.env.configuration.dev.configName = 'base'; +```