Bootstrap v4 beta supported!
If you're using this project and you like it, please give us a star! Thanks!
Thank you from Justin Gordon and ShakaCode
- Video: Front-End Sadness to Happiness: The React on Rails Story: History, motivations, philosophy, and overview.
- Click here for talk slides.
We at ShakaCode are a small, boutique, remote-first application development company. We fund this project by:
- Providing priority support and training for anything related to React + Webpack + Rails in our Coaching Program.
- Building custom web and mobile (React Native) applications. We typically work with a technical founder or CTO and instantly provide a full development team including designers.
- Migrating Angular + Rails to React + Rails. You can see an example of React on Rails and our work converting Angular to React on Rails at egghead.io.
- Augmenting your team to get your product completed more efficiently and quickly.
My article "Why Hire ShakaCode?" provides additional details about our projects.
If any of this resonates with you, please email me, [email protected]. I offer a free half-hour project consultation, on anything from React on Rails to any aspect of web or mobile application development for both consumer and enterprise products.
We are currently looking to hire like-minded developers that wish to work on our projects, including Friends and Guests.
I appreciate your attention and sharing of these offerings with anybody that we can help. Your support allows me to bring you and your team front-end happiness in the Rails world.
Aloha and best wishes from the ShakaCode team!
Please Subscribe to keep in touch with Justin Gordon and ShakaCode. I intend to send a monthly summary including announcements of new releases of bootstrap-loader and React on Rails and of our latest blog articles and tutorials. Subscribers will also have access to exclusive content, including tips and examples.
- Slack Room: Contact us for an invite to the ShakaCode Slack room!
- forum.shakacode.com: Post your questions
- @ShakaCode on Twitter
React on Rails is ShakaCode's flagship product. We want to make sure you're aware of it!
From Joel Hooks, Co-Founder, Chief Nerd at egghead.io, January 30, 2017:
For more testimonials, see Live Projects and Kudos.
If you want the v1 docs which are compatible with Webpack v1, please see the v1 branch. If you're using v2, be sure to check the peer dependencies of webpack
and the extract-text-webpack-plugin
in the package.json.
Successor to bootstrap-sass-loader. Load Bootstrap styles and scripts in your Webpack bundle. This loader uses SASS to process CSS styles. Bootstrap 3 & 4 are supported.
NOTE: Bootstrap 4, twbs/bootstrap is currently in beta right now. Bootstrap 4 definitely worked when we first released this package. The parent company of this product, ShakaCode had originally planned to use it for our upcoming commercial product, but we decided that Bootstrap 4 was changing too fast for a production product. Thus, we're still using Bootstrap 3, and we're not actively developing with Bootstrap 4. Consequently, for Bootstrap 4 issues, we need one of:
- Community support to help us with Bootstrap 4 issues and pull requests.
- We'd be thrilled to have another maintainer join us to help with Bootstrap 4 issues.
- We'd also be thrilled if any companies are open to sponsoring the development of features and issues regarding Bootstrap
That being said, Bootstrap 4 probably works just fine! You must use 4.0.0-beta
or greater.
2017-08-17: Released 2.2.0. This release supports Bootstrap 4.0.0-beta instead of 4.0.0-alpha.6.
- Installation
- Usage
- Examples
- Common configuration options
- Additional configurations
- FAQ
- Contributing
- License
- Examples and related libraries
- Useful Q&A
Get it via npm:
npm install bootstrap-loader
Don't forget to install these dependencies (use --save or --save-dev
option per your needs to update your package.json
):
# Bootstrap 3
npm install --save-dev bootstrap-sass
# or Bootstrap 4
npm install --save-dev [email protected]
# Note, alpha.3 is broken, and alpha.2 is no longer supported
# Node SASS & other loaders needed to handle styles
npm install --save-dev css-loader node-sass resolve-url-loader sass-loader style-loader url-loader
# Additional loaders required for Bootstrap 4 & Webpack 2
npm install --save-dev imports-loader exports-loader
If you're using Bootstrap 4, you probably need:
npm install --save-dev postcss-loader
Simply require it:
require('bootstrap-loader');
Or add bootstrap-loader
as a module in an entry point in your webpack config (you'll need Webpack 2.1 beta and higher):
entry: [ 'bootstrap-loader', './app' ]
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 and Bootstrap 4. 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 that Node sets for us. It is "the name of the directory that the currently executing script resides in."
---
# You can use comments here
styleLoaders:
- style-loader
- css-loader
- sass-loader
styles:
normalize: true
print: true
scripts:
alert: true
button: true
{
// And JSON comments also!
"styleLoaders": ["style-loader", "css-loader", "sass-loader"],
"styles": {
"normalize": true,
"print": true
},
"scripts": {
"alert": true,
"button": true
}
}
If no config provided, default one for Bootstrap 3 will be used.
Because of Bootstrap 4's removal of UMD, internal dependencies, such as Popover's dependencies on Tooltip and Dropdown's dependency on Utils, are no longer naively resolved by Webpack (See Issue #172. In order to solve this issue, add the following code to your webpack configuration:
plugins: [
new webpack.ProvidePlugin({
$: "jquery",
jQuery: "jquery",
"window.jQuery": "jquery",
Tether: "tether",
"window.Tether": "tether",
Alert: "exports-loader?Alert!bootstrap/js/dist/alert",
Button: "exports-loader?Button!bootstrap/js/dist/button",
Carousel: "exports-loader?Carousel!bootstrap/js/dist/carousel",
Collapse: "exports-loader?Collapse!bootstrap/js/dist/collapse",
Dropdown: "exports-loader?Dropdown!bootstrap/js/dist/dropdown",
Modal: "exports-loader?Modal!bootstrap/js/dist/modal",
Popover: "exports-loader?Popover!bootstrap/js/dist/popover",
Scrollspy: "exports-loader?Scrollspy!bootstrap/js/dist/scrollspy",
Tab: "exports-loader?Tab!bootstrap/js/dist/tab",
Tooltip: "exports-loader?Tooltip!bootstrap/js/dist/tooltip",
Util: "exports-loader?Util!bootstrap/js/dist/util",
})
]
Check out example apps in examples/
folder:
- Basic usage: examples/basic
- See the
npm run bs4:customlocation
tasks for examples on how to pass your .bootstraprc config. - With CSS Modules: examples/css-modules (This example shows off hot reloading with Babel 6 as well!)
- With multiple entries examples/multiple-entries with their own config.
Here are common options for Bootstrap 3 & 4.
Default: disabled
Outputs debugging info. Set this option to debug
to output debugging information. This is critical for debugging issues. The output will go to your webpack console.
loglevel: debug
Default: 3
Major version of Bootstrap. Can be 3 or 4.
bootstrapVersion: 3
Default: [ 'style-loader', 'css-loader', 'sass-loader' ]
Array of webpack loaders. sass-loader
is required, order matters. In most cases the style loader should definitely go first and the sass loader should be last.
Note: Beginning with Webpack v2.1.0-beta.26, the '-loader' suffix is required for all loaders.
To maintain compatibility with older versions, all accepted style loaders (style, css, postcss, sass, resolve-url) are automatically appended with '-loader'.
It is recommended that you explicitly state the '-loader' suffix for every webpack loader in styleLoaders
to ensure compatibility in the long term.
styleLoaders:
- style-loader
- css-loader
- sass-loader
# You can apply loader params here:
- sass-loader?outputStyle=expanded
Different settings for different environments can be used.
# It depends on value of NODE_ENV environment variable
env:
development:
styleLoaders:
- style-loader
- css-loader
- resolve-url-loader
- sass-loader
production:
styleLoaders:
- style-loader
- css-loader
- sass-loader
Default: false
Extract styles to stand-alone css file using extract-text-webpack-plugin
version 2.0.0-beta or higher. See extract-text-plugin for more details.
extractStyles: false
# Different settings for different environments can be used,
# It depends on value of NODE_ENV environment variable
env:
development:
extractStyles: false
production:
extractStyles: true
This param can also be set to true
in webpack config:
entry: [ 'bootstrap-loader/extractStyles', './app' ]
See shakacode/react-webpack-rails-tutorial/blob/master/client/webpack.client.rails.build.config. for a working example which is deployed to www.reactrails.com.
Default: disabled
Customize Bootstrap variables that get imported before the original Bootstrap variables. Thus, derived Bootstrap variables can depend on values from here. See the Bootstrap _variables.scss
file for examples of derived Bootstrap variables.
preBootstrapCustomizations: ./path/to/bootstrap/pre-customizations.scss
Default: disabled
This gets loaded after bootstrap variables is loaded. Thus, you may customize Bootstrap variables based on the values established in the Bootstrap _variables.scss
file. Note, if bootstrap
did not have derived values, it would not be necessary to have two config files for customizing bootstrap values.
If you want your bootstrap override value to apply to derived variable values, then place your customizations in preBootstrapCustomizations
. If you want to be sure your changes don't affect other derived values, place the changes in bootstrapCustomizations.
If you are not sure, you can probably simply use preBootstrapCustomizations
and, if you have issues, see _variables.scss
for derived values.
bootstrapCustomizations: ./path/to/bootstrap/customizations.scss
Default: disabled
Import your custom styles here. Usually this endpoint-file contains list of @imports
of your application styles.
appStyles: ./path/to/your/app/styles/endpoint.scss
Default: all
Bootstrap styles.
styles:
mixins: true
normalize: true
...
# or enable/disable all of them:
styles: true / false
Default: all
Bootstrap scripts.
scripts:
transition: true
alert: true
...
# or enable/disable all of them:
scripts: true / false
Default: false
If you're using a custom icon font and you need to specify its path ($icon-font-path
) in your Sass files, set this option to true.
useCustomIconFontPath: true / false
$icon-font-path: ../fonts // relative to your Sass file
$icon-font-name: 'glyphicons' // you'll typically want to change this too.
There is only one additional option for Bootstrap 4:
Additionally, Bootstrap 4 requires Tether. You can add Tether per the examples in the /examples
directory.
- Add tether to package.json:
npm i --save tether
- Add tether as an entry point to your webpack config.
- Add this plugin to your webpack config:
plugins: [
new ExtractTextPlugin('app.css', { allChunks: true }),
new webpack.ProvidePlugin({
"window.Tether": "tether"
}),
],
Bootstrap 4 seems to require postcss:
- Add postcss and the the postcss-loader:
npm i --save postcss postcss-loader
- Put
postcss
beforesass
in the order of loaders in your.bootstraprc
file.
Glyphicons have been removed from Bootstrap 4. The examples demonstrate how to use the font-awesome-loader
If you use bootstrap-loader
to load your styles (via preBootstrapCustomizations
, bootstrapCustomizations
& appStyles
) and you load custom assets (fonts, images etc.), then you can use relative paths inside url
method (relative to SASS file, from which you load asset).
This was made possible thanks to resolve-url-loader. In common case you don't have to do anything special to apply it โ we are doing it internally (just don't forget to install it). But if you want to use its custom settings, please provide it explicitly via styleLoaders
option in .bootstraprc
:
styleLoaders:
- style-loader
- css-loader?sourceMap
- resolve-url-loader?sourceMap
- sass-loader?sourceMap
The following steps are needed to successfully incorporate a theme from Bootswatch:
-
Download the
.scss
files (_variables.scss
and_bootswatch.scss
) for the theme you have chosen. -
Put the files somewhere in your project structure (e.g. the
./styles
directory). -
Add an additional SCSS file, like bs-theme.scss, that contains the following:
@import './_bootswatch.scss';
-
Add the following to your .bootstraprc file:
preBootstrapCustomizations: ./styles/_variables.scss
appStyles: ./styles/bs-theme.scss
The theme should now be applied as expected. Note that this section might be valid for other theme packs as well.
See examples/multiple-entries/webpack.prod.config.js for an example configuration of the following:
- In
entry
, set up one bundle per theme. In each bundle includebootstrap-loader
withextractStyles
and the respective config file. - In
plugins,
set up theextract-text-webpack-plugin
to output each CSS file as[name].css
. This will output a CSS file named after each bundle.
If you want to use Bootstrap's JS scripts โ you have to provide jQuery
to Bootstrap JS modules using imports-loader
. To avoid having to include jQuery
in your project you can disable all scripts (see scripts).
module: {
loaders: [
// Use one of these to serve jQuery for Bootstrap scripts:
// Bootstrap 3
{ test:/bootstrap-sass[\/\\]assets[\/\\]javascripts[\/\\]/, loader: 'imports-loader?jQuery=jquery' },
// Bootstrap 4
{ test: /bootstrap[\/\\]dist[\/\\]js[\/\\]umd[\/\\]/, loader: 'imports-loader?jQuery=jquery' },
],
},
Note: if you're not concerned about Windows, the lines look like this (simpler regexp pattern):
// Boostrap 3
{ test: /bootstrap-sass\/assets\/javascripts\//, loader: 'imports-loader?jQuery=jquery' },
// Bootstrap 4
{ test: /bootstrap\/dist\/js\/umd\//, loader: 'imports-loader?jQuery=jquery' },
Bootstrap uses icon fonts. If you want to load them, don't forget to setup url-loader
or file-loader
in webpack config:
module: {
loaders: [
{ test: /\.(woff2?|svg)$/, loader: 'url-loader?limit=10000' },
{ test: /\.(ttf|eot)$/, loader: 'file-loader' },
],
},
You should use sass-resources-loader
in your webpack
config.
In your webpack.config.js
:
module.exports = {
// stuff removed for clarity ...
module: {
loaders: [
// stuff removed for clarity ...
{
test: /\.scss$/,
loader: ExtractTextPlugin.extract(
'style-loader',
'css-loader?modules&importLoaders=2&localIdentName=[name]__[local]__[hash:base64:5]' +
'!sass-loader' +
'!sass-resources-loader'
),
},
// stuff removed for clarity ...
],
},
// stuff removed for clarity ...
sassResources: './config/sass-resources.scss',
}
And in your ./config/sass-resources.scss
:
// Make variables and mixins available when using CSS modules.
@import "node_modules/bootstrap-sass/assets/stylesheets/bootstrap/_variables";
@import "node_modules/bootstrap-sass/assets/stylesheets/bootstrap/_mixins";
You can then use mixins and variables from Bootstrap in your own code.
By default, bootstrap-loader
will try to resolve bootstrap
from where bootstrap-loader
has been installed. In certain situations (e.g. npm linking, using a custom package installer) it may not be resolvable. In this case, you can pass in the location manually.
require('bootstrap-loader?bootstrapPath=/path/to/bootstrap');
// or
entry: [ 'bootstrap-loader?bootstrapPath=/path/to/bootstrap', './app' ]
See Contributing to get started.
MIT.
- react-webpack-rails-tutorial, live example at www.reactrails.com.
- sass-resources-loader
- Simple integration example
- React + hot reloading example: bootstrap-loader-css-modules-example
- react_on_rails gem
We'll identify issues that are questions.
Identical to top of page
Thank you from Justin Gordon and ShakaCode
- Video: Front-End Sadness to Happiness: The React on Rails Story: History, motivations, philosophy, and overview.
We at ShakaCode are a small, boutique, remote-first application development company. We fund this project by:
- Providing priority support and training for anything related to React + Webpack + Rails in our Coaching Program.
- Building custom web and mobile (React Native) applications. We typically work with a technical founder or CTO and instantly provide a full development team including designers.
- Migrating Angular + Rails to React + Rails. You can see an example of React on Rails and our work converting Angular to React on Rails at egghead.io.
- Augmenting your team to get your product completed more efficiently and quickly.
My article "Why Hire ShakaCode?" provides additional details about our projects.
If any of this resonates with you, please email me, [email protected]. I offer a free half-hour project consultation, on anything from React on Rails to any aspect of web or mobile application development for both consumer and enterprise products.
We are currently looking to hire like-minded developers that wish to work on our projects, including Friends and Guests.
I appreciate your attention and sharing of these offerings with anybody that we can help. Your support allows me to bring you and your team front-end happiness in the Rails world.
Aloha and best wishes from the ShakaCode team!