How to upgrade your Bridgetown site

If you run into trouble upgrading your Bridgetown site, this might help you.

I have been building small sites with Bridgetown for a while now. Sometimes Rails is not a good fit for particular projects, and Bridgetown offers just enough to get things done and enjoy the process. Plus, it uses Ruby. The best part.

Even though it has evolved in ambitions, Bridgetown remains a static site generator.

What is a static site generator?

Before the days of frameworks, Javascript build tools and random compile errors, websites used to be the just folder you FTP up to a server and voila. Your website was live.

Now things are different, we have more advanced needs, but people like me pine for those days before Webpack error two hundred and one cropped up to ruin the day.

Tangent aide, I have been using Bridgetown for about two years on this site, and recently Jared Whyte announced that Bridgetown Version 1 was ready. I have been so impressed that I even sponsor Jared on Github.

This is a big deal because I grew up as an Irish farmer. Anyone who knows Irish farmers knows that spending money is a foreign concept. I’m pretty sure Irish farmers can hear bills travelling to their postbox.

I wanted to upgrade to the latest version and use Esbuild. I ran into a few issues, so hopefully, this helps anyone with the same problems.

After following the upgrade guide and running the script to switch webpack to esbuild, I ran into some errors.

config/esbuild.defaults.js:68:10: note: This error came from the "onLoad" callback registered here
   68 │   build.onLoad({ filter: /\.(css)$/ }, async (args) => 
     ╵      ~~~~~~

In the end, it turned out that this was because I updated TailwindCSS, and my old tailwind.config.js was incorrectly formatted.

After I corrected my tailwind.config.js file, everything worked.

Here is every step I followed:

1. Visited this site
2. Add the gem puma to the Gemfile and ran bundle update
3. Ran bundle binstubs bridgetown-core
4. Created a separate bridgetown site and copied over files config.ru, Rakefile, config/puma.rb, and everything under server/*
5. Ran bin/bridgetown esbuild migrate-from-webpack created by Andrew Mason
6. Removed start.js, sync.js
7. removed browser-sync and concurrently from my package.json
8. Changed the Rakefile to use esbuild

# Rakefile
require "bridgetown"

Bridgetown.load_tasks

# Run rake without specifying any command to execute a deploy build by default.
task default: :deploy

#
# Standard set of tasks, which you can customize if you wish:
#
desc "Build the Bridgetown site for deployment"
task :deploy => [:clean, "frontend:build"] do
 Bridgetown::Commands::Build.start
end

desc "Build the site in a test environment"
task :test do
 ENV["BRIDGETOWN_ENV"] = "test"
 Bridgetown::Commands::Build.start
end

desc "Runs the clean command"
task :clean do
 Bridgetown::Commands::Clean.start
end

namespace :frontend do
 desc "Build the frontend with esbuild for deployment"
 task :build do
  sh "yarn run esbuild"
 end

 desc "Watch the frontend with esbuild during development"
 task :dev do
  sh "yarn run esbuild-dev"
 rescue Interrupt
 end
end

#
# Add your own Rake tasks here! You can use `environment` as a prerequisite
# in order to write automations or other commands requiring a loaded site.
#
# task :my_task => :environment do
#  puts site.root_dir
#  automation do
#   say_status :rake, "I'm a Rake tast =) #{site.config.url}"
#  end
# end

bin/bridgetown configure bt-postcss

bin/bridgetown configure stimulus

bin/bridgetown configure tailwindcss

After that, I ran into the error where esbuild would not generate the CSS, which was a pain to debug because the stack trace was misleading. However, by correcting the tailwind config, everything started working. This took me a few hours to work out.

Next, I had to update my liquid templated because collections work differently.

# Before
for post in site.posts %}
#After
{% for post in collections.posts.resources %}

In one of my components, I did the following to keep the same a tag href
# Before
post.url
# After
post.relative_url

Then I changed my Netlify to run bridgetown deploy instead of yarn deploy.

After that, I had to update my head to use resource title instead of page.title.

<!-- src/_components/head.liquid -->
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
{% capture resource_title %}{{ title | strip_html | strip_newlines }}{% endcapture %}
<title>{% if resource_title != "Index" %}{{ resource_title | escape }} | {{ metadata.title | escape }}{% else %}{{ metadata.title | escape }}: {{ metadata.tagline | escape }}{% endif %}</title>

<meta name="description" content="{{ metadata.description }}" />
<link rel="stylesheet" href="{% asset_path css %}" />
<script src="{% asset_path js %}" defer></script>

Finally, for the sitemap, I just installed this handy gem(https://github.com/ayushn21/bridgetown-sitemap), which did what my code previously did.

Hopefully, that helps anyone who has run into trouble updating their Bridgetown site to version 1.

Long live Bridgetown.