Bridgetown

Bridgetown 2.1 Has Come to Town! Happy Holidays 🥳

2025-12-24T08:22:54-08:00

You better watch out (I’m telling you why): the latest release of our merry little Ruby framework is coming to town! Yes indeed, Bridgetown 2.1 “Festive River City” is here, with a marquee feature enabling you to load in wiki-style content & “digital gardens” managed by external applications, and a slew of other improvements. And you’d better believe we’re ready for the imminent Christmas release of Ruby 4.0!

You can read more about the release details here in our initial beta post, and there are a couple additional details we need to mention:

We now have a brand-new Matrix chat room! Embrace open protocols and chat with fellow Bridgetowners on Matrix. (We recommend you install Element X for iOS & Android so you can access Matrix via mobile platforms.)
We fully embrace Bridgetown projects configured to bundle gems from alternative community servers like gem.coop as well as our own canonical gems.bridgetownrb.com server. Read the details here.

Read the 2.1 release notes here. To upgrade, make sure you’re running at least Ruby 3.2 and Node 22, then modify your Gemfile:

gem "bridgetown", "~> 2.1.0"
gem "bridgetown-routes", "~> 2.1.0" # if applicable

and run bundle update. Upgrade instructions here. Or you can run gem install bridgetown -N -v 2.1.0 and then create a new site.

And of course we continue to push for awareness of “indie web” and sustainable alternatives to Big Tech solutions. Our documentation now includes information on how to deploy static Bridgetown sites to statichost.eu, and our Automations feature can load automation scripts from Codeberg and GitLab repositories in addition to GitHub.

If you run into any issues trying out Bridgetown 2.1, please hop into our community channels and let us know how we can help. We welcome your feedback and ideas! In addition, you can follow us on Bluesky and the fediverse to stay current on the latest news.

Happy Holidays! See y’all in the New Year! 🎉 🎆

Let’s Get Festive! ’Tis the Season to Be Jolly with Bridgetown 2.1 Beta 1

2025-12-03T11:18:55-08:00

A mere three months after the release of Bridgetown 2.0 and we’re already onto 2.1?! What can I say…when you’re on a roll, you’re on a roll. And things are definitely rolling here in Bridgetown as we celebrate our “Festive River City 🥳” (we just couldn’t part ways with the River City branding just yet, hence our “Snow Leopard” style code name!).

With the end-of-year holidays upon us, we’re excited to be presenting several exciting new features and yet more under-the-hood refactoring & infrastructure work which sets us up well for future feature development in 2026. While there are possibly some breaking changes in 2.1 (which is why we opted for a beta cycle), we hope to mitigate those as much as possible or offer clear instructions on how to correct swiftly. Your feedback during the beta is most appreciated!

Read the release notes here. To test your sites with the 2.1 beta, modify your Gemfile:

gem "bridgetown", "~> 2.1.0.beta1"
gem "bridgetown-routes", "~> 2.1.0.beta1" # if applicable

and run bundle update. Or you can run gem install bridgetown -N -v 2.1.0.beta1 to create a new site.

External Content Sources (Markdown Apps, Digital Gardens, Wikis, etc.)

Have you ever thought to yourself: “Self, wouldn’t it be awesome if I could just point Bridgetown at a folder full of Markdown files and it would just render??”

Your wish is our command. ✨

In Bridgetown 2.1, you can now add one or more “external content” sources via an initializer which can be literally any folder on the filesystem, even the parent folder! Yes, Bridgetown now supports “folder inversion” as an alternative installation approach, which means in addition to placing Markdown files and related assets in src, you can write Markdown in the folder above where Bridgetown is installed (and in various subfolders thereof). Not only that, but front matter is completely optional! This is perfect for “digital gardens”, wikis, and other file-based content systems managed by third-party Markdown apps such as Obsidian. (And you’d better believe we have a whole bunch of wiki-themed improvements in mind for future releases.) 😎 Read our docs for more information.

Universal Rendering for Partials & Components

A limitation of how our rendering system worked for partials in the past was that you could only use partials within the same template engine. So if you were writing an ERB template, you couldn’t use a Serbea partial. Or if you were in a Serbea template, you couldn’t use a pure Ruby (.rb) partial.

That has now been fixed! Any template engine can render any partial whether ERB, Serbea, or pure Ruby. On top of that, you can now render both partials & components to strings from any context (not just within a template)—including the console! Read our docs for more information.

Speaking of the console, you now have access to the Rack::Test DSL (if the gem is installed, which happenes automatically if you use the minitesting bundled configuration). This is great for testing both static & dynamic routes directly within the REPL.

