Bridgetown [v1]

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! 😁

Happy 4th Birthday, Bridgetown!

2024-04-02T08:09:29-07:00

Four years ago today, I wrote in my Day One journal:

“I forked Jekyll today and turned it into Bridgetown, so I’m now privately the maintainer of a Webpack-aware, Ruby-based static site generator for the modern JAMstack era. How cool (and crazy) is that?!?!”

The first public website launch and release of Bridgetown 0.10 happened a few weeks later, and the rest as they say is history. As always, a hearty thank you to all our sponsors and 70+ contributors who have helped this open source project flourish in ways I never could have imagined.

Some “hindsight is 20/20 thoughts”

I know we all sort of cringe thinking about Webpack today (esbuild forever!), but back then it was still a Big Deal and represented a major frontend shift towards using ESM, pulling in packages from NPM for both JavaScript and CSS libraries/frameworks, and compiling using JavaScript-based tools. Having a pre-configured frontend pipeline that Just Works™ come ready to roll with your site generator was (and is) nothing to sneeze at.

It’s interesting to look at my original notes on what was most urgent to add to whatever might emerge from this fork: Webpack (as mentioned), Components (not just basic includes/partials), Internationalization (i18n), and easier third-party API integration were top of the list. A promising start! But a lot of what I love today about Bridgetown hadn’t quite been conceived of yet. Much has happened in only four years! (You can find a more in-depth list of post-Jekyll features and changes here if you’re curious.)

One major direction for Bridgetown I imagined in those earlier days that we ended up totally shifting away from is a tight integration with Rails. Aside from my own perspective on Rails shifting, it turns out a significant level of interest in the potential architecture such a marriage might produce never materialized. I could do a deep dive some day into why that might be, but the good news (and a direction I never would have foreseen in 2020!) is that we pivoted into a tight integration with Roda. That proved to be a huge boon for the framework—with a lot of newer features being heavily inspired by the “Roda way” like the new Initializers system—and I’m ready to push that all to the max this year. I see no reason why, with just a tad more DX polish, a combined Bridgetown + Roda couldn’t be then used to build substantial web applications serving thousands of customers. I look forward to spreading the message that Bridgetown is far more than “just” a static-site generator (as we clearly say right on our homepage!) by promoting solid integrations with Rodauth and Sequel to round out our server-side offerings. (We’re basically just living in the JECU—the Jeremy Evans Cinematic Universe—at this point! 😅)

In closing…

We’re currently in the midst of the Bridgetown v2 development cycle, and I’ll be posting Part 3 of our blog series on the topic shortly. In the meantime, follow us on Mastodon to stay on top of the latest news. Thank you once again for all of your support over the past four years. The Bridgetown community is now larger than any one of us, and I can’t wait to see what the next four years have in store for Rubyists everywhere.

Road to Bridgetown 2.0, Part 2 (New Baselines)

2024-02-29T08:14:56-08:00

“And blood-black nothingness began to spin…a system of cells interlinked within cells interlinked within cells interlinked within one stem…and dreadfully distinct against the dark, a tall white fountain played.”

OK OK, not that baseline. 😜

Rather, what we’re talking about are technology baselines. Minimum language version requirements. Language syntaxes. Tool dependencies. That sort of thing.

The Bridgetown 2.0 release cycle lets us reset some of these baselines, moving the framework into a more modern era without sacrificing developer experience or causing major upgrade headaches. For the most part, you should be able to keep your projects running with few (if any) changes. But of course, with a little spit and polish, you’ll be able to take full advantage of improvements lower in the stack.

Let’s step through the various baselines we’ll be providing in Bridgetown 2.0.

Ruby 3.1

Bridgetown 3.1 will require a minimum Ruby version of 3.1. Our policy is that for each major version number increment (in this case, v2), we will move the minimum Ruby version to two yearly releases prior to the current one. Since today’s Ruby version is 3.3, that allows us to support Ruby 3.1 and 3.2 as well.

Because we’re moving from the past minimum of Ruby 2.7 to 3.1, this opens up a whole new world of Ruby v3 syntax and functionality being made available to the Bridgetown ecosystem. I wrote about some of my favorite Ruby 3.1 features over two years ago! And even more has happened since with the releases of Ruby 3.2 and 3.3. (YJIT, anyone?)

We suspect many Bridgetown projects are already on Ruby 3, and for those still using Ruby 2.7, the upgrade process to switch to at least 3.1 should be fairly smooth.

