It’s easy to get started with Bridgetown, but it helps to have a basic understanding of a few key aspects of the site build process so you know which tools to use for the right job. Websites using Bridgetown are built and deployed as atomic artifacts, but they can optionally provide dynamic routes via a secondary server process. This means the website your visitors will ultimately engage with was largely produced as a “snapshot in time”—the product of Bridgetown’s build process. How does that process work? Let’s find out!
The Build Process #
There’s a relatively linear process which occurs every time you run a build command:
- First, Bridgetown loads its internal Ruby APIs as well as any Ruby gems specified in the
bridgetown-pluginsgroup of your
- Next, Bridgetown looks for a configuration file in your current working directory and uses that to instantiate a
- After loading the configuration, Bridgetown prepares the
siteobject for loading the various types of content in your site repository, starting with custom plugins in the
- Plugins are then granted the ability to generate new content programmatically and define other features such as Liquid tags or Ruby helpers (aka “shortcodes”). This is the point when you’d create blog posts and other resources from data provided by an external API for example.
- Once plugins (if any) have loaded, Bridgetown starts systematically reading in files from the source folder (typically
- Data files
- Static files
- Any gem-based plugins which supply their own layouts, components, and content via Source Manifests.
- Once all of the data structures for the entire website are in place, Bridgetown renders all relevant content objects to prepare them for final output. This is when Front Matter variables are made available to templates, any Liquid or Ruby templates are processed, formats like Markdown are converted to HTML, resources are placed within layout templates, and generally everything is finalized in its proper output format (HTML, JSON, images, PDFs, etc.).
- The final step is to write everything to the destination folder (typically
output). If all has gone well, that folder will contain a complete, fully-functioning website which can be deployed to any basic HTTP web server.
Normally during development, you will be running a local dev server, which means every time you change a file (update a blog post, edit a template, replace an image file, fix a bug in a custom plugin, etc.), that entire build process is run through again.
For small-to-medium sites and on reasonably modern hardware, this typically happens in only a few seconds or less. For really large sites with tens of thousands of pages, or if many external API calls are involved, build processes can slow down substantially. There are technical solutions to many of these slowdowns, which can range from caching API data between builds to limiting the number of files built in development. Improving build time is a major goal of the Bridgetown core team as we look to the future.
The Frontend Build Process #
When using Bridgetown’s built-in
essentially two build processes are kicked off: the frontend build process (either esbuild or Webpack) and the Bridgetown build process. The two align when something magical happens.
- esbuild/Webpack will conclude its build process by exporting a
manifest.jsonfile to the hidden
.bridgetown-cachefolder. This manifest lists the exact, fingerprinted filenames of the compiled and bundled JS and CSS output files.
- Bridgetown, using the
asset_pathLiquid tag/Ruby helper, monitors that manifest, and whenever it detects a change it will regenerate the site to point to those bundled output files.
- This way, your website frontend and the HTML of your generated static site are always kept in sync.
Adding Extra Features to Your Site #
In addition to the work you do yourself to code, design, and publish your website, there are ways you can enhance your site by installing third-party plugins or applying automations. These may provide new features, themes, or software configurations in useful ways. Some examples:
- Add instant search to your site with the bridgetown-quick-search plugin
- Include inline SVG images with the bridgetown-svg-inliner plugin
- Start your site off with a clean, professional design via the Bulmatown theme and Bulma CSS framework
You can discover links to these and many more in our Plugins directory.
Server-Side Rendering and Dynamic Routes #
Bridgetown provides a full SSR pipeline powered by the Roda web toolkit. Roda, like Rails or Sinatra, takes full advantage of Ruby’s Rack ecosystem and offers a minimalist yet elegant DSL for defining and handling routes via a “routing tree” as well as processing request/response cycles. Accepting form data or JSON payloads is a snap, and there’s even a core plugin you can configure to enable dynamic, file-based routing with all of Bridgetown’s template engines and component rendering at your disposal.
What to Learn Next #
There is detailed documentation available about each and every step mentioned above, so feel free to poke around and read up on the topics which interest you the most. And as always, if you get stuck or have follow-up questions, just hop in one of our community channels and a friendly Bridgetowner will endeavor to help you out!