diff options
Diffstat (limited to 'site/content/docs/5.2/getting-started')
| -rw-r--r-- | site/content/docs/5.2/getting-started/accessibility.md | 62 | ||||
| -rw-r--r-- | site/content/docs/5.2/getting-started/best-practices.md | 20 | ||||
| -rw-r--r-- | site/content/docs/5.2/getting-started/browsers-devices.md | 79 | ||||
| -rw-r--r-- | site/content/docs/5.2/getting-started/contents.md | 111 | ||||
| -rw-r--r-- | site/content/docs/5.2/getting-started/contribute.md | 67 | ||||
| -rw-r--r-- | site/content/docs/5.2/getting-started/download.md | 119 | ||||
| -rw-r--r-- | site/content/docs/5.2/getting-started/introduction.md | 162 | ||||
| -rw-r--r-- | site/content/docs/5.2/getting-started/javascript.md | 337 | ||||
| -rw-r--r-- | site/content/docs/5.2/getting-started/parcel.md | 159 | ||||
| -rw-r--r-- | site/content/docs/5.2/getting-started/rfs.md | 86 | ||||
| -rw-r--r-- | site/content/docs/5.2/getting-started/rtl.md | 182 | ||||
| -rw-r--r-- | site/content/docs/5.2/getting-started/vite.md | 198 | ||||
| -rw-r--r-- | site/content/docs/5.2/getting-started/webpack.md | 322 |
13 files changed, 1904 insertions, 0 deletions
diff --git a/site/content/docs/5.2/getting-started/accessibility.md b/site/content/docs/5.2/getting-started/accessibility.md new file mode 100644 index 0000000..e9f1cb3 --- /dev/null +++ b/site/content/docs/5.2/getting-started/accessibility.md @@ -0,0 +1,62 @@ +--- +layout: docs +title: Accessibility +description: A brief overview of Bootstrap's features and limitations for the creation of accessible content. +group: getting-started +toc: true +--- + +Bootstrap provides an easy-to-use framework of ready-made styles, layout tools, and interactive components, allowing developers to create websites and applications that are visually appealing, functionally rich, and accessible out of the box. + +## Overview and limitations + +The overall accessibility of any project built with Bootstrap depends in large part on the author's markup, additional styling, and scripting they've included. However, provided that these have been implemented correctly, it should be perfectly possible to create websites and applications with Bootstrap that fulfill [<abbr title="Web Content Accessibility Guidelines">WCAG</abbr> 2.1](https://www.w3.org/TR/WCAG/) (A/AA/AAA), [Section 508](https://www.section508.gov/), and similar accessibility standards and requirements. + +### Structural markup + +Bootstrap's styling and layout can be applied to a wide range of markup structures. This documentation aims to provide developers with best practice examples to demonstrate the use of Bootstrap itself and illustrate appropriate semantic markup, including ways in which potential accessibility concerns can be addressed. + +### Interactive components + +Bootstrap's interactive components—such as modal dialogs, dropdown menus, and custom tooltips—are designed to work for touch, mouse, and keyboard users. Through the use of relevant [<abbr title="Web Accessibility Initiative">WAI</abbr>-<abbr title="Accessible Rich Internet Applications">ARIA</abbr>](https://www.w3.org/WAI/standards-guidelines/aria/) roles and attributes, these components should also be understandable and operable using assistive technologies (such as screen readers). + +Because Bootstrap's components are purposely designed to be fairly generic, authors may need to include further <abbr title="Accessible Rich Internet Applications">ARIA</abbr> roles and attributes, as well as JavaScript behavior, to more accurately convey the precise nature and functionality of their component. This is usually noted in the documentation. + +### Color contrast + +Some combinations of colors that currently make up Bootstrap's default palette—used throughout the framework for things such as button variations, alert variations, form validation indicators—may lead to *insufficient* color contrast (below the recommended [WCAG 2.1 text color contrast ratio of 4.5:1](https://www.w3.org/TR/WCAG/#contrast-minimum) and the [WCAG 2.1 non-text color contrast ratio of 3:1](https://www.w3.org/TR/WCAG/#non-text-contrast)), particularly when used against a light background. Authors are encouraged to test their specific uses of color and, where necessary, manually modify/extend these default colors to ensure adequate color contrast ratios. + +### Visually hidden content + +Content which should be visually hidden, but remain accessible to assistive technologies such as screen readers, can be styled using the `.visually-hidden` class. This can be useful in situations where additional visual information or cues (such as meaning denoted through the use of color) need to also be conveyed to non-visual users. + +```html +<p class="text-danger"> + <span class="visually-hidden">Danger: </span> + This action is not reversible +</p> +``` + +For visually hidden interactive controls, such as traditional "skip" links, use the `.visually-hidden-focusable` class. This will ensure that the control becomes visible once focused (for sighted keyboard users). **Watch out, compared to the equivalent `.sr-only` and `.sr-only-focusable` classes in past versions, Bootstrap 5's `.visually-hidden-focusable` is a standalone class, and must not be used in combination with the `.visually-hidden` class.** + +```html +<a class="visually-hidden-focusable" href="#content">Skip to main content</a> +``` + +### Reduced motion + +Bootstrap includes support for the [`prefers-reduced-motion` media feature](https://www.w3.org/TR/mediaqueries-5/#prefers-reduced-motion). In browsers/environments that allow the user to specify their preference for reduced motion, most CSS transition effects in Bootstrap (for instance, when a modal dialog is opened or closed, or the sliding animation in carousels) will be disabled, and meaningful animations (such as spinners) will be slowed down. + +On browsers that support `prefers-reduced-motion`, and where the user has *not* explicitly signaled that they'd prefer reduced motion (i.e. where `prefers-reduced-motion: no-preference`), Bootstrap enables smooth scrolling using the `scroll-behavior` property. + +## Additional resources + +- [Web Content Accessibility Guidelines (WCAG) 2.1](https://www.w3.org/TR/WCAG/) +- [The A11Y Project](https://www.a11yproject.com/) +- [MDN accessibility documentation](https://developer.mozilla.org/en-US/docs/Web/Accessibility) +- [Tenon.io Accessibility Checker](https://tenon.io/) +- [Color Contrast Analyser (CCA)](https://www.tpgi.com/color-contrast-checker/) +- ["HTML Codesniffer" bookmarklet for identifying accessibility issues](https://github.com/squizlabs/HTML_CodeSniffer) +- [Microsoft Accessibility Insights](https://accessibilityinsights.io/) +- [Deque Axe testing tools](https://www.deque.com/axe/) +- [Introduction to Web Accessibility](https://www.w3.org/WAI/fundamentals/accessibility-intro/) diff --git a/site/content/docs/5.2/getting-started/best-practices.md b/site/content/docs/5.2/getting-started/best-practices.md new file mode 100644 index 0000000..449d02a --- /dev/null +++ b/site/content/docs/5.2/getting-started/best-practices.md @@ -0,0 +1,20 @@ +--- +layout: docs +title: Best practices +description: Learn about some of the best practices we've gathered from years of working on and using Bootstrap. +group: getting-started +--- + +We've designed and developed Bootstrap to work in a number of environments. Here are some of the best practices we've gathered from years of working on and using it ourselves. + +{{< callout info >}} +**Heads up!** This copy is a work in progress. +{{< /callout >}} + +### General outline + +- Working with CSS +- Working with Sass files +- Building new CSS components +- Working with flexbox +- Ask in [our GitHub Discussions](https://github.com/twbs/bootstrap/discussions) diff --git a/site/content/docs/5.2/getting-started/browsers-devices.md b/site/content/docs/5.2/getting-started/browsers-devices.md new file mode 100644 index 0000000..dc550ec --- /dev/null +++ b/site/content/docs/5.2/getting-started/browsers-devices.md @@ -0,0 +1,79 @@ +--- +layout: docs +title: Browsers and devices +description: Learn about the browsers and devices, from modern to old, that are supported by Bootstrap, including known quirks and bugs for each. +group: getting-started +toc: true +--- + +## Supported browsers + +Bootstrap supports the **latest, stable releases** of all major browsers and platforms. + +Alternative browsers which use the latest version of WebKit, Blink, or Gecko, whether directly or via the platform's web view API, are not explicitly supported. However, Bootstrap should (in most cases) display and function correctly in these browsers as well. More specific support information is provided below. + +You can find our supported range of browsers and their versions [in our `.browserslistrc file`]({{< param repo >}}/blob/v{{< param current_version >}}/.browserslistrc): + +```text +{{< rf.inline >}} +{{- readFile ".browserslistrc" | chomp | htmlEscape -}} +{{< /rf.inline >}} +``` + +We use [Autoprefixer](https://github.com/postcss/autoprefixer) to handle intended browser support via CSS prefixes, which uses [Browserslist](https://github.com/browserslist/browserslist) to manage these browser versions. Consult their documentation for how to integrate these tools into your projects. + +### Mobile devices + +Generally speaking, Bootstrap supports the latest versions of each major platform's default browsers. Note that proxy browsers (such as Opera Mini, Opera Mobile's Turbo mode, UC Browser Mini, Amazon Silk) are not supported. + +{{< bs-table "table" >}} +| | Chrome | Firefox | Safari | Android Browser & WebView | +| --- | --- | --- | --- | --- | +| **Android** | Supported | Supported | <span class="text-muted">—</span> | v6.0+ | +| **iOS** | Supported | Supported | Supported | <span class="text-muted">—</span> | +{{< /bs-table >}} + +### Desktop browsers + +Similarly, the latest versions of most desktop browsers are supported. + +{{< bs-table "table" >}} +| | Chrome | Firefox | Microsoft Edge | Opera | Safari | +| --- | --- | --- | --- | --- | --- | +| **Mac** | Supported | Supported | Supported | Supported | Supported | +| **Windows** | Supported | Supported | Supported | Supported | <span class="text-muted">—</span> | +{{< /bs-table >}} + +For Firefox, in addition to the latest normal stable release, we also support the latest [Extended Support Release (ESR)](https://www.mozilla.org/en-US/firefox/enterprise/) version of Firefox. + +Unofficially, Bootstrap should look and behave well enough in Chromium and Chrome for Linux, and Firefox for Linux, though they are not officially supported. + +## Internet Explorer + +Internet Explorer is not supported. **If you require Internet Explorer support, please use Bootstrap v4.** + +## Modals and dropdowns on mobile + +### Overflow and scrolling + +Support for `overflow: hidden;` on the `<body>` element is quite limited in iOS and Android. To that end, when you scroll past the top or bottom of a modal in either of those devices' browsers, the `<body>` content will begin to scroll. See [Chrome bug #175502](https://bugs.chromium.org/p/chromium/issues/detail?id=175502) (fixed in Chrome v40) and [WebKit bug #153852](https://bugs.webkit.org/show_bug.cgi?id=153852). + +### iOS text fields and scrolling + +As of iOS 9.2, while a modal is open, if the initial touch of a scroll gesture is within the boundary of a textual `<input>` or a `<textarea>`, the `<body>` content underneath the modal will be scrolled instead of the modal itself. See [WebKit bug #153856](https://bugs.webkit.org/show_bug.cgi?id=153856). + +### Navbar Dropdowns + +The `.dropdown-backdrop` element isn't used on iOS in the nav because of the complexity of z-indexing. Thus, to close dropdowns in navbars, you must directly click the dropdown element (or [any other element which will fire a click event in iOS](https://developer.mozilla.org/en-US/docs/Web/API/Element/click_event#Safari_Mobile)). + +## Browser zooming + +Page zooming inevitably presents rendering artifacts in some components, both in Bootstrap and the rest of the web. Depending on the issue, we may be able to fix it (search first and then open an issue if need be). However, we tend to ignore these as they often have no direct solution other than hacky workarounds. + +## Validators + +In order to provide the best possible experience to old and buggy browsers, Bootstrap uses [CSS browser hacks](http://browserhacks.com/) in several places to target special CSS to certain browser versions in order to work around bugs in the browsers themselves. These hacks understandably cause CSS validators to complain that they are invalid. In a couple places, we also use bleeding-edge CSS features that aren't yet fully standardized, but these are used purely for progressive enhancement. + +These validation warnings don't matter in practice since the non-hacky portion of our CSS does fully validate and the hacky portions don't interfere with the proper functioning of the non-hacky portion, hence why we deliberately ignore these particular warnings. + +Our HTML docs likewise have some trivial and inconsequential HTML validation warnings due to our inclusion of a workaround for [a certain Firefox bug](https://bugzilla.mozilla.org/show_bug.cgi?id=654072). diff --git a/site/content/docs/5.2/getting-started/contents.md b/site/content/docs/5.2/getting-started/contents.md new file mode 100644 index 0000000..88632b6 --- /dev/null +++ b/site/content/docs/5.2/getting-started/contents.md @@ -0,0 +1,111 @@ +--- +layout: docs +title: Contents +description: Discover what's included in Bootstrap, including our compiled and source code flavors. +group: getting-started +toc: true +--- + +## Compiled Bootstrap + +Once downloaded, unzip the compressed folder and you'll see something like this: + +<!-- NOTE: This info is intentionally duplicated in the README. Copy any changes made here over to the README too, but be sure to keep in mind to add the `dist` folder. --> + +```text +bootstrap/ +├── css/ +│ ├── bootstrap-grid.css +│ ├── bootstrap-grid.css.map +│ ├── bootstrap-grid.min.css +│ ├── bootstrap-grid.min.css.map +│ ├── bootstrap-grid.rtl.css +│ ├── bootstrap-grid.rtl.css.map +│ ├── bootstrap-grid.rtl.min.css +│ ├── bootstrap-grid.rtl.min.css.map +│ ├── bootstrap-reboot.css +│ ├── bootstrap-reboot.css.map +│ ├── bootstrap-reboot.min.css +│ ├── bootstrap-reboot.min.css.map +│ ├── bootstrap-reboot.rtl.css +│ ├── bootstrap-reboot.rtl.css.map +│ ├── bootstrap-reboot.rtl.min.css +│ ├── bootstrap-reboot.rtl.min.css.map +│ ├── bootstrap-utilities.css +│ ├── bootstrap-utilities.css.map +│ ├── bootstrap-utilities.min.css +│ ├── bootstrap-utilities.min.css.map +│ ├── bootstrap-utilities.rtl.css +│ ├── bootstrap-utilities.rtl.css.map +│ ├── bootstrap-utilities.rtl.min.css +│ ├── bootstrap-utilities.rtl.min.css.map +│ ├── bootstrap.css +│ ├── bootstrap.css.map +│ ├── bootstrap.min.css +│ ├── bootstrap.min.css.map +│ ├── bootstrap.rtl.css +│ ├── bootstrap.rtl.css.map +│ ├── bootstrap.rtl.min.css +│ └── bootstrap.rtl.min.css.map +└── js/ + ├── bootstrap.bundle.js + ├── bootstrap.bundle.js.map + ├── bootstrap.bundle.min.js + ├── bootstrap.bundle.min.js.map + ├── bootstrap.esm.js + ├── bootstrap.esm.js.map + ├── bootstrap.esm.min.js + ├── bootstrap.esm.min.js.map + ├── bootstrap.js + ├── bootstrap.js.map + ├── bootstrap.min.js + └── bootstrap.min.js.map +``` + +This is the most basic form of Bootstrap: compiled files for quick drop-in usage in nearly any web project. We provide compiled CSS and JS (`bootstrap.*`), as well as compiled and minified CSS and JS (`bootstrap.min.*`). [Source maps](https://developers.google.com/web/tools/chrome-devtools/javascript/source-maps) (`bootstrap.*.map`) are available for use with certain browsers' developer tools. Bundled JS files (`bootstrap.bundle.js` and minified `bootstrap.bundle.min.js`) include [Popper](https://popper.js.org/). + +### CSS files + +Bootstrap includes a handful of options for including some or all of our compiled CSS. + +{{< bs-table "table" >}} +| CSS files | Layout | Content | Components | Utilities | +| --- | --- | --- | --- | --- | +| `bootstrap.css`<br> `bootstrap.min.css`<br> `bootstrap.rtl.css`<br> `bootstrap.rtl.min.css` | Included | Included | Included | Included | +| `bootstrap-grid.css`<br> `bootstrap-grid.rtl.css`<br> `bootstrap-grid.min.css`<br> `bootstrap-grid.rtl.min.css` | [Only grid system]({{< docsref "/layout/grid" >}}) | — | — | [Only flex utilities]({{< docsref "/utilities/flex" >}}) | +| `bootstrap-utilities.css`<br> `bootstrap-utilities.rtl.css`<br> `bootstrap-utilities.min.css`<br> `bootstrap-utilities.rtl.min.css` | — | — | — | Included | +| `bootstrap-reboot.css`<br> `bootstrap-reboot.rtl.css`<br> `bootstrap-reboot.min.css`<br> `bootstrap-reboot.rtl.min.css` | — | [Only Reboot]({{< docsref "/content/reboot" >}}) | — | — | +{{< /bs-table >}} + +### JS files + +Similarly, we have options for including some or all of our compiled JavaScript. + +{{< bs-table "table" >}} +| JS Files | Popper | +| --- | --- | +| `bootstrap.bundle.js`<br> `bootstrap.bundle.min.js`<br> | Included | +| `bootstrap.js`<br> `bootstrap.min.js`<br> | – | +{{< /bs-table >}} + +## Bootstrap source code + +The Bootstrap source code download includes the compiled CSS and JavaScript assets, along with source Sass, JavaScript, and documentation. More specifically, it includes the following and more: + +```text +bootstrap/ +├── dist/ +│ ├── css/ +│ └── js/ +├── site/ +│ └──content/ +│ └── docs/ +│ └── {{< param docs_version >}}/ +│ └── examples/ +├── js/ +└── scss/ +``` + +The `scss/` and `js/` are the source code for our CSS and JavaScript. The `dist/` folder includes everything listed in the compiled download section above. The `site/content/docs/` folder includes the source code for our hosted documentation, including our live examples of Bootstrap usage. + +Beyond that, any other included file provides support for packages, license information, and development. diff --git a/site/content/docs/5.2/getting-started/contribute.md b/site/content/docs/5.2/getting-started/contribute.md new file mode 100644 index 0000000..6b3de43 --- /dev/null +++ b/site/content/docs/5.2/getting-started/contribute.md @@ -0,0 +1,67 @@ +--- +layout: docs +title: Contribute +description: Help develop Bootstrap with our documentation build scripts and tests. +group: getting-started +toc: true +aliases: "/docs/5.2/getting-started/build-tools/" +--- + +## Tooling setup + +Bootstrap uses [npm scripts](https://docs.npmjs.com/misc/scripts/) to build the documentation and compile source files. Our [package.json]({{< param repo >}}/blob/v{{< param current_version >}}/package.json) houses these scripts for compiling code, running tests, and more. These aren't intended for use outside our repository and documentation. + +To use our build system and run our documentation locally, you'll need a copy of Bootstrap's source files and Node. Follow these steps and you should be ready to rock: + +1. [Download and install Node.js](https://nodejs.org/en/download/), which we use to manage our dependencies. +2. Either [download Bootstrap's sources]({{< param "download.source" >}}) or fork [Bootstrap's repository]({{< param repo >}}). +3. Navigate to the root `/bootstrap` directory and run `npm install` to install our local dependencies listed in [package.json]({{< param repo >}}/blob/v{{< param current_version >}}/package.json). + +When completed, you'll be able to run the various commands provided from the command line. + +## Using npm scripts + +Our [package.json]({{< param repo >}}/blob/v{{< param current_version >}}/package.json) includes numerous tasks for developing the project. Run `npm run` to see all the npm scripts in your terminal. **Primary tasks include:** + +{{< bs-table >}} +| Task | Description | +| --- | --- | +| `npm start` | Compiles CSS and JavaScript, builds the documentation, and starts a local server. | +| `npm run dist` | Creates the `dist/` directory with compiled files. Uses [Sass](https://sass-lang.com/), [Autoprefixer](https://github.com/postcss/autoprefixer), and [terser](https://github.com/terser/terser). | +| `npm test` | Runs tests locally after running `npm run dist` | +| `npm run docs-serve` | Builds and runs the documentation locally. | +{{< /bs-table >}} + +{{< callout info >}} +{{< partial "callout-info-npm-starter.md" >}} +{{< /callout >}} + +## Sass + +Bootstrap uses [Dart Sass](https://sass-lang.com/dart-sass) for compiling our Sass source files into CSS files (included in our build process), and we recommend you do the same if you're compiling Sass using your own asset pipeline. We previously used Node Sass for Bootstrap v4, but LibSass and packages built on top of it, including Node Sass, are now [deprecated](https://sass-lang.com/blog/libsass-is-deprecated). + +Dart Sass uses a rounding precision of 10 and for efficiency reasons does not allow adjustment of this value. We don't lower this precision during further processing of our generated CSS, such as during minification, but if you chose to do so we recommend maintaining a precision of at least 6 to prevent issues with browser rounding. + +## Autoprefixer + +Bootstrap uses [Autoprefixer](https://github.com/postcss/autoprefixer) (included in our build process) to automatically add vendor prefixes to some CSS properties at build time. Doing so saves us time and code by allowing us to write key parts of our CSS a single time while eliminating the need for vendor mixins like those found in v3. + +We maintain the list of browsers supported through Autoprefixer in a separate file within our GitHub repository. See [.browserslistrc]({{< param repo >}}/blob/v{{< param current_version >}}/.browserslistrc) for details. + +## RTLCSS + +Bootstrap uses [RTLCSS](https://rtlcss.com/) to process compiled CSS and convert them to RTL – basically replacing horizontal direction aware properties (e.g. `padding-left`) with their opposite. It allows us only write our CSS a single time and make minor tweaks using RTLCSS [control](https://rtlcss.com/learn/usage-guide/control-directives/) and [value](https://rtlcss.com/learn/usage-guide/value-directives/) directives. + +## Local documentation + +Running our documentation locally requires the use of Hugo, which gets installed via the [hugo-bin](https://www.npmjs.com/package/hugo-bin) npm package. Hugo is a blazingly fast and quite extensible static site generator that provides us: basic includes, Markdown-based files, templates, and more. Here's how to get it started: + +1. Run through the [tooling setup](#tooling-setup) above to install all dependencies. +2. From the root `/bootstrap` directory, run `npm run docs-serve` in the command line. +3. Open `http://localhost:9001/` in your browser, and voilà. + +Learn more about using Hugo by reading its [documentation](https://gohugo.io/documentation/). + +## Troubleshooting + +Should you encounter problems with installing dependencies, uninstall all previous dependency versions (global and local). Then, rerun `npm install`. diff --git a/site/content/docs/5.2/getting-started/download.md b/site/content/docs/5.2/getting-started/download.md new file mode 100644 index 0000000..b06c055 --- /dev/null +++ b/site/content/docs/5.2/getting-started/download.md @@ -0,0 +1,119 @@ +--- +layout: docs +title: Download +description: Download Bootstrap to get the compiled CSS and JavaScript, source code, or include it with your favorite package managers like npm, RubyGems, and more. +group: getting-started +toc: true +--- + +## Compiled CSS and JS + +Download ready-to-use compiled code for **Bootstrap v{{< param current_version >}}** to easily drop into your project, which includes: + +- Compiled and minified CSS bundles (see [CSS files comparison]({{< docsref "/getting-started/contents#css-files" >}})) +- Compiled and minified JavaScript plugins (see [JS files comparison]({{< docsref "/getting-started/contents#js-files" >}})) + +This doesn't include documentation, source files, or any optional JavaScript dependencies like Popper. + +<a href="{{< param "download.dist" >}}" class="btn btn-bd-primary" onclick="ga('send', 'event', 'Getting started', 'Download', 'Download Bootstrap');">Download</a> + +## Source files + +Compile Bootstrap with your own asset pipeline by downloading our source Sass, JavaScript, and documentation files. This option requires some additional tooling: + +- [Sass compiler]({{< docsref "/getting-started/contribute#sass" >}}) for compiling Sass source files into CSS files +- [Autoprefixer](https://github.com/postcss/autoprefixer) for CSS vendor prefixing + +Should you require our full set of [build tools]({{< docsref "/getting-started/contribute#tooling-setup" >}}), they are included for developing Bootstrap and its docs, but they're likely unsuitable for your own purposes. + +<a href="{{< param "download.source" >}}" class="btn btn-bd-primary" onclick="ga('send', 'event', 'Getting started', 'Download', 'Download source');">Download source</a> + +## Examples + +If you want to download and examine our [examples]({{< docsref "/examples" >}}), you can grab the already built examples: + +<a href="{{< param "download.dist_examples" >}}" class="btn btn-bd-primary" onclick="ga('send', 'event', 'Getting started', 'Download', 'Download Examples');">Download Examples</a> + +## CDN via jsDelivr + +Skip the download with [jsDelivr](https://www.jsdelivr.com/) to deliver cached version of Bootstrap's compiled CSS and JS to your project. + +```html +<link href="{{< param "cdn.css" >}}" rel="stylesheet" integrity="{{< param "cdn.css_hash" >}}" crossorigin="anonymous"> +<script src="{{< param "cdn.js_bundle" >}}" integrity="{{< param "cdn.js_bundle_hash" >}}" crossorigin="anonymous"></script> +``` + +If you're using our compiled JavaScript and prefer to include Popper separately, add Popper before our JS, via a CDN preferably. + +```html +<script src="{{< param "cdn.popper" >}}" integrity="{{< param "cdn.popper_hash" >}}" crossorigin="anonymous"></script> +<script src="{{< param "cdn.js" >}}" integrity="{{< param "cdn.js_hash" >}}" crossorigin="anonymous"></script> +``` + +## Package managers + +Pull in Bootstrap's **source files** into nearly any project with some of the most popular package managers. No matter the package manager, Bootstrap will **require a [Sass compiler]({{< docsref "/getting-started/contribute#sass" >}}) and [Autoprefixer](https://github.com/postcss/autoprefixer)** for a setup that matches our official compiled versions. + +### npm + +Install Bootstrap in your Node.js powered apps with [the npm package](https://www.npmjs.com/package/bootstrap): + +```sh +npm install bootstrap@{{< param "current_version" >}} +``` + +`const bootstrap = require('bootstrap')` or `import bootstrap from 'bootstrap'` will load all of Bootstrap's plugins onto a `bootstrap` object. +The `bootstrap` module itself exports all of our plugins. You can manually load Bootstrap's plugins individually by loading the `/js/dist/*.js` files under the package's top-level directory. + +Bootstrap's `package.json` contains some additional metadata under the following keys: + +- `sass` - path to Bootstrap's main [Sass](https://sass-lang.com/) source file +- `style` - path to Bootstrap's non-minified CSS that's been compiled using the default settings (no customization) + +{{< callout info >}} +{{< partial "callout-info-npm-starter.md" >}} +{{< /callout >}} + +### yarn + +Install Bootstrap in your Node.js powered apps with [the yarn package](https://yarnpkg.com/en/package/bootstrap): + +```sh +yarn add bootstrap@{{< param "current_version" >}} +``` + +### RubyGems + +Install Bootstrap in your Ruby apps using [Bundler](https://bundler.io/) (**recommended**) and [RubyGems](https://rubygems.org/) by adding the following line to your [`Gemfile`](https://bundler.io/gemfile.html): + +```ruby +gem 'bootstrap', '~> {{< param current_ruby_version >}}' +``` + +Alternatively, if you're not using Bundler, you can install the gem by running this command: + +```sh +gem install bootstrap -v {{< param current_ruby_version >}} +``` + +[See the gem's README](https://github.com/twbs/bootstrap-rubygem/blob/master/README.md) for further details. + +### Composer + +You can also install and manage Bootstrap's Sass and JavaScript using [Composer](https://getcomposer.org/): + +```sh +composer require twbs/bootstrap:{{< param current_version >}} +``` + +### NuGet + +If you develop in .NET Framework, you can also install and manage Bootstrap's [CSS](https://www.nuget.org/packages/bootstrap/) or [Sass](https://www.nuget.org/packages/bootstrap.sass/) and JavaScript using [NuGet](https://www.nuget.org/). Newer projects should use [libman](https://docs.microsoft.com/en-us/aspnet/core/client-side/libman/) or another method as NuGet is designed for compiled code, not frontend assets. + +```powershell +Install-Package bootstrap +``` + +```powershell +Install-Package bootstrap.sass +``` diff --git a/site/content/docs/5.2/getting-started/introduction.md b/site/content/docs/5.2/getting-started/introduction.md new file mode 100644 index 0000000..f0072bf --- /dev/null +++ b/site/content/docs/5.2/getting-started/introduction.md @@ -0,0 +1,162 @@ +--- +layout: docs +title: Get started with Bootstrap +description: Bootstrap is a powerful, feature-packed frontend toolkit. Build anything—from prototype to production—in minutes. +group: getting-started +aliases: + - "/docs/5.2/getting-started/" + - "/docs/getting-started/" + - "/getting-started/" +toc: true +--- + +## Quick start + +Get started by including Bootstrap's production-ready CSS and JavaScript via CDN without the need for any build steps. See it in practice with this [Bootstrap CodePen demo](https://codepen.io/team/bootstrap/pen/qBamdLj). + +<br> + +1. **Create a new `index.html` file in your project root.** Include the `<meta name="viewport">` tag as well for [proper responsive behavior](https://developer.mozilla.org/en-US/docs/Web/HTML/Viewport_meta_tag) in mobile devices. + + ```html + <!doctype html> + <html lang="en"> + <head> + <meta charset="utf-8"> + <meta name="viewport" content="width=device-width, initial-scale=1"> + <title>Bootstrap demo</title> + </head> + <body> + <h1>Hello, world!</h1> + </body> + </html> + ``` + +2. **Include Bootstrap's CSS and JS.** Place the `<link>` tag in the `<head>` for our CSS, and the `<script>` tag for our JavaScript bundle (including Popper for positioning dropdowns, poppers, and tooltips) before the closing `</body>`. Learn more about our [CDN links](#cdn-links). + + ```html + <!doctype html> + <html lang="en"> + <head> + <meta charset="utf-8"> + <meta name="viewport" content="width=device-width, initial-scale=1"> + <title>Bootstrap demo</title> + <link href="{{< param "cdn.css" >}}" rel="stylesheet" integrity="{{< param "cdn.css_hash" >}}" crossorigin="anonymous"> + </head> + <body> + <h1>Hello, world!</h1> + <script src="{{< param "cdn.js_bundle" >}}" integrity="{{< param "cdn.js_bundle_hash" >}}" crossorigin="anonymous"></script> + </body> + </html> + ``` + + You can also include [Popper](https://popper.js.org/) and our JS separately. If you don't plan to use dropdowns, popovers, or tooltips, save some kilobytes by not including Popper. + + ```html + <script src="{{< param "cdn.popper" >}}" integrity="{{< param "cdn.popper_hash" >}}" crossorigin="anonymous"></script> + <script src="{{< param "cdn.js" >}}" integrity="{{< param "cdn.js_hash" >}}" crossorigin="anonymous"></script> + ``` + +3. **Hello, world!** Open the page in your browser of choice to see your Bootstrapped page. Now you can start building with Bootstrap by creating your own [layout]({{< docsref "/layout/grid" >}}), adding dozens of [components]({{< docsref "/components/buttons" >}}), and utilizing [our official examples]({{< docsref "/examples" >}}). + +## CDN links + +As reference, here are our primary CDN links. + +{{< bs-table >}} +| Description | URL | +| --- | --- | +| CSS | `{{< param "cdn.css" >}}` | +| JS | `{{< param "cdn.js_bundle" >}}` | +{{< /bs-table >}} + +You can also use the CDN to fetch any of our [additional builds listed in the Contents page]({{< docsref "/getting-started/contents" >}}). + +## Next steps + +- Read a bit more about some [important global environment settings](#important-globals) that Bootstrap utilizes. + +- Read about what's included in Bootstrap in our [contents section]({{< docsref "/getting-started/contents/" >}}) and the list of [components that require JavaScript](#js-components) below. + +- Need a little more power? Consider building with Bootstrap by [including the source files via package manager]({{< docsref "/getting-started/download#package-managers" >}}). + +- Looking to use Bootstrap as a module with `<script type="module">`? Please refer to our [using Bootstrap as a module]({{< docsref "/getting-started/javascript#using-bootstrap-as-a-module" >}}) section. + +## JS components + +Curious which components explicitly require our JavaScript and Popper? Click the show components link below. If you're at all unsure about the general page structure, keep reading for an example page template. + +<details> +<summary class="text-primary mb-3">Show components requiring JavaScript</summary> +{{< markdown >}} +- Alerts for dismissing +- Buttons for toggling states and checkbox/radio functionality +- Carousel for all slide behaviors, controls, and indicators +- Collapse for toggling visibility of content +- Dropdowns for displaying and positioning (also requires [Popper](https://popper.js.org/)) +- Modals for displaying, positioning, and scroll behavior +- Navbar for extending our Collapse and Offcanvas plugins to implement responsive behaviors +- Navs with the Tab plugin for toggling content panes +- Offcanvases for displaying, positioning, and scroll behavior +- Scrollspy for scroll behavior and navigation updates +- Toasts for displaying and dismissing +- Tooltips and popovers for displaying and positioning (also requires [Popper](https://popper.js.org/)) +{{< /markdown >}} +</details> + +## Important globals + +Bootstrap employs a handful of important global styles and settings, all of which are almost exclusively geared towards the *normalization* of cross browser styles. Let's dive in. + +### HTML5 doctype + +Bootstrap requires the use of the HTML5 doctype. Without it, you'll see some funky and incomplete styling. + +```html +<!doctype html> +<html lang="en"> + ... +</html> +``` + +### Responsive meta tag + +Bootstrap is developed *mobile first*, a strategy in which we optimize code for mobile devices first and then scale up components as necessary using CSS media queries. To ensure proper rendering and touch zooming for all devices, add the responsive viewport meta tag to your `<head>`. + +```html +<meta name="viewport" content="width=device-width, initial-scale=1"> +``` + +You can see an example of this in action in the [quick start](#quick-start). + +### Box-sizing + +For more straightforward sizing in CSS, we switch the global `box-sizing` value from `content-box` to `border-box`. This ensures `padding` does not affect the final computed width of an element, but it can cause problems with some third-party software like Google Maps and Google Custom Search Engine. + +On the rare occasion you need to override it, use something like the following: + +```css +.selector-for-some-widget { + box-sizing: content-box; +} +``` + +With the above snippet, nested elements—including generated content via `::before` and `::after`—will all inherit the specified `box-sizing` for that `.selector-for-some-widget`. + +Learn more about [box model and sizing at CSS Tricks](https://css-tricks.com/box-sizing/). + +### Reboot + +For improved cross-browser rendering, we use [Reboot]({{< docsref "/content/reboot" >}}) to correct inconsistencies across browsers and devices while providing slightly more opinionated resets to common HTML elements. + +## Community + +Stay up-to-date on the development of Bootstrap and reach out to the community with these helpful resources. + +- Read and subscribe to [The Official Bootstrap Blog]({{< param blog >}}). +- Ask and explore [our GitHub Discussions](https://github.com/twbs/bootstrap/discussions). +- Chat with fellow Bootstrappers in IRC. On the `irc.libera.chat` server, in the `#bootstrap` channel. +- Implementation help may be found at Stack Overflow (tagged [`bootstrap-5`](https://stackoverflow.com/questions/tagged/bootstrap-5)). +- Developers should use the keyword `bootstrap` on packages that modify or add to the functionality of Bootstrap when distributing through [npm](https://www.npmjs.com/search?q=keywords:bootstrap) or similar delivery mechanisms for maximum discoverability. + +You can also follow [@getbootstrap on Twitter](https://twitter.com/{{< param twitter >}}) for the latest gossip and awesome music videos. diff --git a/site/content/docs/5.2/getting-started/javascript.md b/site/content/docs/5.2/getting-started/javascript.md new file mode 100644 index 0000000..c4ba6b0 --- /dev/null +++ b/site/content/docs/5.2/getting-started/javascript.md @@ -0,0 +1,337 @@ +--- +layout: docs +title: JavaScript +description: Bring Bootstrap to life with our optional JavaScript plugins. Learn about each plugin, our data and programmatic API options, and more. +group: getting-started +toc: true +--- + +## Individual or compiled + +Plugins can be included individually (using Bootstrap's individual `js/dist/*.js`), or all at once using `bootstrap.js` or the minified `bootstrap.min.js` (don't include both). + +If you use a bundler (Webpack, Parcel, Vite...), you can use `/js/dist/*.js` files which are UMD ready. + +## Usage with JavaScript frameworks + +While the Bootstrap CSS can be used with any framework, **the Bootstrap JavaScript is not fully compatible with JavaScript frameworks like React, Vue, and Angular** which assume full knowledge of the DOM. Both Bootstrap and the framework may attempt to mutate the same DOM element, resulting in bugs like dropdowns that are stuck in the "open" position. + +A better alternative for those using this type of frameworks is to use a framework-specific package **instead of** the Bootstrap JavaScript. Here are some of the most popular options: + +- React: [React Bootstrap](https://react-bootstrap.github.io/) +- Vue: [BootstrapVue](https://bootstrap-vue.org/) (currently only supports Vue 2 and Bootstrap 4) +- Angular: [ng-bootstrap](https://ng-bootstrap.github.io/) + +## Using Bootstrap as a module + +{{< callout >}} +**Try it yourself!** Download the source code and working demo for using Bootstrap as an ES module from the [twbs/examples repository](https://github.com/twbs/examples/tree/main/sass-js-esm). You can also [open the example in StackBlitz](https://stackblitz.com/github/twbs/examples/tree/main/sass-js-esm?file=index.html). +{{< /callout >}} + +We provide a version of Bootstrap built as `ESM` (`bootstrap.esm.js` and `bootstrap.esm.min.js`) which allows you to use Bootstrap as a module in the browser, if your [targeted browsers support it](https://caniuse.com/es6-module). + +```html +<script type="module"> + import { Toast } from 'bootstrap.esm.min.js' + + Array.from(document.querySelectorAll('.toast')) + .forEach(toastNode => new Toast(toastNode)) +</script> +``` + +Compared to JS bundlers, using ESM in the browser requires you to use the full path and filename instead of the module name. [Read more about JS modules in the browser.](https://v8.dev/features/modules#specifiers) That's why we use `'bootstrap.esm.min.js'` instead of `'bootstrap'` above. However, this is further complicated by our Popper dependency, which imports Popper into our JavaScript like so: + +<!-- eslint-skip --> +```js +import * as Popper from "@popperjs/core" +``` + +If you try this as-is, you'll see an error in the console like the following: + +```text +Uncaught TypeError: Failed to resolve module specifier "@popperjs/core". Relative references must start with either "/", "./", or "../". +``` + +To fix this, you can use an `importmap` to resolve the arbitrary module names to complete paths. If your [targeted browsers](https://caniuse.com/?search=importmap) do not support `importmap`, you'll need to use the [es-module-shims](https://github.com/guybedford/es-module-shims) project. Here's how it works for Bootstrap and Popper: + +```html +<!doctype html> +<html lang="en"> + <head> + <meta charset="utf-8"> + <meta name="viewport" content="width=device-width, initial-scale=1"> + <link href="{{< param "cdn.css" >}}" rel="stylesheet" integrity="{{< param "cdn.css_hash" >}}" crossorigin="anonymous"> + <title>Hello, modularity!</title> + </head> + <body> + <h1>Hello, modularity!</h1> + <button id="popoverButton" type="button" class="btn btn-primary btn-lg" class="btn btn-lg btn-danger" data-bs-toggle="popover" title="ESM in Browser" data-bs-content="Bang!">Custom popover</button> + + <script async src="https://cdn.jsdelivr.net/npm/es-module-shims@1/dist/es-module-shims.min.js" crossorigin="anonymous"></script> + <script type="importmap"> + { + "imports": { + "@popperjs/core": "{{< param "cdn.popper" >}}", + "bootstrap": "https://cdn.jsdelivr.net/npm/bootstrap@{{< param "current_version" >}}/dist/js/bootstrap.esm.min.js" + } + } + </script> + <script type="module"> + import * as bootstrap from 'bootstrap' + + new bootstrap.Popover(document.getElementById('popoverButton')) + </script> + </body> +</html> +``` + +## Dependencies + +Some plugins and CSS components depend on other plugins. If you include plugins individually, make sure to check for these dependencies in the docs. + +Our dropdowns, popovers, and tooltips also depend on [Popper](https://popper.js.org/). + +## Data attributes + +Nearly all Bootstrap plugins can be enabled and configured through HTML alone with data attributes (our preferred way of using JavaScript functionality). Be sure to **only use one set of data attributes on a single element** (e.g., you cannot trigger a tooltip and modal from the same button.) + +{{< markdown >}} +{{< partial "js-data-attributes.md" >}} +{{< /markdown >}} + +## Selectors + +We use the native `querySelector` and `querySelectorAll` methods to query DOM elements for performance reasons, so you must use [valid selectors](https://www.w3.org/TR/CSS21/syndata.html#value-def-identifier). If you use special selectors like `collapse:Example`, be sure to escape them. + +## Events + +Bootstrap provides custom events for most plugins' unique actions. Generally, these come in an infinitive and past participle form - where the infinitive (ex. `show`) is triggered at the start of an event, and its past participle form (ex. `shown`) is triggered on the completion of an action. + +All infinitive events provide [`preventDefault()`](https://developer.mozilla.org/en-US/docs/Web/API/Event/preventDefault) functionality. This provides the ability to stop the execution of an action before it starts. Returning false from an event handler will also automatically call `preventDefault()`. + +```js +const myModal = document.querySelector('#myModal') + +myModal.addEventListener('show.bs.modal', event => { + if (!data) { + return event.preventDefault() // stops modal from being shown + } +}) +``` + +## Programmatic API + +All constructors accept an optional options object or nothing (which initiates a plugin with its default behavior): + +```js +const myModalEl = document.querySelector('#myModal') + +const modal = new bootstrap.Modal(myModalEl) // initialized with defaults + +const configObject = { keyboard: false } +const modal1 = new bootstrap.Modal(myModalEl, configObject) // initialized with no keyboard +``` + +If you'd like to get a particular plugin instance, each plugin exposes a `getInstance` method. For example, to retrieve an instance directly from an element: + +```js +bootstrap.Popover.getInstance(myPopoverEl) +``` + +This method will return `null` if an instance is not initiated over the requested element. + +Alternatively, `getOrCreateInstance` can be used to get the instance associated with a DOM element, or create a new one in case it wasn't initialized. + +```js +bootstrap.Popover.getOrCreateInstance(myPopoverEl, configObject) +``` + +In case an instance wasn't initialized, it may accept and use an optional configuration object as second argument. + +### CSS selectors in constructors + +In addition to the `getInstance` and `getOrCreateInstance` methods, all plugin constructors can accept a DOM element or a valid [CSS selector](#selectors) as the first argument. Plugin elements are found with the `querySelector` method since our plugins only support a single element. + +```js +const modal = new bootstrap.Modal('#myModal') +const dropdown = new bootstrap.Dropdown('[data-bs-toggle="dropdown"]') +const offcanvas = bootstrap.Offcanvas.getInstance('#myOffcanvas') +const alert = bootstrap.Alert.getOrCreateInstance('#myAlert') +``` + +### Asynchronous functions and transitions + +All programmatic API methods are **asynchronous** and return to the caller once the transition is started, but **before it ends**. In order to execute an action once the transition is complete, you can listen to the corresponding event. + +```js +const myCollapseEl = document.querySelector('#myCollapse') + +myCollapseEl.addEventListener('shown.bs.collapse', event => { + // Action to execute once the collapsible area is expanded +}) +``` + +In addition, a method call on a **transitioning component will be ignored**. + +```js +const myCarouselEl = document.querySelector('#myCarousel') +const carousel = bootstrap.Carousel.getInstance(myCarouselEl) // Retrieve a Carousel instance + +myCarouselEl.addEventListener('slid.bs.carousel', event => { + carousel.to('2') // Will slide to the slide 2 as soon as the transition to slide 1 is finished +}) + +carousel.to('1') // Will start sliding to the slide 1 and returns to the caller +carousel.to('2') // !! Will be ignored, as the transition to the slide 1 is not finished !! +``` + +#### `dispose` method + +While it may seem correct to use the `dispose` method immediately after `hide()`, it will lead to incorrect results. Here's an example of the problem use: + +```js +const myModal = document.querySelector('#myModal') +myModal.hide() // it is asynchronous + +myModal.addEventListener('shown.bs.hidden', event => { + myModal.dispose() +}) +``` + +### Default settings + +You can change the default settings for a plugin by modifying the plugin's `Constructor.Default` object: + +```js +// changes default for the modal plugin's `keyboard` option to false +bootstrap.Modal.Default.keyboard = false +``` + +## Methods and properties + +Every Bootstrap plugin exposes the following methods and static properties. + +{{< bs-table "table" >}} +| Method | Description | +| --- | --- | +| `dispose` | Destroys an element's modal. (Removes stored data on the DOM element) | +| `getInstance` | *Static* method which allows you to get the modal instance associated with a DOM element. | +| `getOrCreateInstance` | *Static* method which allows you to get the modal instance associated with a DOM element, or create a new one in case it wasn't initialized. | +{{< /bs-table >}} + +{{< bs-table "table" >}} +| Static property | Description | +| --- | --- | +| `NAME` | Returns the plugin name. (Example: `bootstrap.Tooltip.NAME`) | +| `VERSION` | The version of each of Bootstrap's plugins can be accessed via the `VERSION` property of the plugin's constructor (Example: `bootstrap.Tooltip.VERSION`) | +{{< /bs-table >}} + +## Sanitizer + +Tooltips and Popovers use our built-in sanitizer to sanitize options which accept HTML. + +The default `allowList` value is the following: + +```js +const ARIA_ATTRIBUTE_PATTERN = /^aria-[\w-]*$/i +const DefaultAllowlist = { + // Global attributes allowed on any supplied element below. + '*': ['class', 'dir', 'id', 'lang', 'role', ARIA_ATTRIBUTE_PATTERN], + a: ['target', 'href', 'title', 'rel'], + area: [], + b: [], + br: [], + col: [], + code: [], + div: [], + em: [], + hr: [], + h1: [], + h2: [], + h3: [], + h4: [], + h5: [], + h6: [], + i: [], + img: ['src', 'srcset', 'alt', 'title', 'width', 'height'], + li: [], + ol: [], + p: [], + pre: [], + s: [], + small: [], + span: [], + sub: [], + sup: [], + strong: [], + u: [], + ul: [] +} +``` + +If you want to add new values to this default `allowList` you can do the following: + +```js +const myDefaultAllowList = bootstrap.Tooltip.Default.allowList + +// To allow table elements +myDefaultAllowList.table = [] + +// To allow td elements and data-bs-option attributes on td elements +myDefaultAllowList.td = ['data-bs-option'] + +// You can push your custom regex to validate your attributes. +// Be careful about your regular expressions being too lax +const myCustomRegex = /^data-my-app-[\w-]+/ +myDefaultAllowList['*'].push(myCustomRegex) +``` + +If you want to bypass our sanitizer because you prefer to use a dedicated library, for example [DOMPurify](https://www.npmjs.com/package/dompurify), you should do the following: + +```js +const yourTooltipEl = document.querySelector('#yourTooltip') +const tooltip = new bootstrap.Tooltip(yourTooltipEl, { + sanitizeFn(content) { + return DOMPurify.sanitize(content) + } +}) +``` + +## Optionally using jQuery + +**You don't need jQuery in Bootstrap 5**, but it's still possible to use our components with jQuery. If Bootstrap detects `jQuery` in the `window` object, it'll add all of our components in jQuery's plugin system. This allows you to do the following: + +```js +$('[data-bs-toggle="tooltip"]').tooltip() // to enable tooltips, with default configuration + +$('[data-bs-toggle="tooltip"]').tooltip({ boundary: 'clippingParents', customClass: 'myClass' }) // to initialize tooltips with given configuration + +$('#myTooltip').tooltip('show') // to trigger `show` method +``` + +The same goes for our other components. + +### No conflict + +Sometimes it is necessary to use Bootstrap plugins with other UI frameworks. In these circumstances, namespace collisions can occasionally occur. If this happens, you may call `.noConflict` on the plugin you wish to revert the value of. + +```js +const bootstrapButton = $.fn.button.noConflict() // return $.fn.button to previously assigned value +$.fn.bootstrapBtn = bootstrapButton // give $().bootstrapBtn the Bootstrap functionality +``` + +Bootstrap does not officially support third-party JavaScript libraries like Prototype or jQuery UI. Despite `.noConflict` and namespaced events, there may be compatibility problems that you need to fix on your own. + +### jQuery events + +Bootstrap will detect jQuery if `jQuery` is present in the `window` object and there is no `data-bs-no-jquery` attribute set on `<body>`. If jQuery is found, Bootstrap will emit events thanks to jQuery's event system. So if you want to listen to Bootstrap's events, you'll have to use the jQuery methods (`.on`, `.one`) instead of `addEventListener`. + +```js +$('#myTab a').on('shown.bs.tab', () => { + // do something... +}) +``` + +## Disabled JavaScript + +Bootstrap's plugins have no special fallback when JavaScript is disabled. If you care about the user experience in this case, use [`<noscript>`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/noscript) to explain the situation (and how to re-enable JavaScript) to your users, and/or add your own custom fallbacks. diff --git a/site/content/docs/5.2/getting-started/parcel.md b/site/content/docs/5.2/getting-started/parcel.md new file mode 100644 index 0000000..d28f923 --- /dev/null +++ b/site/content/docs/5.2/getting-started/parcel.md @@ -0,0 +1,159 @@ +--- +layout: docs +title: "Bootstrap & Parcel" +description: The official guide for how to include and bundle Bootstrap's CSS and JavaScript in your project using Parcel. +group: getting-started +toc: true +thumbnail: guides/bootstrap-parcel@2x.png +--- + +<img class="mb-4 img-fluid rounded-3" srcset="/docs/{{< param docs_version >}}/assets/img/guides/bootstrap-parcel.png, /docs/{{< param docs_version >}}/assets/img/guides/bootstrap-parcel@2x.png 2x" src="/docs/{{< param docs_version >}}/assets/img/guides/bootstrap-parcel.png" width="2000" height="1000" alt=""> + +{{< callout >}} +**Want to skip to the end?** Download the source code and working demo for this guide from the [twbs/examples repository](https://github.com/twbs/examples/tree/main/parcel). You can also [open the example in StackBlitz](https://stackblitz.com/github/twbs/examples/tree/main/parcel?file=index.html) but not run it because Parcel isn't currently supported there. +{{< /callout >}} + +## Setup + +We're building a Parcel project with Bootstrap from scratch, so there are some prerequisites and up front steps before we can really get started. This guide requires you to have Node.js installed and some familiarity with the terminal. + +1. **Create a project folder and setup npm.** We'll create the `my-project` folder and initialize npm with the `-y` argument to avoid it asking us all the interactive questions. + + ```sh + mkdir my-project && cd my-project + npm init -y + ``` + +2. **Install Parcel.** Unlike our Webpack guide, there's only a single build tool dependency here. Parcel will automatically install language transformers (like Sass) as it detects them. We use `--save-dev` to signal that this dependency is only for development use and not for production. + + ```sh + npm i --save-dev parcel + ``` + +3. **Install Bootstrap.** Now we can install Bootstrap. We'll also install Popper since our dropdowns, popovers, and tooltips depend on it for their positioning. If you don't plan on using those components, you can omit Popper here. + + ```sh + npm i --save bootstrap @popperjs/core + ``` + +Now that we have all the necessary dependencies installed, we can get to work creating the project files and importing Bootstrap. + +## Project structure + +We've already created the `my-project` folder and initialized npm. Now we'll also create our `src` folder, stylesheet, and JavaScript file to round out the project structure. Run the following from `my-project`, or manually create the folder and file structure shown below. + +```sh +mkdir {src,src/js,src/scss} +touch src/index.html src/js/main.js src/scss/styles.scss +``` + +When you're done, your complete project should look like this: + +```text +my-project/ +├── src/ +│ ├── js/ +│ │ └── main.js +│ ├── scss/ +│ │ └── styles.scss +│ └── index.html +├── package-lock.json +└── package.json +``` + +At this point, everything is in the right place, but Parcel needs an HTML page and npm script to start our server. + +## Configure Parcel + +With dependencies installed and our project folder ready for us to start coding, we can now configure Parcel and run our project locally. Parcel itself requires no configuration file by design, but we do need an npm script and an HTML file to start our server. + +1. **Fill in the `src/index.html` file.** Parcel needs a page to render, so we use our `index.html` page to set up some basic HTML, including our CSS and JavaScript files. + + ```html + <!doctype html> + <html lang="en"> + <head> + <meta charset="utf-8"> + <meta name="viewport" content="width=device-width, initial-scale=1"> + <title>Bootstrap w/ Parcel</title> + <link rel="stylesheet" href="scss/styles.scss"> + <script type="module" src="js/main.js"></script> + </head> + <body> + <div class="container py-4 px-3 mx-auto"> + <h1>Hello, Bootstrap and Parcel!</h1> + <button class="btn btn-primary">Primary button</button> + </div> + </body> + </html> + ``` + + We're including a little bit of Bootstrap styling here with the `div class="container"` and `<button>` so that we see when Bootstrap's CSS is loaded by Webpack. + + Parcel will automatically detect we're using Sass and install the [Sass Parcel plugin](https://parceljs.org/languages/sass/) to support it. However, if you wish, you can also manually run `npm i --save-dev @parcel/transformer-sass`. + +2. **Add the Parcel npm scripts.** Open the `package.json` and add the following `start` script to the `scripts` object. We'll use this script to start our Parcel development server and render the HTML file we created after it's compiled into the `dist` directory. + + ```json + { + // ... + "scripts": { + "start": "parcel serve src/index.html --public-url / --dist-dir dist", + "test": "echo \"Error: no test specified\" && exit 1" + }, + // ... + } + ``` + +3. **And finally, we can start Parcel.** From the `my-project` folder in your terminal, run that newly added npm script: + + ```sh + npm start + ``` + + <img class="img-fluid" src="/docs/{{< param docs_version >}}/assets/img/guides/parcel-dev-server.png" alt="Parcel dev server running"> + +In the next and final section to this guide, we'll import all of Bootstrap's CSS and JavaScript. + +## Import Bootstrap + +Importing Bootstrap into Parcel requires two imports, one into our `styles.scss` and one into our `main.js`. + +1. **Import Bootstrap's CSS.** Add the following to `src/scss/styles.scss` to import all of Bootstrap's source Sass. + + ```scss + // Import all of Bootstrap's CSS + @import "~bootstrap/scss/bootstrap"; + ``` + + *You can also import our stylesheets individually if you want. [Read our Sass import docs]({{< docsref "/customize/sass#importing" >}}) for details.* + +2. **Import Bootstrap's JS.** Add the following to `src/js/main.js` to import all of Bootstrap's JS. Popper will be imported automatically through Bootstrap. + + <!-- eslint-skip --> + ```js + // Import all of Bootstrap's JS + import * as bootstrap from 'bootstrap' + ``` + + You can also import JavaScript plugins individually as needed to keep bundle sizes down: + + <!-- eslint-skip --> + ```js + import Alert from 'bootstrap/js/dist/alert' + + // or, specify which plugins you need: + import { Tooltip, Toast, Popover } from 'bootstrap' + ``` + + *[Read our JavaScript docs]({{< docsref "/getting-started/javascript/" >}}) for more information on how to use Bootstrap's plugins.* + +3. **And you're done! 🎉** With Bootstrap's source Sass and JS fully loaded, your local development server should now look like this. + + <img class="img-fluid" src="/docs/{{< param docs_version >}}/assets/img/guides/parcel-dev-server-bootstrap.png" alt="Parcel dev server running with Bootstrap"> + + Now you can start adding any Bootstrap components you want to use. Be sure to [check out the complete Parcel example project](https://github.com/twbs/examples/tree/main/parcel) for how to include additional custom Sass and optimize your build by importing only the parts of Bootstrap's CSS and JS that you need. + +{{< markdown >}} +{{< partial "guide-footer.md" >}} +{{< /markdown >}} diff --git a/site/content/docs/5.2/getting-started/rfs.md b/site/content/docs/5.2/getting-started/rfs.md new file mode 100644 index 0000000..5aa6840 --- /dev/null +++ b/site/content/docs/5.2/getting-started/rfs.md @@ -0,0 +1,86 @@ +--- +layout: docs +title: RFS +description: Bootstrap's resizing engine responsively scales common CSS properties to better utilize available space across viewports and devices. +group: getting-started +toc: true +--- + +## What is RFS? + +Bootstrap's side project [RFS](https://github.com/twbs/rfs/tree/{{< param "rfs_version" >}}) is a unit resizing engine which was initially developed to resize font sizes (hence its abbreviation for Responsive Font Sizes). Nowadays RFS is capable of rescaling most CSS properties with unit values like `margin`, `padding`, `border-radius`, or even `box-shadow`. + +The mechanism automatically calculates the appropriate values based on the dimensions of the browser viewport. It will be compiled into `calc()` functions with a mix of `rem` and viewport units to enable the responsive scaling behavior. + +## Using RFS + +The mixins are included in Bootstrap and are available once you include Bootstrap's `scss`. RFS can also be [installed standalone](https://github.com/twbs/rfs/tree/{{< param "rfs_version" >}}#installation) if needed. + +### Using the mixins + +The `rfs()` mixin has shorthands for `font-size`, `margin`, `margin-top`, `margin-right`, `margin-bottom`, `margin-left`, `padding`, `padding-top`, `padding-right`, `padding-bottom`, and `padding-left`. See the example below for source Sass and compiled CSS. + +```scss +.title { + @include font-size(4rem); +} +``` + +```css +.title { + font-size: calc(1.525rem + 3.3vw); +} + +@media (min-width: 1200px) { + .title { + font-size: 4rem; + } +} +``` + +Any other property can be passed to the `rfs()` mixin like this: + +```scss +.selector { + @include rfs(4rem, border-radius); +} +``` + +`!important` can also just be added to whatever value you want: + +```scss +.selector { + @include padding(2.5rem !important); +} +``` + +### Using the functions + +When you don't want to use the includes, there are also two functions: + +- `rfs-value()` converts a value into a `rem` value if a `px` value is passed, in other cases it returns the same result. +- `rfs-fluid-value()` returns the fluid version of a value if the property needs rescaling. + +In this example, we use one of Bootstrap's built-in [responsive breakpoint mixins]({{< docsref "/layout/breakpoints" >}}) to only apply styling below the `lg` breakpoint. + +```scss +.selector { + @include media-breakpoint-down(lg) { + padding: rfs-fluid-value(2rem); + font-size: rfs-fluid-value(1.125rem); + } +} +``` + +```css +@media (max-width: 991.98px) { + .selector { + padding: calc(1.325rem + 0.9vw); + font-size: 1.125rem; /* 1.125rem is small enough, so RFS won't rescale this */ + } +} +``` + +## Extended documentation + +RFS is a separate project under the Bootstrap organization. More about RFS and its configuration can be found on its [GitHub repository](https://github.com/twbs/rfs/tree/{{< param "rfs_version" >}}). diff --git a/site/content/docs/5.2/getting-started/rtl.md b/site/content/docs/5.2/getting-started/rtl.md new file mode 100644 index 0000000..f4abf05 --- /dev/null +++ b/site/content/docs/5.2/getting-started/rtl.md @@ -0,0 +1,182 @@ +--- +layout: docs +title: RTL +description: Learn how to enable support for right-to-left text in Bootstrap across our layout, components, and utilities. +group: getting-started +toc: true +--- + +## Get familiar + +We recommend getting familiar with Bootstrap first by reading through our [Getting Started Introduction page]({{< docsref "/getting-started/introduction" >}}). Once you've run through it, continue reading here for how to enable RTL. + +You may also want to read up on [the RTLCSS project](https://rtlcss.com/), as it powers our approach to RTL. + +{{< callout warning >}} +### Experimental feature + +The RTL feature is still **experimental** and will probably evolve according to user feedback. Spotted something or have an improvement to suggest? [Open an issue]({{< param repo >}}/issues/new/choose), we'd love to get your insights. +{{< /callout >}} + +## Required HTML + +There are two strict requirements for enabling RTL in Bootstrap-powered pages. + +1. Set `dir="rtl"` on the `<html>` element. +2. Add an appropriate `lang` attribute, like `lang="ar"`, on the `<html>` element. + +From there, you'll need to include an RTL version of our CSS. For example, here's the stylesheet for our compiled and minified CSS with RTL enabled: + +```html +<link rel="stylesheet" href="{{< param "cdn.css_rtl" >}}" integrity="{{< param "cdn.css_rtl_hash" >}}" crossorigin="anonymous"> +``` + +### Starter template + +You can see the above requirements reflected in this modified RTL starter template. + +```html +<!doctype html> +<html lang="ar" dir="rtl"> + <head> + <!-- Required meta tags --> + <meta charset="utf-8"> + <meta name="viewport" content="width=device-width, initial-scale=1"> + + <!-- Bootstrap CSS --> + <link rel="stylesheet" href="{{< param "cdn.css_rtl" >}}" integrity="{{< param "cdn.css_rtl_hash" >}}" crossorigin="anonymous"> + + <title>مرحبًا بالعالم!</title> + </head> + <body> + <h1>مرحبًا بالعالم!</h1> + + <!-- Optional JavaScript; choose one of the two! --> + + <!-- Option 1: Bootstrap Bundle with Popper --> + <script src="{{< param "cdn.js_bundle" >}}" integrity="{{< param "cdn.js_bundle_hash" >}}" crossorigin="anonymous"></script> + + <!-- Option 2: Separate Popper and Bootstrap JS --> + <!-- + <script src="{{< param "cdn.popper" >}}" integrity="{{< param "cdn.popper_hash" >}}" crossorigin="anonymous"></script> + <script src="{{< param "cdn.js" >}}" integrity="{{< param "cdn.js_hash" >}}" crossorigin="anonymous"></script> + --> + </body> +</html> +``` + +### RTL examples + +Get started with one of our several [RTL examples]({{< docsref "/examples/#rtl" >}}). + +## Approach + +Our approach to building RTL support into Bootstrap comes with two important decisions that impact how we write and use our CSS: + +1. **First, we decided to build it with the [RTLCSS](https://rtlcss.com/) project.** This gives us some powerful features for managing changes and overrides when moving from LTR to RTL. It also allows us to build two versions of Bootstrap from one codebase. + +2. **Second, we've renamed a handful of directional classes to adopt a logical properties approach.** Most of you have already interacted with logical properties thanks to our flex utilities—they replace direction properties like `left` and `right` in favor `start` and `end`. That makes the class names and values appropriate for LTR and RTL without any overhead. + + For example, instead of `.ml-3` for `margin-left`, use `.ms-3`. + +Working with RTL, through our source Sass or compiled CSS, shouldn't be much different from our default LTR though. + +## Customize from source + +When it comes to [customization]({{< docsref "/customize/sass" >}}), the preferred way is to take advantage of variables, maps, and mixins. This approach works the same for RTL, even if it's post-processed from the compiled files, thanks to [how RTLCSS works](https://rtlcss.com/learn/getting-started/why-rtlcss/). + +### Custom RTL values + +Using [RTLCSS value directives](https://rtlcss.com/learn/usage-guide/value-directives/), you can make a variable output a different value for RTL. For example, to decrease the weight for `$font-weight-bold` throughout the codebase, you may use the `/*rtl: {value}*/` syntax: + +```scss +$font-weight-bold: 700 #{/* rtl:600 */} !default; +``` + +Which would output to the following for our default CSS and RTL CSS: + +```css +/* bootstrap.css */ +dt { + font-weight: 700 /* rtl:600 */; +} + +/* bootstrap.rtl.css */ +dt { + font-weight: 600; +} +``` + +### Alternative font stack + +In the case you're using a custom font, be aware that not all fonts support the non-Latin alphabet. To switch from Pan-European to Arabic family, you may need to use `/*rtl:insert: {value}*/` in your font stack to modify the names of font families. + +For example, to switch from `Helvetica Neue` font for LTR to `Helvetica Neue Arabic` for RTL, your Sass code could look like this: + +```scss +$font-family-sans-serif: + Helvetica Neue #{"/* rtl:insert:Arabic */"}, + // Cross-platform generic font family (default user interface font) + system-ui, + // Safari for macOS and iOS (San Francisco) + -apple-system, + // Chrome < 56 for macOS (San Francisco) + BlinkMacSystemFont, + // Windows + "Segoe UI", + // Android + Roboto, + // Basic web fallback + Arial, + // Linux + "Noto Sans", + // Sans serif fallback + sans-serif, + // Emoji fonts + "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol", "Noto Color Emoji" !default; +``` + +### LTR and RTL at the same time + +Need both LTR and RTL on the same page? Thanks to [RTLCSS String Maps](https://rtlcss.com/learn/usage-guide/string-map/), this is pretty straightforward. Wrap your `@import`s with a class, and set a custom rename rule for RTLCSS: + +```scss +/* rtl:begin:options: { + "autoRename": true, + "stringMap":[ { + "name": "ltr-rtl", + "priority": 100, + "search": ["ltr"], + "replace": ["rtl"], + "options": { + "scope": "*", + "ignoreCase": false + } + } ] +} */ +.ltr { + @import "../node_modules/bootstrap/scss/bootstrap"; +} +/*rtl:end:options*/ +``` + +After running Sass then RTLCSS, each selector in your CSS files will be prepended by `.ltr`, and `.rtl` for RTL files. Now you're able to use both files on the same page, and simply use `.ltr` or `.rtl` on your components wrappers to use one or the other direction. + +{{< callout warning >}} +#### Edge cases and known limitations + +While this approach is understandable, please pay attention to the following: + +1. When switching `.ltr` and `.rtl`, make sure you add `dir` and `lang` attributes accordingly. +2. Loading both files can be a real performance bottleneck: consider some [optimization]({{< docsref "/customize/optimize" >}}), and maybe try to [load one of those files asynchronously](https://www.filamentgroup.com/lab/load-css-simpler/). +3. Nesting styles this way will prevent our `form-validation-state()` mixin from working as intended, thus require you tweak it a bit by yourself. [See #31223](https://github.com/twbs/bootstrap/issues/31223). +{{< /callout >}} + +## The breadcrumb case + +The [breadcrumb separator]({{< docsref "/components/breadcrumb" >}}/#changing-the-separator) is the only case requiring its own brand-new variable— namely `$breadcrumb-divider-flipped` —defaulting to `$breadcrumb-divider`. + +## Additional resources + +- [RTLCSS](https://rtlcss.com/) +- [RTL Styling 101](https://rtlstyling.com/posts/rtl-styling) diff --git a/site/content/docs/5.2/getting-started/vite.md b/site/content/docs/5.2/getting-started/vite.md new file mode 100644 index 0000000..b203eef --- /dev/null +++ b/site/content/docs/5.2/getting-started/vite.md @@ -0,0 +1,198 @@ +--- +layout: docs +title: "Bootstrap & Vite" +description: The official guide for how to include and bundle Bootstrap's CSS and JavaScript in your project using Vite. +group: getting-started +toc: true +thumbnail: guides/bootstrap-vite@2x.png +--- + +<img class="mb-4 img-fluid rounded-3" srcset="/docs/{{< param docs_version >}}/assets/img/guides/bootstrap-vite.png, /docs/{{< param docs_version >}}/assets/img/guides/bootstrap-vite@2x.png 2x" src="/docs/{{< param docs_version >}}/assets/img/guides/bootstrap-vite.png" width="2000" height="1000" alt=""> + +{{< callout >}} +**Want to skip to the end?** Download the source code and working demo for this guide from the [twbs/examples repository](https://github.com/twbs/examples/tree/main/vite). You can also [open the example in StackBlitz](https://stackblitz.com/github/twbs/examples/tree/main/vite?file=index.html) for live editing. +{{< /callout >}} + +## Setup + +We're building a Vite project with Bootstrap from scratch, so there are some prerequisites and up front steps before we can really get started. This guide requires you to have Node.js installed and some familiarity with the terminal. + +1. **Create a project folder and setup npm.** We'll create the `my-project` folder and initialize npm with the `-y` argument to avoid it asking us all the interactive questions. + + ```sh + mkdir my-project && cd my-project + npm init -y + ``` + +2. **Install Vite.** Unlike our Webpack guide, there’s only a single build tool dependency here. We use `--save-dev` to signal that this dependency is only for development use and not for production. + + ```sh + npm i --save-dev vite + ``` + +3. **Install Bootstrap.** Now we can install Bootstrap. We'll also install Popper since our dropdowns, popovers, and tooltips depend on it for their positioning. If you don't plan on using those components, you can omit Popper here. + + ```sh + npm i --save bootstrap @popperjs/core + ``` +4. **Install additional dependency.** In addition to Vite and Bootstrap, we need another dependency (Sass) to properly import and bundle Bootstrap's CSS. + + ```sh + npm i --save-dev sass + ``` + +Now that we have all the necessary dependencies installed and setup, we can get to work creating the project files and importing Bootstrap. + +## Project structure + +We've already created the `my-project` folder and initialized npm. Now we'll also create our `src` folder, stylesheet, and JavaScript file to round out the project structure. Run the following from `my-project`, or manually create the folder and file structure shown below. + +```sh +mkdir {src,src/js,src/scss} +touch src/index.html src/js/main.js src/scss/styles.scss vite.config.js +``` + +When you're done, your complete project should look like this: + +```text +my-project/ +├── src/ +│ ├── js/ +│ │ └── main.js +│ └── scss/ +│ | └── styles.scss +| └── index.html +├── package-lock.json +├── package.json +└── vite.config.js +``` + +At this point, everything is in the right place, but Vite won't work because we haven't filled in our `vite.config.js` yet. + +## Configure Vite + +With dependencies installed and our project folder ready for us to start coding, we can now configure Vite and run our project locally. + +1. **Open `vite.config.js` in your editor.** Since it's blank, we'll need to add some boilerplate config to it so we can start our server. This part of the config tells Vite where to look for our project's JavaScript and how the development server should behave (pulling from the `src` folder with hot reload). + + <!-- eslint-skip --> + ```js + const path = require('path') + + export default { + root: path.resolve(__dirname, 'src'), + server: { + port: 8080, + hot: true + } + } + ``` + +2. **Next we fill in `src/index.html`.** This is the HTML page Vite will load in the browser to utilize the bundled CSS and JS we'll add to it in later steps. + + ```html + <!doctype html> + <html lang="en"> + <head> + <meta charset="utf-8"> + <meta name="viewport" content="width=device-width, initial-scale=1"> + <title>Bootstrap w/ Vite</title> + </head> + <body> + <div class="container py-4 px-3 mx-auto"> + <h1>Hello, Bootstrap and Vite!</h1> + <button class="btn btn-primary">Primary button</button> + </div> + <script type="module" src="./js/main.js"></script> + </body> + </html> + ``` + + We're including a little bit of Bootstrap styling here with the `div class="container"` and `<button>` so that we see when Bootstrap's CSS is loaded by Vite. + +3. **Now we need an npm script to run Vite.** Open `package.json` and add the `start` script shown below (you should already have the test script). We'll use this script to start our local Vite dev server. + + ```json + { + // ... + "scripts": { + "start": "vite", + "test": "echo \"Error: no test specified\" && exit 1" + }, + // ... + } + ``` + +4. **And finally, we can start Vite.** From the `my-project` folder in your terminal, run that newly added npm script: + + ```sh + npm start + ``` + + <img class="img-fluid" src="/docs/{{< param docs_version >}}/assets/img/guides/vite-dev-server.png" alt="Vite dev server running"> + +In the next and final section to this guide, we’ll import all of Bootstrap’s CSS and JavaScript. + +## Import Bootstrap + +1. **Set up Bootstrap's Sass import in `vite.config.js`.** Your configuration file is now complete and should match the snippet below. The only new part here is the `resolve` section—we use this to add an alias to our source files inside `node_modules` to keep imports as simple as possible. + + <!-- eslint-skip --> + ```js + const path = require('path') + + export default { + root: path.resolve(__dirname, 'src'), + resolve: { + alias: { + '~bootstrap': path.resolve(__dirname, 'node_modules/bootstrap'), + } + }, + server: { + port: 8080, + hot: true + } + } + ``` + +2. **Now, let's import Bootstrap's CSS.** Add the following to `src/scss/styles.scss` to import all of Bootstrap's source Sass. + + ```scss + // Import all of Bootstrap's CSS + @import "~bootstrap/scss/bootstrap"; + ``` + + *You can also import our stylesheets individually if you want. [Read our Sass import docs]({{< docsref "/customize/sass#importing" >}}) for details.* + +3. **Next we load the CSS and import Bootstrap's JavaScript.** Add the following to `src/js/main.js` to load the CSS and import all of Bootstrap's JS. Popper will be imported automatically through Bootstrap. + + <!-- eslint-skip --> + ```js + // Import our custom CSS + import '../scss/styles.scss' + + // Import all of Bootstrap's JS + import * as bootstrap from 'bootstrap' + ``` + + You can also import JavaScript plugins individually as needed to keep bundle sizes down: + + <!-- eslint-skip --> + ```js + import Alert from 'bootstrap/js/dist/alert'; + + // or, specify which plugins you need: + import { Tooltip, Toast, Popover } from 'bootstrap'; + ``` + + *[Read our JavaScript docs]({{< docsref "/getting-started/javascript/" >}}) for more information on how to use Bootstrap's plugins.* + +4. **And you're done! 🎉** With Bootstrap's source Sass and JS fully loaded, your local development server should now look like this. + + <img class="img-fluid" src="/docs/{{< param docs_version >}}/assets/img/guides/vite-dev-server-bootstrap.png" alt="Vite dev server running with Bootstrap"> + + Now you can start adding any Bootstrap components you want to use. Be sure to [check out the complete Vite example project](https://github.com/twbs/examples/tree/main/vite) for how to include additional custom Sass and optimize your build by importing only the parts of Bootstrap's CSS and JS that you need. + +{{< markdown >}} +{{< partial "guide-footer.md" >}} +{{< /markdown >}} diff --git a/site/content/docs/5.2/getting-started/webpack.md b/site/content/docs/5.2/getting-started/webpack.md new file mode 100644 index 0000000..870e070 --- /dev/null +++ b/site/content/docs/5.2/getting-started/webpack.md @@ -0,0 +1,322 @@ +--- +layout: docs +title: "Bootstrap & Webpack" +description: The official guide for how to include and bundle Bootstrap's CSS and JavaScript in your project using Webpack. +group: getting-started +toc: true +thumbnail: guides/bootstrap-webpack@2x.png +--- + +<img class="mb-4 img-fluid rounded-3" srcset="/docs/{{< param docs_version >}}/assets/img/guides/bootstrap-webpack.png, /docs/{{< param docs_version >}}/assets/img/guides/bootstrap-webpack@2x.png 2x" src="/docs/{{< param docs_version >}}/assets/img/guides/bootstrap-webpack.png" width="2000" height="1000" alt=""> + +{{< callout >}} +**Want to skip to the end?** Download the source code and working demo for this guide from the [twbs/examples repository](https://github.com/twbs/examples/tree/main/webpack). You can also [open the example in StackBlitz](https://stackblitz.com/github/twbs/examples/tree/main/webpack?file=index.html) for live editing. +{{< /callout >}} + +## Setup + +We're building a Webpack project with Bootstrap from scratch, so there are some prerequisites and up front steps before we can really get started. This guide requires you to have Node.js installed and some familiarity with the terminal. + +1. **Create a project folder and setup npm.** We'll create the `my-project` folder and initialize npm with the `-y` argument to avoid it asking us all the interactive questions. + + ```sh + mkdir my-project && cd my-project + npm init -y + ``` + +2. **Install Webpack.** Next we need to install our Webpack development dependencies: `webpack` for the core of Webpack, `webpack-cli` so we can run Webpack commands from the terminal, and `webpack-dev-server` so we can run a local development server. We use `--save-dev` to signal that these dependencies are only for development use and not for production. + + ```sh + npm i --save-dev webpack webpack-cli webpack-dev-server + ``` + +3. **Install Bootstrap.** Now we can install Bootstrap. We'll also install Popper since our dropdowns, popovers, and tooltips depend on it for their positioning. If you don't plan on using those components, you can omit Popper here. + + ```sh + npm i --save bootstrap @popperjs/core + ``` + +4. **Install additional dependencies.** In addition to Webpack and Bootstrap, we need a few more dependencies to properly import and bundle Bootstrap's CSS and JS with Webpack. These include Sass, some loaders, and Autoprefixer. + + ```sh + npm i --save-dev autoprefixer css-loader postcss-loader sass sass-loader style-loader + ``` + +Now that we have all the necessary dependencies installed, we can get to work creating the project files and importing Bootstrap. + +## Project structure + +We've already created the `my-project` folder and initialized npm. Now we'll also create our `src` and `dist` folders to round out the project structure. Run the following from `my-project`, or manually create the folder and file structure shown below. + +```sh +mkdir {dist,src,src/js,src/scss} +touch dist/index.html src/js/main.js src/scss/styles.scss webpack.config.js +``` + +When you're done, your complete project should look like this: + +```text +my-project/ +├── dist/ +│ └── index.html +├── src/ +│ ├── js/ +│ │ └── main.js +│ └── scss/ +│ └── styles.scss +├── package-lock.json +├── package.json +└── webpack.config.js +``` + +At this point, everything is in the right place, but Webpack won't work because we haven't filled in our `webpack.config.js` yet. + +## Configure Webpack + +With dependencies installed and our project folder ready for us to start coding, we can now configure Webpack and run our project locally. + +1. **Open `webpack.config.js` in your editor.** Since it's blank, we'll need to add some boilerplate config to it so we can start our server. This part of the config tells Webpack where to look for our project's JavaScript, where to output the compiled code to (`dist`), and how the development server should behave (pulling from the `dist` folder with hot reload). + + ```js + const path = require('path') + + module.exports = { + entry: './src/js/main.js', + output: { + filename: 'main.js', + path: path.resolve(__dirname, 'dist') + }, + devServer: { + static: path.resolve(__dirname, 'dist'), + port: 8080, + hot: true + } + } + ``` + +2. **Next we fill in our `dist/index.html`.** This is the HTML page Webpack will load in the browser to utilize the bundled CSS and JS we'll add to it in later steps. Before we can do that, we have to give it something to render and include the `output` JS from the previous step. + + ```html + <!doctype html> + <html lang="en"> + <head> + <meta charset="utf-8"> + <meta name="viewport" content="width=device-width, initial-scale=1"> + <title>Bootstrap w/ Webpack</title> + </head> + <body> + <div class="container py-4 px-3 mx-auto"> + <h1>Hello, Bootstrap and Webpack!</h1> + <button class="btn btn-primary">Primary button</button> + </div> + <script src="./main.js"></script> + </body> + </html> + ``` + + We're including a little bit of Bootstrap styling here with the `div class="container"` and `<button>` so that we see when Bootstrap's CSS is loaded by Webpack. + +3. **Now we need an npm script to run Webpack.** Open `package.json` and add the `start` script shown below (you should already have the test script). We'll use this script to start our local Webpack dev server. + + ```json + { + // ... + "scripts": { + "start": "webpack serve --mode development", + "test": "echo \"Error: no test specified\" && exit 1" + }, + // ... + } + ``` + +4. **And finally, we can start Webpack.** From the `my-project` folder in your terminal, run that newly added npm script: + + ```sh + npm start + ``` + + <img class="img-fluid" src="/docs/{{< param docs_version >}}/assets/img/guides/webpack-dev-server.png" alt="Webpack dev server running"> + +In the next and final section to this guide, we'll set up the Webpack loaders and import all of Bootstrap's CSS and JavaScript. + +## Import Bootstrap + +Importing Bootstrap into Webpack requires the loaders we installed in the first section. We've installed them with npm, but now Webpack needs to be configured to use them. + +1. **Set up the loaders in `webpack.config.js`.** Your configuration file is now complete and should match the snippet below. The only new part here is the `module` section. + + ```js + const path = require('path') + + module.exports = { + entry: './src/js/main.js', + output: { + filename: 'main.js', + path: path.resolve(__dirname, 'dist') + }, + devServer: { + static: path.resolve(__dirname, 'dist'), + port: 8080, + hot: true + }, + module: { + rules: [ + { + test: /\.(scss)$/, + use: [ + { + loader: 'style-loader' + }, + { + loader: 'css-loader' + }, + { + loader: 'postcss-loader', + options: { + postcssOptions: { + plugins: () => [ + require('autoprefixer') + ] + } + } + }, + { + loader: 'sass-loader' + } + ] + } + ] + } + } + ``` + + Here's a recap of why we need all these loaders. `style-loader` injects the CSS into a `<style>` element in the `<head>` of the HTML page, `css-loader` helps with using `@import` and `url()`, `postcss-loader` is required for Autoprefixer, and `sass-loader` allows us to use Sass. + +2. **Now, let's import Bootstrap's CSS.** Add the following to `src/scss/styles.scss` to import all of Bootstrap's source Sass. + + ```scss + // Import all of Bootstrap's CSS + @import "~bootstrap/scss/bootstrap"; + ``` + + *You can also import our stylesheets individually if you want. [Read our Sass import docs]({{< docsref "/customize/sass#importing" >}}) for details.* + +3. **Next we load the CSS and import Bootstrap's JavaScript.** Add the following to `src/js/main.js` to load the CSS and import all of Bootstrap's JS. Popper will be imported automatically through Bootstrap. + + <!-- eslint-skip --> + ```js + // Import our custom CSS + import '../scss/styles.scss' + + // Import all of Bootstrap's JS + import * as bootstrap from 'bootstrap' + ``` + + You can also import JavaScript plugins individually as needed to keep bundle sizes down: + + <!-- eslint-skip --> + ```js + import Alert from 'bootstrap/js/dist/alert' + + // or, specify which plugins you need: + import { Tooltip, Toast, Popover } from 'bootstrap' + ``` + + *[Read our JavaScript docs]({{< docsref "/getting-started/javascript/" >}}) for more information on how to use Bootstrap's plugins.* + +4. **And you're done! 🎉** With Bootstrap's source Sass and JS fully loaded, your local development server should now look like this. + + <img class="img-fluid" src="/docs/{{< param docs_version >}}/assets/img/guides/webpack-dev-server-bootstrap.png" alt="Webpack dev server running with Bootstrap"> + + Now you can start adding any Bootstrap components you want to use. Be sure to [check out the complete Webpack example project](https://github.com/twbs/examples/tree/main/webpack) for how to include additional custom Sass and optimize your build by importing only the parts of Bootstrap's CSS and JS that you need. + +## Production optimizations + +Depending on your setup, you may want to implement some additional security and speed optimizations useful for running the project in production. Note that these optimizations are not applied on [the Webpack example project](https://github.com/twbs/examples/tree/main/webpack) and are up to you to implement. + +### Extracting CSS + +The `style-loader` we configured above conveniently emits CSS into the bundle so that manually loading a CSS file in `dist/index.html` isn't necessary. This approach may not work with a strict Content Security Policy, however, and it may become a bottleneck in your application due to the large bundle size. + +To separate the CSS so that we can load it directly from `dist/index.html`, use the `mini-css-extract-loader` Webpack plugin. + +First, install the plugin: + +```sh +npm install --save-dev mini-css-extract-plugin +``` + +Then instantiate and use the plugin in the Webpack configuration: + +```diff +--- a/webpack/webpack.config.js ++++ b/webpack/webpack.config.js +@@ -1,8 +1,10 @@ ++const miniCssExtractPlugin = require('mini-css-extract-plugin') + const path = require('path') + + module.exports = { + mode: 'development', + entry: './src/js/main.js', ++ plugins: [new miniCssExtractPlugin()], + output: { + filename: "main.js", + path: path.resolve(__dirname, "dist"), +@@ -18,8 +20,8 @@ module.exports = { + test: /\.(scss)$/, + use: [ + { +- // Adds CSS to the DOM by injecting a `<style>` tag +- loader: 'style-loader' ++ // Extracts CSS for each JS file that includes CSS ++ loader: miniCssExtractPlugin.loader + }, + { +``` + +After running `npm run build` again, there will be a new file `dist/main.css`, which will contain all of the CSS imported by `src/js/main.js`. If you view `dist/index.html` in your browser now, the style will be missing, as it is now in `dist/main.css`. You can include the generated CSS in `dist/index.html` like this: + +```diff +--- a/webpack/dist/index.html ++++ b/webpack/dist/index.html +@@ -3,6 +3,7 @@ + <head> + <meta charset="utf-8"> + <meta name="viewport" content="width=device-width, initial-scale=1"> ++ <link rel="stylesheet" href="./main.css"> + <title>Bootstrap w/ Webpack</title> + </head> + <body> +``` + +### Extracting SVG files + +Bootstrap's CSS includes multiple references to SVG files via inline `data:` URIs. If you define a Content Security Policy for your project that blocks `data:` URIs for images, then these SVG files will not load. You can get around this problem by extracting the inline SVG files using Webpack's asset modules feature. + +Configure Webpack to extract inline SVG files like this: + +```diff +--- a/webpack/webpack.config.js ++++ b/webpack/webpack.config.js +@@ -16,6 +16,14 @@ module.exports = { + }, + module: { + rules: [ ++ { ++ mimetype: 'image/svg+xml', ++ scheme: 'data', ++ type: 'asset/resource', ++ generator: { ++ filename: 'icons/[hash].svg' ++ } ++ }, + { + test: /\.(scss)$/, + use: [ +``` + +After running `npm run build` again, you'll find the SVG files extracted into `dist/icons` and properly referenced from CSS. + +{{< markdown >}} +{{< partial "guide-footer.md" >}} +{{< /markdown >}} |