1 | [![Travis CI](https://travis-ci.org/istarkov/babel-plugin-webpack-loaders.svg?branch=master)](https://travis-ci.org/istarkov/babel-plugin-webpack-loaders)
|
2 | [![Appveyor](https://ci.appveyor.com/api/projects/status/r4rctajjme24wl0q?svg=true)](https://ci.appveyor.com/project/istarkov/babel-plugin-webpack-loaders)
|
3 |
|
4 | # babel-plugin-webpack-loaders
|
5 |
|
6 | ## Important note!!!
|
7 |
|
8 | Since plugin was published, there were a lot of changes in testing software. Be sure in most(all) cases you DON'T need this plugin for testing. I highly recommend you to use [jest](https://facebook.github.io/jest/) for testing, and use [moduleNameMapper](https://facebook.github.io/jest/docs/tutorial-webpack.html) (_identity-obj-proxy, etc_) to mock CSS-Modules and other webpack loaders.
|
9 |
|
10 | ## Begin
|
11 |
|
12 | This Babel 6 plugin allows you to use webpack loaders in Babel.
|
13 | It's now easy to run universal apps on the server without additional build steps, to create libraries as usual with `babel src --out-dir lib` command, to run tests without mocking-prebuilding source code.
|
14 | It just replaces `require - import` statements with `webpack loaders` results. Take a look at this Babel [build output diff](https://github.com/istarkov/babel-plugin-webpack-loaders/commit/2a7a6d1e61ea3d052b34afd5c3abc46f075d277c#diff-4) to get the idea.
|
15 |
|
16 | For now this plugin is of alpha quality and tested on webpack loaders I use in my projects.
|
17 | These loaders are `file-loader`, `url-loader`, `css-loader`, `style-loader`, `sass-loader`, `postcss-loader`.
|
18 | The plugin supports all webpack features like loaders chaining, webpack plugins, and all loaders params. It's easy because this plugin just uses webpack.
|
19 |
|
20 | Three examples:
|
21 |
|
22 | - [runtime css-modules example](https://github.com/istarkov/babel-plugin-webpack-loaders/blob/master/examples/runExample/run.js) with simple [webpack config](https://github.com/istarkov/babel-plugin-webpack-loaders/blob/master/examples_webpack_configs/run.webpack.config.js),
|
23 | run it with `npm run example-run`
|
24 |
|
25 | - [library example](https://github.com/istarkov/babel-plugin-webpack-loaders/blob/master/examples/myCoolLibrary/myCoolLibrary.js) with [multi loaders-plugins webpack config](https://github.com/istarkov/babel-plugin-webpack-loaders/blob/master/examples_webpack_configs/lib.webpack.config.js),
|
26 | build it with `npm run example-build` and execute with `node build/myCoolLibrary/myCoolLibrary.js`, assets and code will be placed at `./build/myCoolLibrary` folder.
|
27 |
|
28 | Here is an [output diff](https://github.com/istarkov/babel-plugin-webpack-loaders/commit/2a7a6d1e61ea3d052b34afd5c3abc46f075d277c#diff-4) of this [library example](https://github.com/istarkov/babel-plugin-webpack-loaders/blob/master/examples/myCoolLibrary/myCoolLibrary.js) built without and with the plugin.
|
29 |
|
30 | - [minimal-example-standalone-repo](https://github.com/istarkov/minimal-example-for-babel-plugin-webpack-loaders)
|
31 |
|
32 | ## Warning
|
33 |
|
34 | **Do not run this plugin as part of a webpack frontend configuration. This plugin is intended only for backend compilation.**
|
35 |
|
36 |
|
37 | # How it works
|
38 |
|
39 | Take a look at this [minimal-example](https://github.com/istarkov/minimal-example-for-babel-plugin-webpack-loaders)
|
40 |
|
41 | - You need to create a [webpack config](https://github.com/istarkov/minimal-example-for-babel-plugin-webpack-loaders/blob/master/webpack.config.js)
|
42 |
|
43 | - You need to add [these lines](https://github.com/istarkov/minimal-example-for-babel-plugin-webpack-loaders/blob/master/.babelrc#L1-L16) to `.babelrc`
|
44 |
|
45 | - Now you can run [example.js](https://github.com/istarkov/minimal-example-for-babel-plugin-webpack-loaders/blob/master/example.js)
|
46 |
|
47 | ```javascript
|
48 | // example.js
|
49 | import css from './example.css';
|
50 | console.log('css-modules result:', css);
|
51 | ```
|
52 |
|
53 | with the command `BABEL_DISABLE_CACHE=1 NODE_ENV=EXAMPLE ./node_modules/.bin/babel-node ./example.js` and you'll get the following console output:
|
54 |
|
55 | ```javascript
|
56 | css-modules result: { main: 'example__main--zYOjd', item: 'example__item--W9XoN' }
|
57 | ```
|
58 |
|
59 | Here I placed [output diff](https://github.com/istarkov/babel-plugin-webpack-loaders/commit/2a7a6d1e61ea3d052b34afd5c3abc46f075d277c#diff-4)
|
60 | of this [babel library](https://github.com/istarkov/babel-plugin-webpack-loaders/blob/master/examples/myCoolLibrary/myCoolLibrary.js) build without and with the plugin.
|
61 | As you can see the plugin just replaces require with loaders results. [All loaders](https://github.com/istarkov/babel-plugin-webpack-loaders/blob/example-output/build/myCoolLibrary/assets/myCoolStyle.css#L12) and [plugins](https://github.com/istarkov/babel-plugin-webpack-loaders/blob/example-output/build/myCoolLibrary/assets/myCoolStyle.css#L4) have been applied to generated assets
|
62 |
|
63 |
|
64 | # Install
|
65 |
|
66 | ```shell
|
67 | npm install --save-dev babel-cli babel-plugin-webpack-loaders
|
68 | ```
|
69 |
|
70 | # Examples
|
71 |
|
72 | [webpack configs](https://github.com/istarkov/babel-plugin-webpack-loaders/tree/master/examples_webpack_configs),
|
73 | [examples](https://github.com/istarkov/babel-plugin-webpack-loaders/tree/master/examples),
|
74 | [.babelrc example](https://github.com/istarkov/babel-plugin-webpack-loaders/blob/master/.babelrc),
|
75 | [tests](https://github.com/istarkov/babel-plugin-webpack-loaders/tree/master/test),
|
76 | [minimal-example-repo](https://github.com/istarkov/minimal-example-for-babel-plugin-webpack-loaders)
|
77 |
|
78 | You can try out the examples by cloning this repo and running the following commands:
|
79 |
|
80 | ```shell
|
81 | npm install
|
82 | # example above
|
83 | npm run example-run
|
84 | # library example - build library with a lot of modules
|
85 | npm run example-build
|
86 | # and now you can use your library using just node
|
87 | node build/myCoolLibrary/myCoolLibrary.js
|
88 | # test sources are also good examples
|
89 | npm run test
|
90 | ```
|
91 |
|
92 | # Why
|
93 |
|
94 | The source of inspiration for this plugin was [babel-plugin-css-modules-transform](https://github.com/michalkvasnicak/babel-plugin-css-modules-transform), but it was missing some features I wanted:
|
95 |
|
96 | - I love writing CSS using Sass
|
97 | - I like webpack and its loaders (chaining, plugins, settings)
|
98 | - I wanted to open source a UI library which heavily used CSS Modules, Sass and other webpack loaders.
|
99 | The library consisted of many small modules and every module needed to be available to users independently such as `lodash/blabla/blublu`.
|
100 | With this plugin the heavy build file for the library could be replaced with just one command: `babel src --out-dir lib`.
|
101 |
|
102 | # How the plugin works internally
|
103 |
|
104 | The plugin tests all `require` paths with [test regexps](https://github.com/istarkov/babel-plugin-webpack-loaders/blob/master/src/plugin.js#L91) from the loaders in the webpack config, and then for each successful test:
|
105 |
|
106 | 1. [synchronously executes webpack](https://github.com/istarkov/babel-plugin-webpack-loaders/blob/b2a097c971f8f01b53bfe5bfbcf9e0c2fa16f62b/src/runWebPackSync.js#L16-L26)
|
107 |
|
108 | 2. [parses webpack output](https://github.com/istarkov/babel-plugin-webpack-loaders/blob/b2a097c971f8f01b53bfe5bfbcf9e0c2fa16f62b/src/plugin.js#L11) using babel-parse
|
109 |
|
110 | 3. [replaces](https://github.com/istarkov/babel-plugin-webpack-loaders/blob/b2a097c971f8f01b53bfe5bfbcf9e0c2fa16f62b/src/plugin.js#L267) the required ast with the parsed ast output
|
111 |
|
112 | # Caching issues
|
113 |
|
114 | By default Babel caches compiled files, so any changes in files processed with loaders will not be visible at subsequent builds,
|
115 | you need to run all commands with a `BABEL_DISABLE_CACHE=1` prefix.
|
116 |
|
117 | (_More information: [#T1186](https://phabricator.babeljs.io/T1186), [#36](https://github.com/istarkov/babel-plugin-webpack-loaders/issues/36)_)
|
118 |
|
119 | # Dynamic config path
|
120 |
|
121 | It's possible to interpolate env vars into the WebPack config path defined in your `.babelrc` using `lodash.template` syntax. This is mainly to achieve compatibility with [ava](https://github.com/sindresorhus/ava).
|
122 |
|
123 | The ava test runner runs each spec relative to its enclosing folder in a new process which hampers this plugins ability to use a relative path for the WebPack config. An absolute path to the WebPack config will work however, and you can set one in your `.babelrc` using an env var like this,
|
124 |
|
125 | ```json
|
126 | {
|
127 | "presets": ["es2015"],
|
128 | "env": {
|
129 | "AVA": {
|
130 | "plugins": [
|
131 | [
|
132 | "babel-plugin-webpack-loaders",
|
133 | {
|
134 | "config": "${CONFIG}",
|
135 | "verbose": false
|
136 | }
|
137 | ]
|
138 | ]
|
139 | }
|
140 | }
|
141 | }
|
142 |
|
143 | ```
|
144 |
|
145 | And then invoke ava something like this,
|
146 |
|
147 | ```sh
|
148 | CONFIG=$(pwd)/webpack.config.ava.js BABEL_DISABLE_CACHE=1 NODE_ENV=AVA ava --require babel-register src/**/*test.js
|
149 | ```
|
150 |
|
151 | (_More information: [#41](https://github.com/istarkov/babel-plugin-webpack-loaders/issues/41)_)
|
152 |
|
153 | # Thanks to
|
154 |
|
155 | [Felix Kling](https://github.com/fkling) and his [astexplorer](https://github.com/fkling/astexplorer)
|
156 |
|
157 | [James Kyle](https://github.com/thejameskyle) and his [babel-plugin-handbook](https://github.com/thejameskyle/babel-plugin-handbook)
|
158 |
|
159 | [Michal Kvasničák](https://github.com/michalkvasnicak) and his [babel-plugin-css-modules-transform](https://github.com/michalkvasnicak/babel-plugin-css-modules-transform)
|