Node 20

Until recently, for a good window of time it seemed like the particular version of Node you happened to be running wasn’t a huge deal since Bridgetown’s use of Node has been almost exclusively relegated to compiling frontend assets.

While that will continue to be the case, we are making some specific, intentional changes to how Bridgetown integrates with Node. In order to streamline these efforts, it makes sense to standardize on newer versions of Node.

As of the time of this writing Node 21 is the current production release, but as we suspect Node 22 is right around the corner (based on Node’s yearly release schedule), we are jumping the gun just a tad and going with Node 20 as our baseline (since essentially that will be two versions prior to current once Bridgetown 2.0 is released later in Q2).

Which brings us to:

ESM

The JavaScript NPM ecosystem has been stumbling towards its goal of coalescing around ES Modules (ESM), rather than CommonJS, for quite a long time now. It feels like we’ve arrived at the moment when it’s now or never, so let’s do it now. For those of you only vaguely aware of what the differences are, here it is in a nutshell:

const path = require("path") // CommonJS

import path from "path" // ESM

Yes, for those of you asking, ESM has been the only way you write JavaScript for client-side purposes (since ES6 anyway). Yet Node’s historical CommonJS manner of importing and exporting modules and packages has persisted on the server. The end is nigh though, as universal ESM syntax has been embraced more and more throughout the ecosystem.

There are two ways to instruct Node to use ESM instead of CommonJS. You can name JavaScript file extensions as .mjs. Or you can add "type": "module" to your package.json file.

For Bridgetown 2.0, we will be opting for that latter option, and all configuration files for tools like esbuild and PostCSS will be supplied in ESM format. CommonJS will still work in your existing projects, but for all new projects, it will be all ESM, all the time! 👏

Farewell Yarn

When the Bridgetown framework first launched in 2020, many people considered Yarn to be a better package manager than Node’s built-in npm solution. Many frameworks had built up around it, and even Ruby on Rails had embraced it.

But time doesn’t stand still, and neither did npm because at this point, it works just as well as “classic” Yarn and newer versions of Yarn ended up causing headaches due to changing designs, syntax, and feature-set sweet spots.

So in Bridgetown 2.0, we’re greatly simplifying and migrating to using npm by default. You still have the option of keeping classic Yarn around for use in your existing Bridgetown projects—or you can switch over to npm or even another popular package manager, pnpm. We’ll focus on npm out of the box, but switching to pnpm should you wish it will be straightforward (we’ve actually supported it in the most recent v1.x releases anyway).

Farewell Webpack

Bridgetown has defaulted to using esbuild for its frontend bundler for some time now, but with Bridgetown 2.0 we’ll be removing official support for Webpack. This does mean we recommend migrating your projects from Webpack over to esbuild as soon as possible, since we have no guarantee Webpack will continue to work once Bridgetown 2.0 arrives.

The writing has been on the wall for some time, as the entire web industry generally pivots away from Webpack and towards more modern solutions like esbuild (Vite, Turbopack, and Parcel being some other popular options).

The good news is that we continue to feel extremely satisfied with our embrace of esbuild. I personally like to say that esbuild is the “last bundler” I’ll ever use. And I really believe that. I see no reason years from now why esbuild won’t still be perfectly adequate to perform the sorts of lightweight frontend bundling and asset pipeline tasks Bridgetown users typically require. It’s nice to have that level of confidence in a framework dependency.

ERB by Default

And last but certainly not least, we’ll be switching away from Liquid as our default out-of-the-box template engine and over to ERB. Bridgetown is a Ruby framework after all, and ERB is the template language most Rubyists are familiar with. The reason we ever defaulted to Liquid in the first place was an historical one…Jekyll defaulted to Liquid—and in fact only supports Liquid (you have to install a third-party plugin to get some sort of ERB support). But with Bridgetown having supported ERB for years now, it makes sense to go ERB-first.

However, we have a few tricks up our sleeve—some extra features in the works to bring Serbea-like pipelines over to ERB, as well as a new DSL based on procs & heredocs called Streamlined you can use instead of ERB in certain parts of your codebase to generate complicated HTML quickly and efficiently. (This is essentially our answer to “tag builders.”)

