add webpack to documentation #22423

IdanCo · 2017-04-12T16:47:12Z

Summary

Add a guide to the official docs on how to integrate Bootstrap with Webpack.

Motivation

Webpack's popularity is growing, but there's a lack of reliable up-to-date resources on how to integrate it with Bootstrap
Following @mdo question in Bootstrap 4 with npm and webpack #22196

Background

During the past few months i've been integrating bootstrap into several new and existing projects using webpack version 2. This led me to conduct a thorough research and tests on the best practices to achieve this integration. The results of these efforts are in this guide.

Technical

Check out a sample project which implements the steps detailed in this guide -
https://github.com/IdanCo/webpack-modular/tree/bootstrap4

mdo

Looking at this, the only question I have is around the placement of this on a separate page—need to think about that a bit more. Also, is there anyone else out there using Webpack that would like to chime in with a review here?

ajacksified

I have a few minor optional comments, but otherwise this very similar to my own webpack config.

ajacksified · 2017-04-21T02:55:49Z

docs/getting-started/webpack.md

+{% callout info %}
+#### Customization
+
+To implement the powerful [options](/getting-started/options/) Bootstrap offers, create `_custom.scss` and import it **before** Bootstrap.


Since you include examples elsewhere, may be nice to do the same here for clarity:

To implement the powerful [options](/getting-started/options/) Bootstrap offers, create a file for variables, such as `_custom.scss`, and import it **before** Bootstrap: {% highlight scss %} // theme.scss $brand-primary: $green; {% endhighlight %} {% highlight scss %} @import "theme.scss"; @import "~bootstrap/scss/bootstrap"; {% endhighlight %}

@ajacksified thanks for the feedback! i'll push a new PR later

ajacksified · 2017-04-21T02:56:13Z

docs/getting-started/webpack.md

+group: getting-started
+---
+
+Use [webpack](https://webpack.js.org/) to bundle Bootstrap into your project.


May be worth mentioning that this is for webpack v2.

IdanCo · 2017-04-23T21:44:43Z

@ajacksified , i've explicitly mentioned webpack v2 and put more emphasize on custom variables (after all, why even use webpack if you're not planning on customizing?)

ajacksified · 2017-04-23T22:01:16Z

Sorry! Must have missed it.

…

On Apr 23, 2017 2:46 PM, "Idan Cohen" ***@***.***> wrote: @ajacksified <https://github.com/ajacksified> , i've explicitly mentioned webpack v2 and put more emphasize on custom variables (after all, why even use webpack if you're not planning on customizing?) — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#22423 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AAKtm40LIYB96Dt3nUA_35SSKxUPnROkks5ry8avgaJpZM4M7r3k> .

ajacksified · 2017-04-23T22:02:26Z

Disregard that, misread the notification email. Looks good to me!

implementing PR comments implementing PR comments

samsch · 2017-04-24T15:18:14Z

I would suggest using ExtractTextWebpackPlugin in the example, rather than style-loader. With style-loader, the styles are injected into <style> tags in the html head. With ExtractTextWebpackPlugin, the styles are extracted into a separate css file to be <link>ed in.

The downside is the slightly added complexity, but the upside is less "magic" around importing styles from JS.

IdanCo · 2017-04-24T20:41:27Z

@samsch , I agree that using ExtractText in many cases would be the best practice. It's actually used it in the demo project I attached to this PR - https://github.com/IdanCo/webpack-modular/tree/bootstrap4

But I'm not convinced it should be a part of the documentation. There are other best-practices (such as using source maps), but adding them to the documentation might imply that they are essential for compiling Bootstrap, even though they are in no way such. Also, i can think of many use cases in which using ExtractText plugin would be counter productive, such as serving dev server or running tests.

I hope other resources (blogs, stackoverflow, etc.) will expand and elaborate this basic setup. I know I plan to...

samsch · 2017-04-24T21:22:11Z

Just a quick counter argument. I'm actually less concerned with ExtractText being a best practice, and more interested in having a separate css file to be more similar to environments which users may be used to. I do see your point about it seeming to be "required" when it is not. Perhaps that could be satisfied with an additional sentence or two in the guide noting that it's optional.

mdo · 2017-05-02T04:54:43Z

Any other feedback before we merge this? (Also, hi @ajacksified! Long time no see! :D)

Johann-S · 2017-05-02T06:36:13Z

My only concern about this PR is, is it the role of BS to show how to integrate BS in any plugins, module bundler etc... ?
I know Webpack have a huge community and I love this tool but if we do that we'll have to do for others plugins too so we should create a dedicated page for that on our documentation

mdo · 2017-05-02T19:41:09Z

My only concern about this PR is, is it the role of BS to show how to integrate BS in any plugins, module bundler etc... ?

