Frontend Bundling (CSS/JS/etc.)

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

By default Bridgetown uses Sass, a pre-processor for CSS; but you can pass --use-postcss to bridgetown new to setup PostCSS which is popular with the Webpack community.

Sass

The starting place for CSS code lives at frontend/styles/index.scss.

Importing common CSS frameworks such as Bootstrap, Foundation, Bulma 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.

PostCSS

You can run bridgetown new mysite --use-postcss to configure your site with PostCSS right out-of-the-box.

The default PostCSS config is largely empty so you can set it up as per your preference. The only two plugins included by default are postcss-flexbugs-fixes and postcss-preset-env.

If you’d like to use Sass with PostCSS, you’ll need to install a plugin for it:

$ yarn add @csstools/postcss-sass

And then include it at the top of the plugins object in postcss.config.js:

module.exports = {  
  plugins: {
    '@csstools/postcss-sass': {},
    'postcss-flexbugs-fixes': {},
    'postcss-preset-env': {
      autoprefixer: {
        flexbox: 'no-2009'
      },
      stage: 3
    }
  }
}

The popular TailwindCSS framework can be added to your project by following their setup guide for PostCSS.

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>

Next: Choose Your Engine