And for that maximum cool factor, we’ll be unveiling an optional, first-party solution to server-rendering web components which can later be hydrated and become interactive on the client-side. We’ve already offered a solution of sorts along these lines with our integration of Lit-based web components. However, this new solution will provide a whole new component format—one which takes further advantage of Ruby as well as the proposed HTML Modules spec. Ooo…exciting!

(Note that we’ll be retiring first-party support for Haml and Slim. I don’t wish to step on anybody’s toes, but template syntaxes based around indentation/whitespace rules just aren’t on the radar of frontend developers by and large. I would argue they feel more like an artifact of Ruby’s past than anything modern developers are looking for. Let’s rally around writing HTML templates in ways which frontend devs can feel comfortable with and get up to speed on quickly.)

Wrap Up

So there you have it: Ruby 3.1. Node 20. npm. esbuild. ERB and a whole lot more. A solid set of defaults we believe will make Bridgetown that much more robust, appealing, and ready to tackle the challenges of tomorrow.

There are also some efforts underway to streamline parts of Bridgetown’s internals to make it easier for contributors and maintainers. Besides simply removing a handful of small deprecations, we’re in the process of completely moving away from Cucumber and towards standard Minitest for integration tests to bring them in line with the rest of the automated test suite. You can read more about these efforts on the community site.

Along with quality-of-life and maintenance improvements, we hope to make progress in increasing the build performance of Bridgetown. Perhaps not so much in production per se (where, to be honest, it’s less critical—the difference in your site rebuilding in CI in 12 seconds vs. 6 actually doesn’t matter much), but most definitely in development. We all know how frustrating it can be to make a small text change and then have to wait seconds—maybe even tens of seconds!—before the page will refresh in your browser. We have a solution in mind called Fast Refresh based on the principles of Signals, using the Signalize gem which is a Ruby port of Preact Signals. It’s not quite an “incremental build” type of solution, but it’ll get us where we need to go. More on all that in the next installment of Road to Bridgetown 2.0.

Until then, hop on over to our community site and let us know what you’re most excited about regarding these changes in Bridgetown 2.0. As always, your feedback is most welcome!

Road to Bridgetown 2.0, Part 1 (Stuck in Burnout Marsh)

2024-02-22T09:20:27-08:00

TL;DR: Bridgetown 2.0 is now under active development! We have a new Community discussion site, based on Lemmy! Stay tuned for additional announcements coming soon of what’s next for the ecosystem! And now, on with the post…

A little known area of Bridgetown, upriver from where the tourists typically spend their time on vacation, is a treacherous stretch of water known as Burnout Marsh. My boat got mired there during the back half of 2023, and I barely escaped with my life.

All right, enough of that clumsy metaphor. 😄 I didn’t want to have to write this post, believe me. I’d much rather just get on to all the juicy technical stuff that’s fun to talk about. Blog posts about “maintainer burnout” are as exciting to read as watching paint dry. It’s a bit akin to the celebrity complaining about how they have to hire security because they’re just so gosh darn famous. Like, dude, you’re famous OK? Quit yer whining before you look like an asshole.

But the fact remains that maintainer burnout is a thing, and it affects a lot of open source software projects. Everyone’s burnout looks a little different, and mine was no different in that way. A little bit of this (weird, weird time in the tech industry), a little bit of that (too many other irons in the fire), but mostly a particular thing (to be revealed momentarily) which affected the worst possible facet of my role as a maintainer of Ruby-based software: my love of Ruby. 😱

Truth be told, I nearly walked away. 😞

And the reason is both complex and simple. Here’s the simple version: the social degradation of 37signals in general and David Heinemeier Hansson (DHH) in particular nearly robbed me of all the joy I felt programming in Ruby. 😬

Now nearly as distasteful to me as wallowing in “maintainer burnout” territory is wallowing in “framework authors taking potshots” territory. So you can imagine I’m doubly not feeling great about where this is headed. I’ve written some version of this post over and over again in my head, and more than once in my drafts folder which you’ll never see let me tell you right now. But like ripping off a Band-Aid, some things just have to be done. So here it goes.

The 37signals Problem

I was aghast when the meltdown at 37signals happened in 2021. It was widely covered at the time, perhaps best by Casey Newton in several pieces such as Behind the controversy at Basecamp and Inside the all-hands meeting that led to a third of Basecamp employees quitting. At the time, I thought surely there would need to be some reckoning with how DHH conducts himself within open source projects as well such as Rails and Hotwire. Perhaps Rails could set up a more transparent governance structure, or at the very least announce DHH stepping down from a position of influence for a while (while making a very public stand around proper Code of Conduct (CoC) etiquette).