Samovar, Freyia, and Custom Commands

In Bridgetown 2.1, we’ve migrated away from using Thor for our command-line interface (CLI) and are now using Samovar, created by Samuel Williams. It provides a straightforward, modern, and elegant way to write commands, and as a bonus, we’ve made it much easier for you to extend Bridgetown’s CLI with your own commands in any project! Just create a config/custom_commands.rb file and add your own Bridgetown::Command subclasses. We believe in most cases this is a more powerful & flexible solution than authoring new Rake tasks. Read our docs for more information.

Note that for the 2.1 release cycle, we have provided a Thor “shim” so existing sites and plugins which provide Thor commands should continue to work as before. In a future release, we will be removing the shim so please update your commands accordingly. In the meantime, if you run into any compatibility issues with the shim please report them and let us know!

Another of our prior uses of Thor was for the Automations functionality (which also powers our Bundled Configurations). Because this functionality is so important, and also near-impossible to replicate verbatim using an alternative library, we have extracted the “actions” & “shell” portions of Thor as a hard fork out to a new gem called Freyia. We will be actively developing Freyia as its own independent project going forward, refactoring and adding new features as needed.

Removal of Active Support

As part of our pledge to ensure Bridgetown is free of dependencies directly managed by 37signals, we have finialized the removal of the Active Support gem. If you have written your own code which assumes the availability of Active Support, you may need to bundle add activesupport and require pieces of it yourself. For example, if you want to use .blank?, .present?, etc., add the gem and include the following in your config/initializers.rb file:

require "active_support/core_ext/object/blank"

Documentation on Active Support is available here.

Supporting Alternatives to Big Tech

We continue to push for awareness of “indie web” and sustainable alternatives to Big Tech solutions. Our documentation now includes information on how to deploy static Bridgetown sites to statichost.eu, and our Automations feature can load automation scripts from Codeberg and GitLab repositories in addition to GitHub.

As always if you run into any issues trying out Bridgetown 2.1, please hop into our community channels and let us know how we can help. We welcome your feedback and ideas! In addition, you can follow us on Bluesky and the fediverse to stay current on the latest news.

Welcome Our Newest Core Team Member: Felipe Vogel

2025-10-08T00:00:00-07:00

We’ve very excited to announce that Felipe Vogel has joined the Bridgetown Core Team! Felipe is a developer based in Lexington, Kentucky, and originally hails from Brazil. He has been an enthusiastic user of Bridgetown for a long time now. In fact…

…When Felipe was first learning Ruby, Bridgetown was the first Ruby web framework that he picked up. Eventually he got into Rails and other tools as well, but that’s quite an amazing story. Here are a few other fun facts about Felipe from his website:

“I used to be a humanities teacher in a former career that took me all the way to West Africa.”
“I grew up in Brazil in southern Amazonia, at times living with the Jarawara indigenous people, in a village that you can see on Google Maps.”
“I’m a big Latin nerd. In grad school I took most of my classes in Latin and lived in the unofficial domus Latina (Latin house), where we spoke only Latin except when we had guests… which, as you might guess, was rare 😂”

You’ll start to see Felipe a bit more in our Discord chat, taking a peek at new PRs, and in other community endeavors. You can also find Felipe in the fediverse: @fpsvogel@ruby.social. We’re glad to have Felipe aboard the USSG Bridgetown! 🫡

Good Times in River City: Bridgetown 2.0 is Here!

2025-09-16T09:01:23-07:00

Graphic Design by Adrian Valenzuela

Introducing the only Ruby web framework which bridges the gap between static Markdown sites and fullstack database-driven application deployments: Bridgetown 2.0 “River City” has been released! 🎉 This version has long been in the hopper, and it’s chock full of major quality-of-life improvements (check out the release notes!). Start your first Bridgetown site with our installation guide, or upgrade your site by bumping the version in your Gemfile:

gem "bridgetown", "~> 2.0"
gem "bridgetown-routes", "~> 2.0" # if applicable

and running bundle update. More upgrade details here, including switching from Yarn to NPM and from CommonJS to ESM for a modern, streamlined frontend build system. If you run into any issues, hop in our Discord chat and let us know how we can help you!

A huge thank you to our many contributors! 🎉 ayushn21, KonnorRogers, michaelherold, erickguan, MaxLap, jeremyevans, brainbuz, akarzim, surrim, mlitwiniuk, jaredcwhite, and everyone who submitted bug reports and feedback. We couldn’t have done this without you!

Also, if you’re brand-new to the Bridgetown 2.0 release cycle, read our Road to Bridgetown 2.0 series here.

