Custom boostraprc location (#114)

* make the .bootstraprc location customizable
* Fixes handling of default configuration when there's neither a custom
  bootstraprc location nor a user supplied .bootstraprc.
* More logging
* Configured the css modules example to use either a fixed file or a
  specified location.
* Made the shorter script names be the ones that use file location as
  that is better for testing the examples, as changes to the
  .bootstraprc file get overwritten.

CHANGELOG.md

@@ -4,17 +4,22 @@ All notable changes to this project will be documented in this file. Items under
 Contributors: please follow the recommendations outlined at [keepachangelog.com](http://keepachangelog.com/). Please use the existing headings and styling as a guide, and add a link for the version diff at the bottom of the file. Also, please update the `Unreleased` link to compare to the latest release version.
 ## [Unreleased]
 
+## [1.1.0] - 2016-08-01
+##### Added
+- Support for custom .bootstraprc location. [#114](https://github.com/shakacode/bootstrap-loader/pull/114) by [justin808](https://github.com/justin808) and [pherris](https://github.com/pherris).
+
 ## [1.0.10] - 2016-03-17
 ##### Fixed
-- fixes polyfill require for node < v4.0.0. [#72](https://github.com/shakacode/bootstrap-loader/pull/72) by [mdgraser](https://github.com/mdgraser).
+- Fixes polyfill require for node < v4.0.0. [#72](https://github.com/shakacode/bootstrap-loader/pull/72) by [mdgraser](https://github.com/mdgraser).
 
 ## [1.0.9] - 2016-02-28
 ##### Fixed
 - Updated to support Bootstrap 4, Alpha 2, including examples. See [#56](https://github.com/shakacode/bootstrap-loader/pull/56) by [justin808](https://github.com/justin808).
 
 ## [1.0.8]
 
-[Unreleased]: https://github.com/shakacode/bootstrap-loader/compare/1.0.10...master
+[Unreleased]: https://github.com/shakacode/bootstrap-loader/compare/1.1.0...master
+[1.1.0]: https://github.com/shakacode/bootstrap-loader/compare/1.0.10...1.1.0
 [1.0.10]: https://github.com/shakacode/bootstrap-loader/compare/1.0.9...1.0.10
 [1.0.9]: https://github.com/shakacode/bootstrap-loader/compare/1.0.8...1.0.9
 [1.0.8]: https://github.com/shakacode/bootstrap-loader/compare/1.0.7...1.0.8

CONTRIBUTING.md

@@ -17,14 +17,68 @@ To start development simply run:
 npm start
 ```
 
-It will run linters, clear directory with previous build, create new build and run watchers to re-build on every change. Sadly, but we can't use `npm link` feature in development process here because this command symlinks package folder, what makes impossible to resolve `bootstrap` packages in project's `npm_modules` folder. Instead of this just install `bootstrap-loader` locally:
+It will run linters, clear directory with previous build, create new build and run watchers to re-build on every change.
+
+
+### Using the Local Library
+#### npm link
+We can use the `npm link` feature in our development process if we reference full paths to our loader in webpack's config: `bootstrap-loader/lib/bootstrap.loader?extractStyles&configFilePath=${__dirname}/.bootstraprc!bootstrap-loader/no-op.js`. In order for this library to find the expected `bootstrap` version, you must also `npm link` the expected `bootstrap` and `extract-text-webpack-plugin` (assuming you are passing `extractStyles` to `boostrap.loader` e.g. `...
+  bootstrap.loader?extractStyles&...`) versions from your project's `node_modules` directory to your clone of this library.
+
+#### Installing locally
+More often than not, `npm link` will not work. Maybe you did not set the sibling directories of `bootstrap` and `extract-text-webpack plugin`? 
+
+If `npm link` doesn't work for you, just install `bootstrap-loader` locally:
 
 ```
 cd my-test-project
 npm install --save-dev ../path/to/local/bootstrap-loader
 ```
 
-It is a pity, but you have to re-install `bootstrap-lodaer` on every change.
+Note that if you install `bootstrap-loader` locally, you have to re-install it on every change. Yes. Very inconvenient!
+
+#### Debug Output
+When doing development or debugging, you probably want DEBUG output on.
+
+Either set an ENV value: `export DEBUG=TRUE` or set debug in the config file. To turn off debugging, etiher `unset DEBUG` or change the debug value in the config file.
+
+#### Testing changes to the repo
+Make sure to write new tests for your changes. Currently the test suite is light, please help us flesh it out. Run the tests with `npm test`.
+
+You will also want to run the example implementations to ensure they work as expected with your changes. To test:
+
+Run the package.json scripts in both the `examples/basic` and `examples/css-modules` directories, like this. Be sure to check the browser and look for error messages.
+
+
+```
+cd examples/basic
+npm run install-local
+
+npm run bs3
+# Try out in the browser at localhost:4000, and maybe make changes to the local config .bootstraprc-3-example
+
+npm run bs4
+# Try out in the browser at localhost:4000, and maybe make changes to the local config .bootstraprc-4-example
+
+npm run bs3:prod
+
+npm run bs4:prod
+
+cd examples/css-modules
+npm run install-local
+
+npm run bs3
+# Try out in the browser at localhost:4000, and maybe make changes to the local config .bootstraprc-3-example
+
+npm run bs4
+# Try out in the browser at localhost:4000, and maybe make changes to the local config .bootstraprc-4-example
+
+npm run bs3:prod
+
+npm run bs4:prod
+```
+
+Ensure your changes don't break any of the examples before you publish your PR.
 
 ### Build
 To create a build run:
@@ -42,7 +96,11 @@ To lint your code run:
 npm run lint
 ```
 
-Shame on us, but we don't have any tests here yet. We will be happy, if you can give us a hand with it.
+To test your code run:
+
+```
+npm run test
+```
 
 ## How loader works
 There are 2 entry points: `./loader.js` & `./extractStyles.js`. These are the dummy loaders, which apply real loader to dummy `no-op.js` file. The source of the real loader is located in `./src/bootstrap.loader.js`. Before exploring things in it, check out `./src/bootstrap.config.js` to figure out how we handle default / user config files & gather options for loader.

README.md

@@ -16,9 +16,9 @@ That being said, Bootstrap 4 probably works just fine!
 
 ## NEWS
 
+2016-08-01: Released 1.1.0. Supports custom bootstraprc location.
 2016-02-28: Released 1.0.9. Updated to support Bootstrap 4, alpha 2!
 
-
 ## Installation
 Get it via npm:
 
@@ -35,6 +35,8 @@ npm install bootstrap-sass
 # or Bootstrap 4
 npm install bootstrap@v4.0.0-alpha.2
 
+# Note, alpha.3 is broken
+
 # Node SASS & other loaders needed to handle styles
 npm install css-loader node-sass resolve-url-loader sass-loader style-loader url-loader
 ```
@@ -59,7 +61,11 @@ Or add `bootstrap-loader` as [a module in an entry point](https://webpack.github
 entry: [ 'bootstrap-loader', './app' ]
 ```
 
-Config is optional. It can be placed in root dir with name `.bootstraprc`. You can write it in `YAML` or `JSON` formats. Take a look at the default config files for [Bootstrap 3](.bootstraprc-3-default) and [Bootstrap 4](.bootstraprc-4-default). Note, we recommend using a configuration or else you might pick up unwanted upgrades, such as when we make Bootstrap 4 the default. Config options don't fall back on the defaults once a config file is present. Be sure not to delete config options. To start with a custom config, copy over a default config file as a starting point.
+Config is optional. If used, by default it should be placed in your project's root dir with name `.bootstraprc`. You can write it in `YAML` or `JSON` formats. Take a look at the default config files for [Bootstrap 3](.bootstraprc-3-default) and [Bootstrap 4](.bootstraprc-4-default). Note, we recommend using a configuration or else you might pick up unwanted upgrades, such as when we make Bootstrap 4 the default. Config options don't fall back on the defaults once a config file is present. Be sure not to delete config options. To start with a custom config, copy over a default config file as a starting point.
+
+If the default location doesn't work for you (e.g. you want to create multiple bootstrap configs for branding variations or you symlink your npm_modules directory), you may pass the **absolute path** of the `.bootstraprc` file to the loader in your webpack config, e.g. `bootstrap-loader/lib/bootstrap.loader?extractStyles&configFilePath=${__dirname}/.bootstraprc!bootstrap-loader/no-op.js`.
+
+Note that :`__dirname` is a [global variable](https://nodejs.org/docs/latest/api/globals.html#globals_dirname) that Node sets for us. It is "the name of the directory that the currently executing script resides in."
 
 ```yaml
 ---
@@ -105,6 +111,7 @@ If no config provided, default one for Bootstrap 3 will be used.
 Check out example apps in [`examples/`](examples) folder:
 
 * Basic usage: [examples/basic](examples/basic)
+ * See the `npm run bs4:customlocation` tasks for examples on how to pass your .bootstraprc config.
 * With CSS Modules: [examples/css-modules](examples/css-modules) (This example shows off hot reloading with Babel 6 as well!)
 
 ## Common Options for Bootstrap 3 and 4
@@ -368,8 +375,6 @@ module: {
 ```
 
 ## Contributing
-This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](CODE_OF_CONDUCT.md).
-
 See [Contributing](CONTRIBUTING.md) to get started.
 
 ## License

examples/basic/.gitignore

@@ -216,3 +216,6 @@ $RECYCLE.BIN/
 
 # Windows shortcuts
 *.lnk
+
+# the npm run ... commands can create this file but we don't want it checked in
+/.bootstraprc

examples/basic/package.json

@@ -9,14 +9,22 @@
   "scripts": {
     "start": "nodemon --watch app/markup --ext html server.dev.js",
     "clean": "rm -rf public/",
+    "lint": "eslint --ext .js,.jsx .",
+    "cleanrc": "rm .bootstraprc || echo 'no .bootstraprc file to delete'",
     "build": "npm run clean && webpack --config webpack.prod.config.js",
-    "prod": "npm run build && nodemon --watch app/markup --ext html server.prod.js",
-    "bs3": "rm .bootstraprc && cp .bootstraprc-3-example .bootstraprc",
-    "bs4": "rm .bootstraprc && cp .bootstraprc-4-example .bootstraprc",
-    "bs3:dev": "npm run bs3 && npm start",
-    "bs4:dev": "npm run bs4 && npm start",
-    "bs3:prod": "npm run bs3 && npm run prod",
-    "bs4:prod": "npm run bs4 && npm run prod"
+    "prod": "nodemon --watch app/markup --ext html server.prod.js",
+    "bs:no-config": "npm run cleanrc && npm start",
+    "bs3": "npm run cleanrc && nodemon --watch app/markup --ext html server.dev.js --bootstraprc-location=.bootstraprc-3-example",
+    "bs4": "npm run cleanrc && nodemon --watch app/markup --ext html server.dev.js --bootstraprc-location=.bootstraprc-4-example",
+    "bs3:prod": "npm run cleanrc && npm run build -- --bootstraprc-location=.bootstraprc-3-example && npm run prod",
+    "bs4:prod": "npm run cleanrc && npm run build -- --bootstraprc-location=.bootstraprc-4-example && npm run prod",
+    "bs3:default:setup": "cp -f .bootstraprc-3-example .bootstraprc",
+    "bs4:default:setup": "cp -f .bootstraprc-4-example .bootstraprc",
+    "bs3:default:dev": "npm run bs3:default:setup && npm start",
+    "bs4:default:dev": "npm run bs4:default:setup && npm start",
+    "bs3:default:prod": "npm run bs3:default:setup && npm run build && npm run prod",
+    "bs4:default:prod": "npm run bs4:default:setup && npm run build && npm run prod",
+    "install-local": "npm install --save-dev ../.."
   },
   "repository": {
     "type": "git",
@@ -46,7 +54,7 @@
     "babel-loader": "^6.1.0",
     "babel-preset-es2015": "^6.1.18",
     "body-parser": "^1.14.1",
-    "bootstrap-loader": "^1.0.9",
+    "bootstrap-loader": "*",
     "css-loader": "^0.22.0",
     "eslint": "^1.9.0",
     "eslint-config-airbnb": "^1.0.0",
@@ -55,7 +63,7 @@
     "font-awesome-loader": "^1.0.0",
     "imports-loader": "^0.6.5",
     "node-sass": "^3.4.2",
-    "nodemon": "^1.8.1",
+    "nodemon": "^1.9.2",
     "postcss-loader": "^0.8.1",
     "resolve-url-loader": "^1.4.3",
     "sass-loader": "^3.1.1",

examples/basic/webpack.bootstrap.config.js

@@ -0,0 +1,48 @@
+'use strict';
+const fs = require('fs');
+
+function getBootstraprcCustomLocation() {
+  const matchedArgument = process.argv.find(val => val.includes('--bootstraprc-location'));
+  return matchedArgument && matchedArgument.split('=')[1];
+}
+
+const bootstraprcCustomLocation = getBootstraprcCustomLocation();
+
+let defaultBootstraprcFileExists;
+
+try {
+  fs.statSync('./.bootstraprc');
+  defaultBootstraprcFileExists = true;
+} catch (e) {
+  defaultBootstraprcFileExists = false;
+}
+
+if (!bootstraprcCustomLocation && !defaultBootstraprcFileExists) {
+  /* eslint no-console: 0 */
+  console.log('You did not specify a \'bootstraprc-location\' arg or a ./.boostraprc file in the root.');
+  console.log('Using the bootstrap-loader default configuration.');
+}
+
+// DEV and PROD have slightly different configurations
+let bootstrapDevEntryPoint;
+if (bootstraprcCustomLocation) {
+ bootstrapDevEntryPoint = 'bootstrap-loader/lib/bootstrap.loader?' +
+    `configFilePath=${__dirname}/${bootstraprcCustomLocation}` +
+    '!bootstrap-loader/no-op.js';
+} else {
+  bootstrapDevEntryPoint = 'bootstrap-loader';
+}
+
+let bootstrapProdEntryPoint;
+if (bootstraprcCustomLocation) {
+ bootstrapProdEntryPoint = 'bootstrap-loader/lib/bootstrap.loader?extractStyles' +
+   `&configFilePath=${__dirname}/${bootstraprcCustomLocation}` +
+   '!bootstrap-loader/no-op.js';
+} else {
+  bootstrapProdEntryPoint = 'bootstrap-loader/extractStyles';
+}
+
+module.exports = {
+  dev: bootstrapDevEntryPoint,
+  prod: bootstrapProdEntryPoint,
+};