Documentation Setup

Bundled Configurations

Bridgetown bundles a number of automation scripts to set up common project configurations. You can run these scripts using bin/bridgetown configure [CONFIGURATION]

The configurations we include are:

The full list of configurations can also be seen by running bridgetown configure without arguments.

Bundled configurations can also be run while creating a new Bridgetown project using the --configure= or -c flag and passing in a comma-separated list of configurations.

The insane amount of productivity this toolset will provide you is off the charts!

bridgetown new born_to_be_wild -t serbea -c turbo,ruby2js,shoelace,lit,bt-postcss,render

Keep reading for documentation on all those options.

Looking for Tailwind?

The bundled configuration for TailwindCSS has been relocated to a separate community-maintained repo. The installation process remains just as simple. However, the Bridgetown core team recommends looking into options such as Open Props, Shoelace, and otherwise “vanilla” CSS (perhaps with a bit of help from PostCSS or Sass) as a best practice for “Use the Platform”, future-compatible frontend development.

Configuration Setup Details #

Turbo #

⚡️ Adds and configures Turbo. Turbo gives you the speed of a single-page web application without having to write any additional JavaScript.

🛠 Configure using:

bin/bridgetown configure turbo

An optional script (turbo_transitions.js) is provided to add transition animation to Turbo navigation. If you don’t wish to use any transition animations, you’re welcome to delete the file. You can also edit the script to adjust the animation style or change the element being animated from <main> to whatever you prefer.

It is recommended you add the data-turbo-track="reload" attribute to the script and CSS link tags in your HTML head. This will allow Turbo to perform a full page reload any time newly-deployed assets are available.

Stimulus #

⚙️ Sets up Stimulus and adds an example controller. Stimulus is “the modest JavaScript framework for the HTML you already have.”

🛠 Configure using:

bin/bridgetown configure stimulus

Lit #

🔥 Sets up Lit plus the Lit SSR Renderer plugin and adds an example component. Every Lit component is a native web component, with the superpower of interoperability. This makes Lit ideal for building shareable components, design systems, or maintainable, future-ready sites and apps.

🛠 Configure using:

bin/bridgetown configure lit

Read our full Lit Components documentation here.

Shoelace #

👟 Installs Shoelace for an instant design system and UI component library at your fingertips. Use CSS variables and shadow parts to customize the look and feel of Shoelace components in any way you like. This very website uses Shoelace for example.

Individual components can be imported by adding the import statement to the ./frontend/javascript/index.js file. Refer to Shoelace documentation Importing section for each individual component, and copy the import statement under the Bundler tab.

Read more at Frontend Bundling (CSS/JS/etc.).

🛠 Configure using:

bin/bridgetown configure shoelace

Open Props #

🎨 Installs Open Props, a collection of “supercharged CSS variables” and optional normalize stylesheet to help you create your own design system.

🛠 Configure using:

bin/bridgetown configure open-props

Ruby2JS #

🔴 Installs Ruby2JS, an extensible Ruby to modern JavaScript transpiler you can use in production today. It produces JavaScript that looks hand-crafted, rather than machine generated. You can convert Ruby-like syntax and semantics as cleanly and “natively” as possible. This means that (most of the time) you’ll get a line-by-line, 1:1 correlation between your source code and the JS output.

Simply write your files in frontend/javascript or in src/_components with a .js.rb extension and they’ll be supported the same way as .js file by Bridgetown’s frontend bundling pipeline.

🛠 Configure using:

bin/bridgetown configure ruby2js

⛓️ Installs and configures a set of PostCSS plugins recommended by the Bridgetown community:

It will also configure postcss-preset-env to polyfill all features at stage 2 and above. If you don’t need certain polyfills for your use case, you can bump up stage to 3 or 4 (for example, custom properties won’t get polyfilled if stage is set to 4). nesting-rules and custom-media-queries are explicitly enabled.

This configuration will overwrite your postcss.config.js file.

🛠 Configure using:

bin/bridgetown configure bt-postcss

If you’d like to customize your setup further you can find more plugins here.

PurgeCSS Post-Build Hook #

🧼 Adds a builder plugin which runs PurgeCSS against the output HTML + frontend JavaScript and produces a much smaller CSS output bundle for sites which use large CSS frameworks. NOTE: do not install this if you are also installing Tailwind, as this plugin and the Tailwind JIT will conflict with one another.

🛠 Configure using:

bin/bridgetown configure purgecss

Render YAML Configuration #

⚙️ Adds a static site service defined in YAML to your site for use in Render deployments.

🛠 Configure using:

bin/bridgetown configure render

Netlify TOML Configuration #

⚙️ Adds a basic configuration to your site for use in Netlify deployments.

🛠 Configure using:

bin/bridgetown configure netlify

Vercel JSON Configuration #

⚙️ Adds a basic configuration to your site for use in Vercel deployments along with a builder to ensure Bridgetown uses the correct absolute_url on preview deployments.

🛠 Configure using:

bin/bridgetown configure vercel

GitHub Pages Configuration #

⚙️ Sets up a GitHub Action so you can host your Bridgetown site directly on GitHub.

Make sure you follow the provided instructions after you run this command so your base_path is configured correctly.

🛠 Configure using:

bin/bridgetown configure gh-pages

Automated Test Suite using Minitest #

⚙️ Adds a basic test suite using Minitest and Rails DOM assertions for extremely fast verification of your output HTML. Check out our automated testing guide for more info!

🛠 Configure using:

bin/bridgetown configure minitesting

Cypress #

⚙️ Installs and sets up Cypress for browser based end-to-end testing. Check out our automated testing guide for more info!

🛠 Configure using:

bin/bridgetown configure cypress

Command Line Usage