Template Engine
Change the template engine Bridgetown uses by default to process content files.
-Default: liquid
Default: erb
template_engine: ENGINE (erb, serbea, slim, haml, etc.)
template_engine: ENGINE (erb, serbea, liquid, etc.)
permalink: STYLE or TEMPLATE
Fast Refresh
+Control the behavior of Bridgetown's live reload functionality in development.
+Default: true
fast_refresh: BOOL
Slugify Mode
diff --git a/bridgetown-website/src/_docs/installation/upgrade.md b/bridgetown-website/src/_docs/installation/upgrade.md index 688691537..10945663d 100644 --- a/bridgetown-website/src/_docs/installation/upgrade.md +++ b/bridgetown-website/src/_docs/installation/upgrade.md @@ -6,6 +6,71 @@ back_to: installation order: 0 --- +Ready to try bringing your project up to the latest version? Here are some notes to help you get going. BTW, if you have a really old site, you may want to try incrementally upgrading versions rather than, say, go from 1.0 to 2.0 in one session. + +We’ve have a [Technical Help board](https://community.bridgetown.pub/c/technicalhelp) on our **Community** site, so if you get totally suck, folks can give you a leg up! (Access to the problematic repo in question is almost always a given in order to troubleshoot, so if your code needs to remain private, please create a failing example we can access on GitHub.) There's also an **upgrade-help** channel in our [Discord chat](https://discord.gg/4E6hktQGz4) (though it's harder to include code examples and links there). + +{{ toc }} + +## Upgrading to Bridgetown 2.0 (Beta) + +The first thing to know is that there are new minimum versions of both Ruby and Node for the v2 release cycle. In general, we try to support the previous two significant releases of these runtimes in addition to the current ones (aka Ruby 3.3 and Node 22) with each major version increase. So you will need to use a minimum of: + +* Ruby 3.1.4 (⚠️ there's a bug in earlier versions of Ruby 3.1 which will prevent Bridgetown to run) +* Node 20 + +Sometimes that's as simple as changing your version dotfiles (for example `.ruby-version` and `.nvmrc`). We do recommend switching to the latest versions (Ruby 3.3 and Node 22 as of the time of this writing) if possible. + +To upgrade to Bridgetown 2.0, edit your `Gemfile` to update the version numbers in the argument for the `bridgetown` and `bridgetown-routes` (if applicable) gem to `2.0.0.beta1` and then run `bundle`. + +We also recommend you run `bin/bridgetown esbuild update` so you get the latest default esbuild configuration Bridgetown provides, and you may need to update your `esbuild` version in `package.json` as well. + +### Switching from Yarn to NPM 📦 + +Bridgetown uses NPM now by default, rather than Yarn, for frontend package managing. You may continue to use Yarn on your existing projects, but if you'd like to switch to NPM, you can simply delete your `yarn.lock` file, run `npm install` (shorthand: `npm i`), and check in `package-lock.json` instead. You can also use [pnpm](https://pnpm.io) if you prefer. Bridgetown is now compatible with all three package managers. + +### Specifying Liquid (if necessary) 💧 + +The default template engine for new Bridgetown sites is ERB, with Liquid being optional. If you're upgrading a site that expects Liquid to be the default template engine, you will need to add `template_engine :liquid` to your `config/initializers.rb` file (or `template_engine: liquid` to `bridgetown.config.yml`). If you don't even have a `config/initializers.rb` file in your project yet, see the below section under **Upgrading to Bridgetown 1.2**. + +### Fixing `webpack_path` bug 🪲 + +Bridgetown unfortunately used to ship with templates which referrenced `webpack_path` in Liquid or Ruby-based templates, even when using esbuild. That helper is no longer available in Bridgetown 2.0, as we've removed support for Webpack entirely. + +You will need to do a search & replace for all uses of `webpack_path` and change them to `asset_path`. This is a one-time fix, and then you'll be good to go for the future or even if you still need to run code on an earlier version of Bridgetown. + +### Crashing Related to Roda 💥 + +If you encounter a weird crash which contains `uninitialized constant Bridgetown::Rack::Roda` in the error log, you will need to update the syntax of your `server/roda_app.rb` file so that it's a direct subclass of `Roda` and configures the `bridgetown_server` plugin. Here's a basic version of that file: + +```rb +class RodaApp < Roda + plugin :bridgetown_server + + # Some Roda configuration is handled in the `config/initializers.rb` file. + # But you can also add additional Roda configuration here if needed. + + route do |r| + # Load Roda routes in server/routes (and src/_routes via `bridgetown-routes`) + r.bridgetown + end +end +``` + +### Supporting Active Support Support 😏 + +Bridgetown v2 has removed a number of dependencies in the codebase on the Active Support gem (provided by the Rails framework). If that ends up causing problems with your codebase, you may need to require Active Support manually (and even Action View) in your `config/initializers.rb` file. [Here's a thread on GitHub](https://github.com/bridgetownrb/bridgetown/pull/881#issuecomment-2228693932) referencing this situation. + +### Caveats with Fast Refresh in Development ⏩ + +Bridgetown v2 comes with a "fast refresh" feature by default. This rebuilds only files needed to display updated content in source files, rather than the entire website from scratch. However, certain features aren't yet compatible with fast refresh—most notabily, **i18n**. If you're using multiple locales in your project, you will likely want to disable fast refresh so you don't end up with broken pages/links by setting `fast_refresh` to `false` in your config. + +### Quick Search and Other Plugins 🔍 + +You will need to update to the latest v3 of the [Quick Search plugin](https://github.com/bridgetownrb/bridgetown-quick-search) if you use that on your site. You may also want to double-check other Bridgetown plugins you use and make sure you're on the latest version. + +---- + ## Upgrading to Bridgetown 1.2 Bridgetown 1.2 brings with it a whole new initialization system along with a Ruby-based configuration format. Your `bridgetown.config.yml` file will continue to work, but over time you will likely want to migrate a good portion of your configuration over to the new format (and maybe even delete the YAML file). @@ -120,4 +185,3 @@ The other major change you’ll need to work on in your project is switching you The live reloading mechanism in v1.0 is no longer injected automatically into your HTML layout, so you'll need to add `{%% live_reload_dev_js %}` (Liquid) or `<%= live_reload_dev_js %>` (ERB) to your HTML head in order to get live reload working. Please make sure you've added `BRIDGETOWN_ENV=production` as an environment variable to your production deployment configuration so live reload requests won't be triggered on your public website. {% end %} -We’ve added an **upgrade-help** channel in our [Discord chat](https://discord.gg/4E6hktQGz4) so if you get totally suck, the community can give you a leg up! (Access to the problematic repo in question is almost always a given in order to troubleshoot, so if your code needs to remain private, please create a failing example we can access on GitHub.) diff --git a/bridgetown-website/src/_posts/2024/2024-08-02-its-here-bridgetown-2.0-beta-1.md b/bridgetown-website/src/_posts/2024/2024-08-02-its-here-bridgetown-2.0-beta-1.md new file mode 100644 index 000000000..fdcbdbd06 --- /dev/null +++ b/bridgetown-website/src/_posts/2024/2024-08-02-its-here-bridgetown-2.0-beta-1.md @@ -0,0 +1,61 @@ +--- +title: "It’s Finally Here! Bridgetown 2.0 Beta 1" +subtitle: "New baselines, better defaults, greater dev performance (Signals!), an enhanced full-stack application framework, and a whole lot more." +author: jared +category: release +--- + +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: + +* [Part 1 (Stuck in Burnout Marsh)](/future/road-to-bridgetown-2.0-escaping-burnout/) +* [Part 2 (New Baselines)](/future/road-to-bridgetown-2.0-new-baselines/) +* [Happy 4th Birthday, Bridgetown!](/news/happy-birthday-bridgetown/) +* [Part 3 (Fast Refresh)](/future/road-to-bridgetown-2.0-fast-refresh/) + +What follows is a simplified list of updates as noted in our [changelog](https://github.com/bridgetownrb/bridgetown/blob/main/CHANGELOG.md). (You can also [browse a 1.3...2.0 diff](https://github.com/bridgetownrb/bridgetown/compare/1-3-stable...main) if you're _really_ curious what's going on.) + +[Our "edge" documentation is available here](https://edge.bridgetownrb.com), and you will likely want to [take a look at our 2.0 upgrade guide](https://edge.bridgetownrb.com/docs/installation/upgrade) 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](https://edge.bridgetownrb.com/docs/routes#callable-objects-for-rendering-within-blocks) (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](https://edge.bridgetownrb.com/docs/routes#file-based-dynamic-routes). + +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](https://edge.bridgetownrb.com/docs/configuration/initializers#inflector) (docs). + +We've added support for new [Serbea 2.0](https://serbea.dev) 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](https://github.com/bridgetownrb/streamlined/blob/b5d7e5bab0589b3f581c8a709f970870fa8da327/test/test_streamlined.rb#L32). 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](https://edge.bridgetownrb.com/docs/routes#file-based-dynamic-routes) 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](https://github.com/bridgetownrb/bridgetown/tree/main/bridgetown-foundation)) to **replace Active Support-based dependencies** has landed. And we're making use of the new [Inclusive gem](https://github.com/bridgetownrb/inclusive) to package and import utility code. + +Our `start` command now uses Rackup (and [Rack 3](https://github.com/rack/rack)) 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](https://github.com/bridgetownrb/bridgetown_sequel) 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](/community) 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](https://en.wikipedia.org/wiki/Yukihiro_Matsumoto), the creator of Ruby.)