Now without further ado, let’s talk about all the new features in Bridgetown v2 “River City”.

New Defaults

When you create a new Bridgetown site, you will now get ERB templates installed automatically (rather than the previous default of Liquid). We believe this is much more ergonomic for Ruby developers, but if you work with designers who are more familiar with Liquid, that is still officially supported. (For existing sites based on Liquid, add template_engine :liquid to your config/initializers.rb file or template_engine: liquid to bridgetown.config.yml.)

Bridgetown now requires a minimum version of Ruby 3.1.4 and Node 20.6. This unlocks a variety of syntax improvements both for our internal Ruby APIs and the Ruby code you write in your projects. And with the Node upgrade, we can now switch our esbuild config from the older CommonJS syntax (aka require) to modern ESM (aka import) which is the industry standard and much more expected for frontend JavaScript developers. In addition, Yarn is no longer required as a JS package manager—you can switch to using NPM directly which is a far better tool now than it once was. Or if you prefer, pnpm which is also supported! (Just make sure you update the :frontend tasks in your project’s Rakefile to use your preferred package manager.)

New sites will default to including just the newer Ruby initializers configuration (config/initializers.rb), but the legacy YAML config (bridgetown.config.yml) is still supported and may still be required for certain plugins.

Finally, webpack is no longer supported. Bridgetown is all in on esbuild as the “last frontend bundler you’ll ever need”. Make sure you search-and-replace webpack_path to asset_path in your templates!

Fast Refresh

You know how frustrating it is when you fix a simple typo on a large site and then you have to wait 20 seconds for a rebuild? Well I don’t, because I’ve been rocking the betas for months! 😂 But in all seriousness, this is a fantastic new feature in Bridgetown 2.0, based on a pair of techniques called signals and effects to track changes to individuals files and the ways in which data can flow across multiple files.

In not all, but in most cases, this results in a much faster rebuild time. If you edit just a single resource file, it’s likely only that one resource will get rebuilt. Using the new site.signals API, you can edit data files and only the pages loading in that data will get rebuilt. Fast refresh also tracks access to components within templates. Read our original announcement blog post for a deep dive into this functionality.

Superior Roda Integration

Bridgetown provides a full SSR pipeline built on top of the Roda web toolkit. You can handle form data or JSON payloads with ease, or power up our dynamic, file-based routing with all of Bridgetown’s template engines and component rendering at your disposal.

This was all true prior to 2.0, but what’s new is we’ve added a lot more smarts to Roda for building object-oriented backend APIs out of modular building blocks. You can keep the Roda routing tree lean-and-mean and rely on “controller” and “view” style objects for a familiar pattern to fullstack application development. Want to access a database like PostgreSQL? Our new bridgetown_sequel plugin is the answer you seek.

Check out our Roda reference guide as well as our updated Routes guide to get up to speed.

Streamlined

This is a new library installed with Bridgetown for embedding HTML templates in pure Ruby code using “squiggly heredocs” along with a set of helpers to ensure output safety (proper escaping) and easier interplay between HTML markup and Ruby code. And it’s fast: roughly 50% faster than ERB!

You can use Streamlined directly in resources saved as pure Ruby (.rb), as well as in Bridgetown components. Here’s an example of what that looks like:

class SectionComponent < Bridgetown::Component
  def initialize(variant:, heading:, **options)
    @variant, @heading, @options = variant, heading, options
  end

  def heading
    <<~HTML
      <h3>#{text -> { @heading }}</h3>
    HTML
  end

  def template
    html -> { <<~HTML
      <section #{html_attributes(variant:, **@options)}>
        #{html -> { heading }}
        <section-body>
          #{html -> { content }}
        </section-body>
      </section>
    HTML
    }
  end
end

You may still prefer to author HTML in a “markup first” manner with embedded Ruby, rather than Ruby with embedded HTML (and sometimes I do), but for components with complex interpolations, Streamlined is a win. Read the new documentation here.

Foundation Gem

In Bridgetown 2.0, we have started an ongoing process of reducing our reliance on the Active Support gem (in the hopes we can eventually remove it as a dependency). The Foundation gem marks our effort in this department, and not only that but we’ll be increasingly migrating other useful utility-like Ruby features there from internal Bridgetown APIs so that they’re more decoupled and easily accessible to non-Bridgetown Ruby applications. Foundation gem docs are available here.

Ecosystem Update (Hello Codeberg!)

