Aloha from Justin Gordon and the ShakaCode Team! We need your help. Venture capital funding has slowed and, for the first time, my ShakaCode team is actively looking for our next project. If you like React on Rails, please consider contacting me if we could potentially help you in any way. I'm offering a free half hour project consultation, on anything from React on Rails to any aspect of web application development, including both consumer and enterprise products. You can read more about my background here. Whether you have a new project, or need help on an existing project, please email me directly at [email protected]. And thanks in advance for any referrals! Your support keeps this project going.
bootstrap-sass-loader
DEPRECATED
We're moving to a new project name and slightly different file format.
New Locations
The new npm libs and corresponding github repos are:
New Features
- Supports Bootstrap v3 and v4
- Easier to remove jQuery
- Supports CSS Modules
This new system is currently used by the live demo of reactrails.com. You can find the source code here: shakacode/react-webpack-rails-tutorial.
That being said, the current version will probably keep working, so there's no urgency to upgrade.
Upgrade Instructions
- Change your dependency for bootstrap as shown here. Basically, you will want to configure
bootstrap-loader
as an entry point. Or you might configurebootstrap-loader/extractStyles
as an entry point, as shown here. Note, you no longer specify the name of your bootstrap customization file. - Follow the instructions here for configuring the npm library for Bootstrap.
- If you're using the bootstrap jQuery plugins, configure it like this.
- If you have no customization file, then you're done.
- Otherwise, rename your customization file to
.bootstraprc
. See sample file .bootstraprc-3-default for how to migrate your existingbootstrap-sass-config
file.
bootstrap-sass-loader (please upgrade to bootstrap-loader)
Bootstrap configuration and loading package for webpack, using the npm packages bootstrap-sass
and sass-loader
.
Install from bootstrap-sass-loader on npm.
If you're looking for the less version, see bootstrap-webpack. This project is based on that version for less, with some minor differences, the main one being how the configuration file specifies two sass files for customization.
In a nutshell:
- You've got the sass-loader to process Sass files to CSS.
- The npm bootstrap-sass package places the bootstrap files in
/node_modules/bootstrap-sass/assets
. - You could simply create your own sass file to pick up bootstrap from this location, and you could require the js files here for the Bootstrap JavaScript code. See the sass-loader for instructions on configuring the directories.
- Or you could use this loader and load a js file that configures Bootstrap.
You can find an example of using this:
shakacode/bootstrap-sass-loader-example
Note, bootstrap-sass
must be installed locally inside of ../node_modules
or a parent directories node_modules
directory relative to the loaded config file.
Bootstrap Version
The version of sass-bootstrap used is listed in peerDependencies, so you should be able to use whichever version you like.
Simply specify that version of bootstrap-sass
in your package.json
, like this:
"bootstrap-sass": "~3.3.1"
Usage
1.a Complete Bootstrap
To use the complete bootstrap package including styles and scripts with the default settings:
require("bootstrap-sass-loader");
The disadvantage to using this setup is that you can't:
- Customize the bootstrap variables: Bootstrap Customization
- You can't use the bootstrap variables for your own sass stylesheets.
1.b Customized Bootstrap
- Copy the file
bootstrap-sass.config.js
to your project. You will specify the file path in therequire
statement. - Open that file to customize the location of a file for any Bootstrap variable overrides (
preBootstrapCustomizations
andbootstrapCustomizations
, and your main Sass file that can depend on Bootstrap variables, plus your customizations. Any of these 3 files are optional. You may also remove any Sass or Js modules that you don't need.
Next, you should specify this as an entry point:
module.exports = {
entry: [
"bootstrap-sass!./path/to/bootstrap-sass.config.js"
]
Or a dependency within a file, like you'd specify other webpack dependencies:
require("bootstrap-sass!./path/to/bootstrap-sass.config.js");
bootstrap-sass.config.js
Here's a sample configuration file. The file included in the bootstrap-sass-loader git repo
has many more options. The two customization files, bootstrapCustomizations
and mainSass
are optional.
module.exports = {
bootstrapCustomizations: "./bootstrap-customizations.scss",
mainSass: "./main.scss", // path to your main SASS file (optional)
verbose: true, // print out your custom files used
debug: false, // print out the full generated scss file
styleLoader: "style-loader!css-loader!sass-loader", // see example for the ExtractTextPlugin
scripts: {
// add every bootstrap script you need
'transition': true
},
styles: {
// add every bootstrap style you need
"mixins": true,
"normalize": true,
"print": true,
"scaffolding": true,
"type": true,
}
};
Font Configuration
Bootstrap use some fonts. You need to configure the correct loaders in your webpack.config.js
.
Take a look at example https://github.com/shakacode/react-webpack-rails-tutorial which uses custom fonts with the bootstrap-sass-loader. You'll need to create define a font-face like this:
@font-face {
font-family: 'OpenSans-Light';
src: url('assets/fonts/OpenSans-Light.ttf') format('truetype');
}
Example Loaders Configuration:
module.exports = {
module: {
loaders: [
// **IMPORTANT** This is needed so that each bootstrap js file required by
// bootstrap-webpack has access to the jQuery object
{ test: /bootstrap\/js\//, loader: 'imports?jQuery=jquery' },
// Needed for the css-loader when [bootstrap-webpack](https://github.com/bline/bootstrap-webpack)
// loads bootstrap's css.
{ test: /\.woff(\?v=\d+\.\d+\.\d+)?$/, loader: "url?limit=10000&mimetype=application/font-woff" },
{ test: /\.woff2(\?v=\d+\.\d+\.\d+)?$/, loader: "url?limit=10000&mimetype=application/font-woff" },
{ test: /\.ttf(\?v=\d+\.\d+\.\d+)?$/, loader: "url?limit=10000&mimetype=application/octet-stream" },
{ test: /\.eot(\?v=\d+\.\d+\.\d+)?$/, loader: "file" },
{ test: /\.svg(\?v=\d+\.\d+\.\d+)?$/, loader: "url?limit=10000&mimetype=image/svg+xml" }
]
}
};
extract-text-plugin Notes
- If you don't run webpack like this, you might get a very obscure error:
PATH=$(npm bin):$PATH webpack --config webpack.rails.config.js
Alternate, you can put $(npm bin) in your path. Basically if you run type webpack
and the path is your global one, then
you may have issues.
- You can configure the output file of the created CSS file by using a relative path to the output directory. For example:
plugins: [
new ExtractTextPlugin("../stylesheets/bootstrap-and-customizations.css")
]
Based on:
- bootstrap-webpack.
- DylanLukes/bootstrap-sass-webpack
Known Issues
- Automatic Dependency loading is currently problematic. If you "touch" either of the customization files listed in your config file (bootstrapCustomizations, mainSass), then that will trigger a rebuild of the Sass files. This is a known issue with the sass-loader. I work around this issue by "touching" one of the 3 sass config files.
Testing Changes in the Bootstrap Sass Loader
- See this article Debugging NodeJs and Webpack Loaders
- Clone both this project and https://github.com/shakacode/bootstrap-sass-loader-example
- Use the npm link command per step #1 (see article)
- Be sure to run
npm i bootstrap-sass
in the directory where you have thebootstrap-sass-loader
. This is because the location of bootstap-sass is found relative to thebootstrap-sass-loader
and if you linked it and it's not not there, then you'll bet this error: "Error: Could not find path to bootstrap-sass. Check to see that it's in a parent directory of config file containing node_modules/bootstrap-sass".
Then in the bootstrap-sass-loader-example project:
- Make some changes in the loader, put in some print statements maybe, then run
gulp webpack
to invoke the loader. - Then run
gulp build
and open the resulting file dist/index.html in the browser. - Run
gulp test
to confirm the changes work.
Pull requests are welcome!
For more info see: http://www.railsonmaui.com and http://forum.railsonmaui.com.
Code Inspection and ESLint
- If using Webstorm import the inspection file in /jetbrains-inspection and inspect all files
- Command line:
eslint .
Publishing to NPM
- Install the release-it npm program
- Merge fixes to master
- Run command
release-it
- Take defaults, except for last one to publish changes (answer Y)