easy-webpack / core

An easy way to create configuration files for Webpack
MIT License
68 stars 6 forks source link

write documentation #3

Closed niieani closed 8 years ago

niieani commented 8 years ago

Draft

easy webpack's config packages treat parts of the config as complete features rather than as. This way you are offloading the steep learning curve of webpack configuration onto the mainainers of the configuration feature package. I find this approach is easier for many people as they can get results quickly without putting in hours of studying how best to configure a given feature with Webpack.

generateConfig of can take in either a function or a simple object. For simple configs an object is enough, whether you want to manually override some elements or append to certain arrays (e.g. the plugin array). The default behavior is to deep merge objects, append values to arrays and in all other cases overwrite the old values. The function approach allows for more fine grained changes like prepending arrays, or using previously generated config as input for the generated output. Last config is available as this inside the function.

I've committed a change to easy-webpack/config-env-development, if you npm update in about 5 mins you should get the new default without any changes

The benefit of having parts of the config in separate NPM modules -- we can fix bugs in people's config file without them having to do anything else than npm update. No need for blog posts with tedious migrations to new settings -- simply update the package. And when somebody wants their own, unmanaged settings, they know what and why they're doing anyway. It's like the difference between a managed webhosting and unmanaged dedicated server -- you choose what's right for the job.

if you're running a production-grade product that's using NPM packages, you should either lock your dependencies to a patch level, or use shrinkwrap to lock them altogether and upgrade by using tests to confirm your code works in the updated scenario. If you just "upgrade the hell out of it" for the sake of upgrading then it's your fault if things break.

the developers responsibility to ensure he has set correct SemVer range for the packages, just like it is the mainainers responsitility to follow SemVer in a SemVer environment.

no breaking changes will be made to config files without bumping a major version. For minor and bug fixes -- Only maintenance tasks, upgrade tasks, better defaults (e.g. different compression algorithm, a more compatible devtool - as it happened now - things of that sort).

Contributing

We use Semantic Release, which means:

┆Issue is synchronized with this Asana task

rajajhansi commented 8 years ago

@niieani, You have done a fantastic job by creating easy-webpack. Thank you so much. You don't know how frustrated I was learning Webpack and creating a working webpack.config.js because the documentation of Webpack isn't all that great and most of the articles on the internet are still talking about 1.x.

I went through the entire dependency graph of packages all the way from aurelia-skeleton\aurelia-typescript-webpack\webpack.config.js into easy-webpack/core (assign). I'd like to add a few additional aurelia packages and use SASS loader for *.scss files. I'm going to:

  1. Add additional Aurelia packages (ui toolkits) into "aurelia" array inside "coreBundles" or better yet create another property named "aureali-ui-toolkits" and add that into the "entry" array property in baseConfig.
  2. Add SASS loader for *.scss filles into "production" "development" and "test" configurations by adding:
require('@easy-webpack/config-sass')
        ({ filename: 'styles.css', allChunks: !!ELECTRON, sourceMap: false }),

Question: If my application use a mix of sass and css, since sass loader automatically loads style and css loaders as well, I can replace

require('@easy-webpack/config-css')
        ({ filename: 'styles.css', allChunks: !!ELECTRON, sourceMap: false }),

with

require('@easy-webpack/config-sass')
        ({ filename: 'styles.css', allChunks: !!ELECTRON, sourceMap: false }),

, right? Do you think I'm going in the right direction?

niieani commented 8 years ago

@rajajhansi rather than replacing CSS you should add SASS (so you can still require CSS resources like bootstrap). Also: me and @Vheissu noticed a small issue with the CSS extraction related to CSS+SASS configuration. I'll keep you posted. The docs should help when they're ready.

rajajhansi commented 8 years ago

@niieani That makes total sense. I'll add sass loader right after css loader. Please keep me posted about the CSS extraction issue. Thank you for adding the docs. I'm looking forward to reading them and providing feedback if you're interested. I'm writing a series of blog posts on "Creating a web application using ASP.NET Core 1.0, Aurelia, TypeScript and Webpack in Visual Studio Code". I'm also adding YouTube videos and source code in github to complement each blog post in the series. I finished the first 2 parts that are basic setup of ASP.NET Core 1.0 and TypeScript. I'm writing part 3 of the series, where I'm introducing Aurelia, Webpack, aurelia-typescript-webpack-skeleton, easy-webpack, showing how to build an application using the skeleton by removing the unwanted files and adding the view models specific to the tutorial application. Please check out http://opensourcedotnetter.blogspot.com/ when you have some time.

niieani commented 8 years ago

Initial docs are published: https://github.com/easy-webpack/core

rajajhansi commented 8 years ago

@niieani Awesome! You rock! I'll read through the documentation and provide feedback in the respective github repositories of easy-webpack.