We’ve had a goal in mind to embark on a major revamp of our Plugins directory as well as offer a program to help new plugin authors get started and eventually featured in official Bridgetown marketing. While those ideas were brewing, a huge shakeup has started in the open source community. Due to Microsoft’s major “vibe shift” with how it stewards GitHub—essentially embarking on a “pivot to AI” and folding the company into its own AI & cloud departments, many open source developers are looking elsewhere for a true libre alternative. (It’s odd when you stop and think about it that a proprietary, closed-source platform would be the defacto home for open source projects!)

The destination folks are heading for more and more is Codeberg, a European organization which runs a forge built on top of the fully open source Forgejo software (itself a fork of Gitea). Codeberg has really seemed to reach escape velocity this year, and I (Jared) have already migrated a number of projects there, including several low-level Bridgetown dependencies.

We don’t feel comfortable with the idea of relocating the Bridgetown monorepo itself at this time, out of concern that it will be cumbersome for existing and potential contributors. But the Bridgetown core team is committed to keeping a close watch on how this movement unfolds. One of the most exiting future developments will be federation, the idea that multiple forges run by individuals and organizations alike could all communicate with each other, sharing issues and PRs as if it were all a single platform (just like Mastodon instances!). We believe this will be a seismic event in the evolution of code forges and signal the beginning of the end of GitHub’s dominance in the open source community. As they say, stay tuned.

Et Cetera and So Forth

There’s much more in the release notes showing a large number of bug fixes and refactors for performance and DX, and while software is of course never “done”, we are extremely proud of the Bridgetown 2.0 release and consider its full feature set to be the culmination of several years of effort. It’s likely we’ll continue to chip away at the margins of smaller fixes and enhancements for a long while yet in the v2 era, but the bottom line is that Bridgetown is a mature and stable foundation on which to build the next generation of static sites and modest web applications, always with HTML-first and “vanilla web” principles in mind.

If you run into any issues trying out Bridgetown 2.0, please hop into our community channels and let us know how we can help. We welcome your feedback and ideas! In addition, you can follow us now on Bluesky as well as in the fediverse to stay current on the latest news.

Bridgetown, the Hybrid Ruby Web Framework, Turns Five Today

2025-04-02T16:18:11-07:00

Happy Birthday Bridgetown! Five years ago today, a project was born to create a new kind of web framework—certainly one unlike any previously seen in the Ruby community. (More on that in a moment.) I will confess, I’m as astonished as anyone we’re still going strong five years later!

This time last year I reminisced quite a bit and also looked forward to all-systems-go development of Bridgetown 2.0, and today we are preparing what might be the last beta of the 2.0 cycle before its final release.

But beyond a fist pump in the air and a dash of nostalgia, I’d like to reflect on the astonishing truth that Bridgetown is, well, still the only game in (our) town. I included in the title of this post “the Hybrid Ruby Web Framework” because that’s our not-so-secret sauce that for some reason continues to escape notice for a lot of people.

Bridgetown isn’t just a static site generator. Bridgetown isn’t just a dynamic application server. It’s both. And as time passes, the lines between those two worlds—pre-built and built-on-demand—will blur, and we’ll continue to press forward on solutions which allow your static pages to refresh portions of the page on-demand with live content. We’re super-thrilled with the amount of progress we’ve made on polishing our server architecture, as well as some companion projects simmering on the back burner to make interactive feature development feel unlike anything you’ve experienced in Ruby.

At the same time, we see Bridgetown as playing a significant role in elevating the exposure of Ruby web frameworks in general past a certain train-themed option some people think is the only Ruby framework available. There’s a lot of educational work to be done to show that Ruby has range and we can forge new paths. Along those lines, we want to show how Bridgetown can be used alongside other frameworks, most notably Hanami. While Bridgetown is itself a complete framework, there’s no reason you couldn’t use Hanami for your application server code and Bridgetown for a static portion such as a company blog. Could those live side-by-side in the same repo, perhaps even sharing some common assets? Stay tuned.

Anyway, back to work on getting v2.0 out the door. Once again, thank you to all who support this project and contribute to make it better. Excelsior!

Countdown to Production! Bridgetown 2.0 Beta 4 is Here

2025-01-16T00:00:00-08:00

The Bridgetown progressive web framework is racing to the 2.0 finish line. While we don’t have a specific process for offering “release candidates”, we consider this Beta 4 release to be essentially an RC. Feature development is now frozen, and the only additional updates we anticipate will be major bug fixes only.

Read the release notes, review our “edge” documentation, and take a look at our 2.0 upgrade guide if you’re coming from Bridgetown 1.x. If you’re new to the Bridgetown 2.0 release cycle, read our Road to Bridgetown 2.0 series.

Some of the goodies in Beta 4:

We continue to make progress in improving full build performance. While our Fast Refresh feature makes development an order of magnitude faster in most cases, we also want our complete build cycles to go more quickly.
In previous releases, our primary goal was to ensure Bridgetown could “scale up” to large, ambitious application architectures. Now we’re also looking at opportunities to “scale down”. In the latest beta, we support Bridgetown running in a folder with only a Gemfile and some source files. That’s it. No config folder, no Rakefile, no config.ru…you get the picture. And in a follow-up feature in Bridgetown 2.1, we’ll support source folders located elsewhere on the file system as well as Markdown files with no front matter present. If that makes you think wiki!, well, you’re exactly right. ☺️
The first beta of Bridgetown 2.0 introduced the RodaCallable mixin for allowing any PORO (Plain Old Ruby Object) to respond to a Roda route. Now, we’ve introduced the Viewable mixin for allowing any Ruby view component to provide HTML rendering for a route. Daisy-chain callable & viewable objects and you essentially have the “View-Controller” part of MVC solved. We believe this will unlock opportunities to build ever larger and more robust web applications with Bridgetown.
We’ve introduced an entirely new Bundled Configuration to add minitest to your projects, and the tests will be equally adept at validating the output of statically-generated content as well as server-side routes. Yes that’s right: use the exact same testing infrastructure to test static and dynamic endpoints equally—complete with an elegant DSL for making requests and parsing either HTML or JSON.

We’re also plugging away at new documentation around all of these features and more besides, and going forward the bulk of our efforts to get a final 2.0 release out the door will be the docs.

As always, if you run into any issues trying out Bridgetown 2.0 beta, please hop into our community channels and let us know how we can help. We welcome your feedback and ideas! In addition, you can follow us on Bluesky as well as in the fediverse to stay current on the latest news.

Bridgetown 2024: Year in Review

2024-12-30T00:00:00-08:00

This year has been a pivotal one for the Bridgetown web framework. We started off 2024 on some conceptual shaky ground, uncertain about the direction Bridgetown should head in next, but over the spring and summer we really hit our stride and are finishing out the year in a strong position.

Another meaty beta release of Bridgetown 2.0 is just around the corner, and we expect the final Bridgetown v2 production release to land in early Q1 2025—unlocking a new wave of innovation in the Ruby-powered web development space.

Our message for 2025 is a simple one: Bridgetown is ready to be your #1 go-to framework for ambitious small-to-midsize web applications. We’re not just for blogs. We’re not just for marketing pages. We’re for powerful, database-driven, interactive software across a variety of industries and use cases. We’re flipping the script: instead of asking “why Bridgetown?” you’ll be asking “why not?”

Some stats for Bridgetown in 2024:

6 releases, 3 in the 2.0 beta line
15 contributors across all the releases
Grew by roughly 200 stars on GitHub
574 members in Discord
409 followers on Mastodon
And now we’re on Bluesky too!

We’ll have a slew of exciting announcements to make about the broader Bridgetown ecosystem in 2025 as v2 heads out the door, so be sure to subscribe and join in all the right places. If you’ve been thinking to yourself “somebody really needs to shake up the Ruby landscape with a fresh vision for how web applications are architected and deployed—and how to strengthen the open source community with safety and inclusiveness” — don’t worry, we’ve got some good stuff cooking.

In the meantime, we thank you for your continued interest and support of the Bridgetown project and want to wish you a very Happy New Year! Go Ruby!

Performance Boost with Bridgetown 2.0 Beta 3

2024-11-18T00:00:00-08:00

The third beta of Bridgetown 2.0 is here! Read the release notes, review our “edge” documentation, and you will likely want to take a look at our 2.0 upgrade guide if you’re coming from Bridgetown 1.x. If you’re new to the Bridgetown 2.0 release cycle, read our Road to Bridgetown 2.0 series.

Some of the goodies in Beta 3:

It’s not often we’re able to see a major performance gain with a single fix. Thankfully, with this PR in place, we’ve seen full build performance gains of 15-25%…possibly even higher. Huge thanks to Maxime Lapointe for the awesome detective work.

A bug resulting in Liquid templates not working as expected with the new fast refresh feature has been resolved.

Sites using multiple locales (aka i18n) are now better supported by fast refresh. If you encounter any additional issues seeing updated content after making changes to your content files, please file an issue and let us know.

You can now switch to ESModules (ESM) and away from CommonJS for your projects! Run bin/bridgetown esbuild update to install the latest frontend configuration. You may need to edit some of your JS files manually in order to remove outdated require statements and use import instead.

Finally, we’ve been doing a lot of behind-the-scenes work to improve API-level documentation as well as guide-level documentation. For example, you can read up on our new all-Ruby syntax for HTML templates: Streamlined.