Not only did none of that happen 🤨, but DHH made a huge stink about not being properly invited to keynote RailsConf again right away, leading to RailsConf and DHH going their separate ways and the eventual formation of the “Rails Foundation” and Rails World conferences. So…no such reckoning. DHH would maintain an iron grip on Rails indefinitely (this new foundation really just solidifying his personal influence rather than offering any sort of real check on his power or ego), and in fact go forward to “compete” with RubyCentral and RailsConf. 😩

As if this wasn’t all bad enough, the next shoe to drop dropped…and in a very public way as these things are wont to do. Out of the blue, without warning to any regular contributors or other community members, 37signals (aka DHH) simply decided to remove TypeScript from the Hotwire Turbo codebase. Again, no opportunity for discussion, no time for a heads up or any sort of guidance on how it might affect existing contributions. Just boom, here’s the PR, insta-merge within hours, self-congratulatory DHH post on HEY World, done. 😳

Folks, this is not how you run an open source software project. Somebody’s hobby project on GitHub that’s really just their own little playground, sure, I guess. But not something as consequential as, oh I dunno, the frontend stack of the Ruby on Rails framework and a tool used even outside of Rails by other frameworks! 🤪

Note carefully that none of what I’m saying or about to say has any bearing on the merits of removing TypeScript. We can debate those merits at our leisure, and anyone who knows me knows I’m no big fan of TypeScript. But that’s not what this is about. This is about how people govern open source projects and conduct themselves among peers.

Needless to say, this move to unexpectedly rip TypeScript out of Turbo generally went down like a lead balloon, and things got heated fast. That’s never a good sign (when long-time regular contributors to a project are themselves feeling pretty grumpy), and it eventually led to this seminal issue: Remove DHH for CoC Violations · Issue #977.

To be very clear, nobody’s claiming that making the decision to remove TypeScript was a CoC violation, but the manner in which it was done: with zero involvement of the community and no consideration whatsoever (active hostility in fact) of broad feedback about the decision. I want to quote DHH’s posted response to this claim of CoC violation in full, because there simply is no way for me to read this without feeling enraged once again, and I want you to feel enraged too:

“This is elevating a disagreement of a technical decision to a level of nonsense that has no place here. This project has been founded, funded, and maintained predominantly by the resources and investment of 37signals. We will set the direction as we see fit, accepting input and contributions as they’re presented, but with no guarantee of concurrence or merging. All the best finding a project that’s more to your liking in direction or leadership or otherwise somewhere else 👋”

Notice all the very specific language DHH employs here:

“nonsense” — regular readers of his blog know this to be code for “woke lefties” who would dare challenge his alt-right “edgelord” positioning on a variety of topics. Every time DHH’s political machinations are being publicly challenged, you’ll see the accusations of “nonsense” trotted out (here’s but one example…stochastic terrorism is “nonsense” in DHH-speak, a product of “woke scolds”).
“founded, funded, and maintained by…37signals” — in other words, you, dear contributor to the Turbo repo, don’t actually matter if you aren’t specifically part of the business entity known as 37signals. This is technically open source, sure, but the benefits mostly flow in a single direction. 37signals gets all the benefits of your efforts to improve their codebase, yet meanwhile you get none of the power. Yes, you get to use their code in the end, but that’s it. That’s the only benefit. Whoop-dee-frickin’-doo.
“We will set the direction as we see fit” — and by “we” he means himself. DHH. The big kahuna.
“All the best finding a project that’s more to your liking” — aka if you don’t like how I run things, fuck you.

Folks, there are times when situations are complicated, nuanced, with no real good guys or bad guys, and it’s genuinely hard to parse out what’s really going on and how to process the myriad of factors in order to arrive at a comprehensive decision.

This is not one of those times. 😅

Clearly what we witnessed in this debacle is far from a shining example of how one should govern an “open source” project. Perhaps it would be better described as “source available” — use the code, but don’t count on the stewards of the code to care for the needs of the community. And to get real specific, I am convinced that yes, DHH has indeed been in violation of his own CoC, and the real tragedy is nobody has the power to call him on his own bullshit. DHH is co-owner of 37signals, and 37signals controls all Hotwire intellectual property.