I think so, yes. I'd love more in-depth and helpful guides for using, extending, and contributing to Bootstrap—regardless of the package manager or community. Bootstrap is meant to be accessible to everyone, beginner or seasoned veteran, so I'm a fan :).

IdanCo · 2017-05-02T20:15:38Z

@mdo totally agree.

@Johann-S i see your point - Bootstrap can't be held responsible for what other bundlers are doing. But on the other hand, the bundlers also can't commit to how Bootstrap is structured (especially while in alpha). So the outcome is that integrations fall "between the chairs". So taking responsibility for documenting may not be the obvious choice, but it will help bring Bootstrap to more people, and i think that's worth it.

Regarding which bundlers should be included, IMO as long as there's a demand for integration documentation, it's worth considering adding.

Johann-S · 2017-05-02T20:41:46Z

That's ok for me 👍 it's just a choice to do

cr101 · 2017-05-02T21:20:34Z

We are integrating Bootstrap into our web app with Create React App

Johann-S · 2017-05-03T08:29:21Z

I think we can add this page on : Write a Learn & Extend or Approach section.

Related to #17021 (docs section) and #21548

Johann-S · 2017-05-15T09:43:39Z

@IdanCo can you update your branch ? because now we use Popper instead of Tether

IdanCo · 2017-05-15T09:57:47Z

Done! and congrats on the huge Popper PR @Johann-S , can't wait to give it a try!

Johann-S · 2017-05-15T10:00:46Z

Thank you very much @IdanCo ❤️

Johann-S · 2017-05-15T10:01:15Z

docs/getting-started/webpack.md

+        $: 'jquery',
+        jQuery: 'jquery',
+        'window.jQuery': 'jquery',
+        Tether: 'tether',


Can you change that by Popper ?

Johann-S · 2017-05-15T10:01:32Z

docs/getting-started/webpack.md

+...
+{% endhighlight %}
+
+Bootstrap is dependent on jQuery and Tether, so npm will install them for you if needed. But they must be explicitly provided by webpack. Add the following code to the `plugins` section in your webpack config file:


Can you change that by Popper ?

Johann-S · 2017-05-15T14:07:08Z

LGTM 👍

The merge is up to @mdo because he said :

Looking at this, the only question I have is around the placement of this on a separate page—need to think about that a bit more.

IdanCo · 2017-05-15T14:07:28Z

Changed the webpack configuration to accommodate popper instead of tether.

@Johann-S , any reason why bootstrap.js in v4-dev is not yet updated and still dependent on thether? I built it manually to do my tests and find the correct recipe, but I'm curious about the repo build process...

BTW, at first glance the new tooltips/popovers/dropdown looks great!

EDIT :

Looking at this, the only question I have is around the placement of this on a separate page—need to think about that a bit more.

no problem, let me know if there's anything i can do to help

Johann-S · 2017-05-15T14:11:28Z

Yes we build manualy dist files, currently they are outdated but we will update them soon 👍

And thank you for your feedbacks 👍

micky2be · 2017-05-23T07:48:02Z

docs/getting-started/webpack.md