As always, if you run into any issues trying out Bridgetown 2.0 beta, please hop into our community channels and let us know how we can help. We welcome your feedback and ideas! In addition, you can follow us now on Bluesky as well as in the fediverse to stay current on the latest news.

It’s Finally Here! Bridgetown 2.0 Beta 1

2024-08-02T00:00:00-07:00

I’m pleased to announce the first beta release of Bridgetown 2.0, the premier static site generator 🤝 full-stack web framework powered by Ruby. Many thanks to everyone who contributed! And if you’re wondering hey, where’s the new code name? …that is forthcoming. We’re going to have a little fun playing with the branding on this one, so stay tuned. 😎

In the meantime, Bridgetown 2.0 is really all about two major initiatives: removing many deprecations from the 1.x line all while tightening up internals and providing a high quality & stable API, and raising baselines with improved defaults to enable a clear vision for the next several years of Bridgetown development.

We’ve written about many of these initiatives previously on the blog—see these posts for reference:

What follows is a simplified list of updates as noted in our changelog. (You can also browse a 1.3…2.0 diff if you’re really curious what’s going on.)

Our “edge” documentation is available here, and you will likely want to take a look at our 2.0 upgrade guide if you’re an existing user of Bridgetown. For example, there are new minimum versions of both Ruby and Node for the v2 release cycle.

(Note that some of the new features/enhancements would benefit from detailed documentation which is still underway. We’ll have things more fleshed out by the final 2.0 release.)

What’s Been Added

We’ve made it possible for Roda routes to render “callable” objects (docs) in a very straightforward manner. In MVP parlance, you can now designate your own “controller” objects to handle any requests, or utilize “view” objects to provide particular kinds of output (and out of the box, resources themselves can be returned directly as responses).

Plus, we’ve simplified front matter data access using new syntax across the system (in Ruby-based templates you can omit data. in many cases, e.g. title instead of data.title), and for Roda rendering in particular it’s now much cleaner to pass data along to templates.

Live reloading in development is dramatically faster on average now with the Fast Refresh feature (see the referenced post above for more on how that works).

There’s now a go-to inflector to handle various string conversions (aka folder_name/file_path.rb → FolderName::RubyFilePath) using dry-inflector (docs).

We’ve added support for new Serbea 2.0 template features, including the pipe helper which can be used even in ERB templates. And in addition, we now have a pure Ruby template syntax via Streamlined. Documentation is forthcoming, but you can take a peak at what authoring HTML using Streamlined looks like. This is Bridgetown’s official answer to techniques like content_tag in Rails or gems like Phlex, and it takes a great deal of inspiration from JavaScript’s tagged template literals.

What’s Changed

Bridgetown now defaults to using ERB in new site projects, rather than the previous default of Liquid. You can choose Liquid (or any supported template engine) when you create a new site, but without specifying a particular option Bridgetown will assume ERB.

The config YAML file is now optional—in fact, in new Bridgetown projects only the config/initializers.rb file is generated as the primary form of configuration. In addition, previous support for .toml files has been removed. We’ll be upgrading our documentation to point out these new defaults.

We’ve significantly refactored the file-based routes plugin under the hood for more robust behavior and continuing improvements over time to support advanced full-stack applications.

As promised, an initial batch of first-party framework code (i.e., bridgetown-foundation) to replace Active Support-based dependencies has landed. And we’re making use of the new Inclusive gem to package and import utility code.

Our start command now uses Rackup (and Rack 3) instead of directly interfacing with Puma. This paves the way for future developments such as supporting other Rack-compatible application servers in addition to Puma.

The way we handle front matter has been extracted into standalone loaders. This will make it easier to maintain our front matter loaders over time as well as offer the possibility of supporting new front matter formats in the future.

What’s Been Removed

We’ve removed legacy code dealing with permalinks, along with a variety of other previously-deprecated code paths. We’ve also removed Cucumber, rewriting our integrated feature tests to consolidate around Minitest exclusively. And our Webpack integration is at last done away with, in lieu of a complete focus on esbuild. End of an era!

What’s Next

Bridgetown 2.0 is generally “feature complete” at this point, although one or two small enhancements waiting in the wings might sneak in before the final release. In general however, we’re focusing on fixing bugs and tightening up reliability over the next few weeks as we transition from beta status to production.

Beyond that, the team is working on additional ecosystem functionality with gems such as Lifeform (form rendering) and Authtown (accounts and logins) which can be used on Bridgetown projects. Our Sequel gem for database access is already out the door. And for server-side rendering of web components in Ruby with a companion library offering client-side interactivity…well, that too is forthcoming. 😁