Personally, I find DHH’s continued stranglehold over the Rails and Hotwire frameworks nauseating and thoroughly unacceptable. But ultimately, that’s not the hardest part of it for me. It’s all the carrying water for him that’s gone on in the broader community. People—and yes, good people all—still keep promoting Rails (and Rails World), keep releasing Ruby code and educational resources that prop up Rails as much if not more so as Ruby, and essentially keep DHH on his pedestal.

It’s enough to make you just want to up and quit Ruby. Which I very nearly did. 😭

But, y’know, I gave myself lots of time to think and reflect. I chatted a lot with my close friends and fellow Bridgetown team mates. I mused on ways I might be able to make Bridgetown “fun” again, both in terms of ongoing maintenance as well as future feature development. I waited to see if maybe I could get my boat unstuck and past Burnout Marsh and start heading downriver towards calmer waters again.

And now I’ve arrived here. 😌

What’s Next for Bridgetown in 2024

This post kicks off a short blog series outlining some of the approach we’re taking to construct the next major release of Bridgetown, version 2.0. But it’s also an announcement: we have a new Community site y’all! 🙌

Part of my general burnout in 2023 was just dealing with the absolute insanity which seems to have taken over the computer industry…not the least of which is the rapid “enshittification” of commercial social networks. It really got me paranoid—not only worrying about which services were actively going sideways (cough Reddit cough) but which might implode next in the future. Bridgetown has relied heavily on Discord, and to a lesser extent GitHub Discussions, and, well, I’ve been growing increasingly antsy about each.

So rather than wait for more shitty developments and scramble to react to them, I decided to be proactive and set up a new Bridgetown Community site, based on Lemmy. This serves as a replacement to GitHub Discussions, and an adjunct to Discord. We’ll still rely on Discord for chit-chat (at least until something can serve as a truly suitable substitute) but look to the Community site for longer forum-style posts, technical conversations, tutorials, and something “bloggy” that’s a bit less formal than posting here on the main blog. There are some interesting tidbits there already, and I look forward to more folks in the Bridgetown ecosystem commenting there going forward!

So let’s wrap up with a brief mention of what we’re announcing today as part of the “Road to Bridgetown 2.0” push. If you read my diatribe above, what I’ll say next probably won’t come as much of a shock.

We’ve begun the process of de-37signals-ifying Bridgetown. (Now there’s a mouthful! 😆)

Here’s what this means. We have put an immediate stop to integrating any more dependencies run by 37signals in Bridgetown. In practical terms, this means no additional embrace of libraries like Active Support, and no continued investment in bundled configurations such as Turbo or Stimulus (in fact we’ll be removing these for Bridgetown 2.0). And over time (this will be very much an incremental thing), we will either remove our internal dependency on Rails libraries like Active Support or vendor specific code we can’t easily replace.

This is certainly not ideal. The Bridgetown codebase, and community at large, has benefited from the features provided by Active Support, Turbo, and other 37signals-run projects. But as DHH so emphatically put it, “all the best finding a project that’s more to your liking in direction or leadership or otherwise somewhere else 👋”. So that’s exactly what we are doing. We’ll be looking at other libraries — or in certain cases just building our own solutions — to replace the functionality we had relied on from 37signals.

We take Bridgetown’s own Code of Conduct seriously, and part of that approach means we need to be careful we don’t pull in third-party dependencies from open source projects which are themselves in violation of their CoCs. We’re not in the business of policing the internet, nor can we ever vouch for all other open source projects we might ever touch in some way. But it was a strategic decision originally to embrace codebases run by 37signals, and it is another strategic decision to let them go. I’ve talked about this at length with the rest of the Bridgetown core team, and we are in agreement that it’s in the best long-term interests of the Bridgetown project to take a public stand on this.

So that is merely one aspect of the work that’s ongoing as we head towards Bridgetown 2.0. But thankfully, there’s a lot more that will no doubt prove more exciting and hopeful, from a minimum requirements bump to Ruby 3.1 and Node 20 to a huge performance boost in development in the form of Signals-based Fast Refresh. More on that in the next blog post.

The big takeaway is that I’m feeling more pumped about the future of Bridgetown than I have in many months. Between sorting out feelings of disappointment around past events, and coming up with a list of improvements to the project and the ecosystem I’m very excited to be moving forward on, a new day has dawned. 🌞