+
+Import [Bootstrap's JavaScript](/getting-started/javascript/) by adding this line to your app's entry point (usally `index.js` or `app.js`):
+
+{% highlight js %}


Why don't you use the triple back tick?

import 'bootstrap';

Because we use highlight everywhere else due to our Jekyll setup.

mdo · 2017-05-26T04:05:06Z

Thanks y'all! Holler with PRs if y'all have newer/better ideas for setup docs with other tooling.

petrpacas · 2017-07-13T13:43:00Z

@mdo I'd like to point out an issue of compiling the JS with Bootstrap's individual /dist/ files (as hinted here).

I tested @IdanCo's repo and it looks fine when using the bootstrap.js scripts bundle.

However, if you include the /dist/ files individually (and necessarily reference them with ProvidePlugin), the code is duplicated in the resulting JS file (only referencing them in ProvidePlugin and not importing them doesn't work).

The solution for individual imports is, as suggested in the first link, to include the individual /src/ files instead and use a transpiler (Babel etc.).

IdanCo · 2017-07-13T14:19:21Z

Thanks @petrpacas , I'll have a look at it this weekend

mselerin · 2017-07-13T14:59:28Z

Hi @petrpacas. Personally, I don't use the Provide Plugin but the Expose Loader instead (see my comment here)

Maybe you could adapt your import with this loader and see what happen ?

petrpacas · 2017-07-13T15:19:50Z

For those interested, here's my repo with working example of using the individual source files w/ Babel instead:

https://github.com/petrpacas/webpack-bootstrap-4-setup

ccalvarez · 2017-08-07T20:19:25Z

Hi.

I followed the guide and for some reason it kept telling me that Tether was needed. I had to replace Popper with Tether.

I've installed Bootstrap with npm install --save [email protected] and in my package.json the dependency is "bootstrap": "^4.0.0-alpha.6",.

How can I get the dependency to Popper as explained in the documentation?
Thanks.

IdanCo · 2017-08-07T21:28:31Z

@ccalvarez, These instructions refer to the develop branch which replaced Tether with Popper.

For version Alpha 6 (which you probably use), You can browse the previous commit, or have a look in the issue discussion.

ccalvarez · 2017-08-07T22:04:18Z

@IdanCo I understand, thank you very much!

chrisalexander55 · 2017-09-14T03:02:24Z

Although the documentation is very good, I still found it incomplete regarding the actual NPM packages that need to be installed and interop with other loader(s) who generate source-maps. Here is a Gist that brings it together:

https://gist.github.com/chrisalexander55/81f3d5db057fbcbd74d62d488adbca8a

Please feel free to use this to update the docs page.

Johann-S added docs v4 labels Apr 12, 2017

IdanCo force-pushed the feature/webpack-docs branch from 1c41378 to 2817a1b Compare April 13, 2017 07:58

mdo approved these changes Apr 16, 2017

View reviewed changes

ajacksified approved these changes Apr 21, 2017

View reviewed changes

IdanCo force-pushed the feature/webpack-docs branch from 2817a1b to 4ca4f67 Compare April 23, 2017 21:39

add webpack to documentation"

2f4adf6

implementing PR comments implementing PR comments

IdanCo force-pushed the feature/webpack-docs branch from 4ca4f67 to 2f4adf6 Compare April 23, 2017 22:06

This was referenced May 9, 2017

OSS maintenance burnout and the Bootstrap 4 beta #22576

Closed

@import 'Bootstrap' not working twbs/bootstrap-sass#1119

Closed

Merge branch 'v4-dev' into feature/webpack-docs

4a907b3

Johann-S requested changes May 15, 2017

View reviewed changes

replace tether with popper

47992eb

Johann-S approved these changes May 15, 2017

View reviewed changes

micky2be reviewed May 23, 2017

View reviewed changes

Merge branch 'v4-dev' into feature/webpack-docs

f55e726

mdo merged commit fc5e8b9 into twbs:v4-dev May 26, 2017

mdo added this to the v4.0.0-beta milestone May 26, 2017

mdo mentioned this pull request May 26, 2017

Beta 1 ship list #21568

Closed

mdo mentioned this pull request May 27, 2017

Bootstrap 4 with npm and webpack #22196

Closed


		Import [Bootstrap's JavaScript](/getting-started/javascript/) by adding this line to your app's entry point (usally `index.js` or `app.js`):

		{% highlight js %}

add webpack to documentation #22423

add webpack to documentation #22423

Conversation

IdanCo commented Apr 12, 2017 • edited Loading

Summary

Motivation

Background

Technical

mdo left a comment • edited Loading

Choose a reason for hiding this comment

ajacksified left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

IdanCo commented Apr 23, 2017

ajacksified commented Apr 23, 2017 via email

ajacksified commented Apr 23, 2017

samsch commented Apr 24, 2017

IdanCo commented Apr 24, 2017

samsch commented Apr 24, 2017 via email • edited Loading

mdo commented May 2, 2017

Johann-S commented May 2, 2017

mdo commented May 2, 2017

IdanCo commented May 2, 2017 • edited Loading

Johann-S commented May 2, 2017

cr101 commented May 2, 2017

Johann-S commented May 3, 2017 • edited Loading

Johann-S commented May 15, 2017

IdanCo commented May 15, 2017

Johann-S commented May 15, 2017

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Johann-S commented May 15, 2017

IdanCo commented May 15, 2017 • edited by Johann-S Loading

Johann-S commented May 15, 2017 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

mdo commented May 26, 2017 • edited Loading

petrpacas commented Jul 13, 2017

IdanCo commented Jul 13, 2017

mselerin commented Jul 13, 2017

petrpacas commented Jul 13, 2017

ccalvarez commented Aug 7, 2017

IdanCo commented Aug 7, 2017

ccalvarez commented Aug 7, 2017

chrisalexander55 commented Sep 14, 2017

IdanCo commented Apr 12, 2017 •

edited

Loading

mdo left a comment •

edited

Loading

samsch commented Apr 24, 2017 via email •

edited

Loading

IdanCo commented May 2, 2017 •

edited

Loading

Johann-S commented May 3, 2017 •

edited

Loading

IdanCo commented May 15, 2017 •

edited by Johann-S

Loading

Johann-S commented May 15, 2017 •

edited

Loading

mdo commented May 26, 2017 •

edited

Loading