As always, if you run into any issues trying out Bridgetown 2.0 beta, please hop into our community channels and let us know how we can help. And if you’re new to Ruby, we’re happy to recommend other resources and communities which can give you a leg up. We try our best to follow the Ruby language motto: MINASWAN. (Matz Is Nice And So We Are Nice…Matz being Yukihiro Matsumoto, the creator of Ruby.)

Road to Bridgetown 2.0, Part 3 (Fast Refresh)

2024-05-01T09:44:34-07:00

So before I get right into it, I’m happy to report that Bridgetown 2.0 development progress is proceeding at a rapid pace! Many of the features talked about in the previous rounds (here and here) are well underway, alongside some significant quality of life DX improvements which will make this release really sizzle. Plus I’m looking forward to blogging about some of the underlying particulars soon at the recently rebooted Fullstack Ruby.

Right, now to the topic at hand. I’ll get this out of the way: the Fast Refresh feature—a default setting for the development server coming in v2.0—is not like HMR (Hot Module Replacement), a popular strategy for JavaScript frameworks to make reloading changed code speedy during development. This is in part because—aside from any actual JavsScript files you may have for your frontend—Bridgetown doesn’t use JavaScript.

Bridgetown uses Ruby, and to be precise, is based on “old-school” principles of static site generation. (Unless we’re talking about dynamic routes served via Roda…we’ll save that for a future discussion!) The way it works is you have a repo with a wide variety of input files—Markdown, CSV, HTML templates, images, other assets—and a build process transforms all of those input files in a variety of ways and then outputs them in formats suitable for a functioning website. In that sense, to “reload” a site after making a file change means to go through that entire build process again. For a small site, a full rebuild might be relatively quick…or it might be quite slow if you have hundreds or thousands of pages and assets to deal with.

Where We’ve Been

Bridgetown’s progenitor, Jekyll, offers a limited scope of understanding around the types of content & code to rebuild on-demand as it doesn’t come with any frontend pipeline and doesn’t provide any “live reload” functionality at all for the browser—nor will Jekyll reload Ruby extensions in a repo when you change that code. However, what Jekyll does have—as do many SSGs out there—that Bridgetown hasn’t had to date is an optional “incremental” regeneration process—that is, a change to a content file (Markdown, etc.) doesn’t necessarily require rebuilding the entire site from scratch. But even that can come with limitations, and in many cases a change to a file doesn’t trigger the neccessary downstream changes elsewhere—aka you might revise a headline in Markdown file over here, and over there a template which references said headline would still display the old content.

Stuff like that really grinds my gears. It’s why Bridgetown hasn’t offered an incremental regeneration feature or fast refresh or whatever you want to call it. Trust is the issue. I want to feel confident that the content I’m viewing in development is as accurate as possible, and to a certain degree, you can’t ever trust that what you’re seeing is actually correct when anything less that a full, from-scratch rebuild has occured.

Nevertheless, it’s admittedly a serious UX fail when sites get larger and larger and you suddenly realize that when you fix a typo in a Markdown file you now have to wait 8 seconds before you see that fix appear in the browser. Unacceptable! In an ideal world, you wouldn’t have to wait 8 seconds. Hopefully you wouldn’t even need to wait 800 milliseconds. The refresh would occur as close to “instantaneously” as possible.

That’s the goal with Fast Refresh in Bridgetown 2.0.

How did we accomplish this feat? Read on…

Signals (Of Course 😏)

The concept of Signals has taken the frontend world by storm, and that shift has started to ripple outward into other computing contexts as well. So what are signals? In a nutshell, signals are reactive variables—aka values which, when mutated, cause all subscribers to be notified. If you’re familar with the simpler pattern of observables, you know you have to set up subscriptions by hand—a tedious and sometimes error-prone endeavor. Signals instead are regularly paired with effects—functions which will automatically subscribe to any signals referenced within the function when executed. Later, whenever those signal values change, the effect functions re-execute—like magic! ✨

For a deep dive into this topic from the Ruby perspective, check out Episode 9 of Fullstack Ruby. TL;DR: thanks to the Signalize gem which I wrote as a direct port of Preact Signals, we can use signals in Ruby. And the reason this is such a game-changer for Bridgetown?

By placing resource data into signals, and transformation steps inside of effects, we can track via effects which resources or generated pages would need to be updated due to signals changing. In other words, during the initial full build, we’re assembling a dependency graph in real-time of which pages should be rebuilt later. That way during a refresh, instead of a simplistic incremental regeneration acting on one piece of source data and leaving that data stale on other parts of the site—or just doing the full rebuild which can take a long time—we can instead only rebuild 5 interdependent pages, or 10 pages, or even 50 pages…but probably not 200! (Plus we also get to skip a lot of other slow code reloading logic and so forth whenever it’s simply not necessary…which is the majority of the time!)