Bridgetown 2.0 represents a sort of clean break, not just because we can remove deprecated APIs, streamline aspects of the codebase, and improve features in ways that will help make the framework faster and more stable, but because version 0.x represents an experiment, 1.0 represents something stable yet still new, and 2.0 represents longevity. Bridgetown is here to stay. We have a full major version bump looming. And we hope you’ll stick around to see what comes next. 🤓

Want to discuss this post? Jump over to our Community site and add your comment 🔗

Presenting Islands Architecture in Bridgetown 1.3 “Kelly Butte”

2023-07-10T00:00:00-07:00

We’re pleased to announce the release of Bridgetown 1.3 “Kelly Butte”. Thanks to the many contributors who have helped make this release possible!

Read the release notes or installation instructions, or to upgrade from a previous version, simply bump up the version numbers in your Gemfile and run:

$ bundle update bridgetown

# or

$ bundle update bridgetown bridgetown-routes

It’s not mandatory that you update your esbuild config, but it’s definitely encouraged (especially if you’d like to take advantage of the latest experimental frontend features). To do so, run bin/bridgetown esbuild to get the latest default configuration and follow the instructions. Some of the changes required a fair bit of tinkering, so if you run into any problems please let us know so we can correct them right away.

Here’s a rundown of some of the fixes and improvements before we get to the “flashy” new frontend-themed features:

We’ve finally upgraded our Faraday dependency to v2. 😅 Puma has well has been upgraded to v6.
Also the included connection helpers in the Builder API has been much improved.
Error handling and messaging is much nicer now! Before, certain errors would simply crash the Bridgetown dev process, and if you were viewing your website as that happened, you might not even notice there was a problem. Now, we try to surface error messages right on the website, and the dev process is also less likely to crash. Please let us know if you continue to encounter any severe issues!
We’ve added support for Nokolexbor as a faster alternative to Nokogiri for processing HTML Inspectors.
The l helper is now available alongside the t helper for localizing dates and other such strings.
The Lit and Ruby2JS bundled configurations have seen relevant updates.

Now on to the good stuff. ;-P

Introducing Islands Architecture

Old and busted: putting all your JavaScript, web components, and other frontend libraries in a single bundle that applies to every page on your website.
New hotness: only bundling the bare minimum (if anything) for your website as a whole, and instead using “islands” on individual pages as needed.

As it says in the documentation, the term Islands Architecture was coined a few years ago by frontend architect Katie Sylor-Miller and further popularized by Preact creator Jason Miller. It describes a way of architecting website frontends around independent component trees, all rendered server-side initially as HTML but then “hydrated” on the frontend independently of one another.

Now in Bridgetown 1.3, we’re bringing islands architecture to you with a seamless integration between our view components and our esbuild frontend bundling system. And for even more flexibility, you can even orient your Roda routes around “islands” for a truly modular, full-stack approach to web development.

This is an early step forward for the framework, so your feedback is crucial as we increasingly align our best practices with the latest improvements across the industry.

Declarative Shadow DOM

As it so happens, islands architecture plays very nicely with an experimental new frontend feature we’re super excited about: Declarative Shadow DOM. You can use DSD in your layouts, components, and generally anywhere it would be beneficial to increase the separation between presentation logic & content and work with advanced scoped styling APIs. And of course, paired with islands architecture, you can essentially get “hydrated” components that are first server-rendered and then become interactive on the client-side for “free” using native browser APIs—but only when and where needed for optimal performance. Wow!

We’re considering these features “experimental” for now, but rest assured, we fully expect they will become mainstays of Bridgetown websites and application architectures in the coming months and years. We can’t wait to see what you come up with!

More Frequent but Smaller Releases

I personally have found it a bit challenging to stay on a steady release schedule this year, and I think it all stems from my reluctance to bundle “mere” fixes and tweaks into a release that doesn’t offer a marquee feature to promote. That’s my bad, and henceforth I plan to correct it. So starting now, expect to see Bridgetown 1.3.1, 1.3.2, etc. in a more rapid succession, and possibly even 1.4 that’s mostly about minor improvements.

We’ll never match the release pace of some of our (ahem) JavaScript-based compatriots in the framework space, but we can do better than we have. I also intend to focus more effort on providing improved guidance for new contributors and even new core team members to hop aboard the project and make a meaningful impact.

As always, if you run into any issues trying out Bridgetown please hop into our community channels and let us know how we can help. If you’re new to Ruby, we’re happy to recommend other resources and communities which can give you a leg up. Cheers!