Bridgetown comes with a default configuration of Webpack to handle building and exporting frontend assets such as Javascript/Typescript/etc., CSS/Sass/etc., and related files that are imported through Webpack (fonts, icons, etc.)
Files to be processed by Webpack are placed in the top-level frontend folder within your site root. This folder is entirely separate from the Bridgetown source folder where your content, templates, plugins, etc. live. However, using relative paths you can reference files from Webpack that live in the source folder (so you could keep CSS partials alongside Liquid templates, for example).
Bridgetown uses Yarn to install and manage frontend NPM-based packages and dependencies. Gem-based plugins can instruct Bridgetown to add a related NPM package whenever Bridgetown first loads the gem.
Javascript
The starting place for Javascript code lives at ./frontend/javascript/index.js. Here you can write your custom functionality, use import statements to pull in other modules or external packages, and so forth. This is also where you’d import all relevant CSS. (By default it imports ./frontend/styles/index.scss.)
Because Bridgetown utilizes standard Webpack functionality, you can trick out your Javascript setup with additional language enhancements like Typescript or add well-known frameworks like LitElement, Stimulus, Alpine, React, Vue, and many others. For example, to add slick page transitions to your website using Swup, you would simply run:
yarn add swup
And then update ./frontend/javascript/index.js with:
import Swup from "swup"
const swup = new Swup()
And the update your HTML layout according to the Swup install guide.
CSS
The starting place for CSS code lives at ./frontend/styles/index.scss. By default Bridgetown uses Sass, a pre-processor for CSS, but you can customize your Webpack config to change that to use standard PostCSS which is popular with the Webpack community.
Importing common CSS frameworks such as Bootstrap, Foundation, Bulma, Tailwind, and so forth is often as easy as running:
$ yarn add name-of-css-framework
And then adding:
@import "~css-framework/css-framework";
to index.scss. For example, to add Bulma which is a modern CSS-only (no Javascript) framework built around Flexbox, you’d simply run:
$ yarn add bulma
and then add:
@import "~bulma/bulma";
to index.scss.
Linking to the Output Bundles
Bridgetown’s default Webpack configuration is set up to place all compiled output into the _bridgetown folder in your output folder. Bridgetown knows when it regenerates a website not to touch anything in _bridgetown as that comes solely from Webpack. It is recommended you do not use the site source folder to add anything to _bridgetown as that will not get cleaned and updated by Bridgetown’s generation process across multiple builds.
To reference the compiled JS and CSS files from Webpack in your site template, simply add the webpack_path Liquid tag to your HTML <head>:
<link rel="stylesheet" href="{% webpack_path css %}" />
<script src="{% webpack_path js %}" defer></script>
This will automatically produce HTML tags that look something like this:
<link rel="stylesheet" href="/_bridgetown/static/css/all.6902d0bf80a552c79eaa.css"/>
<script src="/_bridgetown/static/js/all.a1286aad43064359dbc8.js" defer></script>