The Devil’s in the Details

This process is fairly straightforward if the changed file in question is indeed a resource. We can build up the resource (which could be a page at a URL or it could be a data file) + dependency graph, and simply regenerate those resources. But things get tricky when “generated pages” are involved such as using prototype pages or pagination. For those cases, we need to backtrack to an original resource and re-extract all the necessary data for the generated pages which follow.

All of the places where reactive data can end up are vital to the integrity of the Fast Refresh process. Think of all the contexts where content cohesion is crucial:

If you change the name of a person in _data/authors.yml, all of their blog posts should update.
If you change the title of a document, a sidebar with a list of those documents should update whichever pages include that sidebar.
If you update a blog post description, “page 4” in an archive somewhere should update with that new description.

Doing all that is pretty challenging if you have to trace all those dependencies by hand (either under the hood with complex automagical logic, or with specific directives users must understand and maintain themselves…eww!).

Thankfully…signals to the rescue. And we’re not simply tracking resource<->resource connections, but connections between templates and rendered components. If I update a single component template, but that template is only referenced by one or a few resources (or layouts used by those resources), why should the entire site get rebuilt? Let’s just rebuild the resources which directly render that component. Even layouts factor into this: if you edit a layout, only the resources which use that layout will be regenerated.

For the most part, Fast Refresh will require no changes to existing site repos. It’ll “just work”. But we do have a new mechanism in particular for handling site-wide data which can prove quite interesting. Instead of reaching for site.data, reach for site.signals. All of the keys will be shortcuts for setting/getting signal values—aka site.signals.authors is shorthand for site.signals.authors_signal.value and site.signals.authors.value = ... is shortchand for site.signals.authors_signal.value = .... This means you can save and access site data throughout various plugins/templates, and any changes made to data files will propagate accordingly during Fast Refresh.

All of this serves to ensure that when you update a file, it’s often rebuilt so quickly that by the time you switch from your editor back over to the site in the browser, it’s already been refreshed. (We also have increased speed overall thanks to revisions to our Rack/Roda integration!) I’ve been experiencing this rapid round-tripping a lot over the past few weeks, and it’s pretty freakin’ cool. 😎⚡️

Escape Hatch

The version of Fast Refresh shipping in Bridgetown 2.0 will be good, but it won’t be perfect. There are times it may get tangled up in the web of its own dependencies, or fail to account for a particular type of change, and you’ll need to reboot the dev server—or in the worst case, temporarily switch off fast refresh in your config.

Fast Refresh will get top priority for bug fixes for the forseeable future, which is one of the reasons we’re releasing it switched on by default. We want as many people as possible to test this right out of the gate, so we can fix edge cases as quickly as possible. My own experience has been that even with an occasional hiccup, the quality of life improvement with the increased refresh speed more than makes up for those annoyances. Most of the time, it rocks.

We’ll also be shipping a bonus feature: a way for you to hook into Bridgetown’s live reload JavaScript process to control what happens for that browser reload. For users of frontend libraries like Swup, htmx, Turbo, etc. which can swap or even morph page DOM as part of navigation, you could use those to pull in the updated HTML for an even slicker experience. 😎

Performance is a Feature Too

One of the goals of Bridgetown 2.0 (and 2.1 and beyond) is to reframe how we look at opportunities to increase framework performance. There’s never been a desire among the core team to shave a few ms off of a synthetic benchmark, or to gain paltry bits of performance at the expense of great DX.

But if we can identify clear wins around simplifying code steps, creating modular configurations, streamlining algorithms, and encouraging certain architectures over others so as to improve the performance of both static generation and dynamic routes meaningfully, we’re ready to dive in. If you would like to contribute a test site we can use to benchmark Bridgetown 1.x vs 2.x as we fine-tune this release, please get in touch! Our hope is to gradually build up our release QA process to include regression testing…aka a full site build with each new Bridgetown release should be the same or faster, definitely not slower.

OK, that does it for Fast Refresh! Stay tuned for the next installment of the “Road to Bridgetown 2.0” series all about where we’re going with our Roda and Sequel integrations. Spoiler alert: Bridgetown 2.0 will completely support Rack-native, fullstack, database-driven application requirements where even your index file can be a dynamic route if you so choose. Have your static website cake and eat your dynamic server too? 🍰 Yep! 😁