Getting Started

This guide explains how to set up a utopia website for local development and deployment.

Middleware

This guide gives an overview of the different middleware used by Utopia.

Server Setup

This guide explains how to deploy a utopia web application.

Integrating with JavaScript

This guide explains how to integrate JavaScript into your Utopia application.

What is XNode?

This guide explains the xnode view layer and how it can be used to build efficient websites.

Updating Utopia

This guide explains how to update existing utopia websites.

v3.0.0

The 3.0.x series is considered a development release while the protocol HTTP application and controller interfaces stabilize.

• Breaking Require Ruby 3.3 or later.
• Breaking Replace the Rack-centric application boundary with class Utopia::Application and Protocol::HTTP::Middleware. Applications now use config/application.rb and config/serve.rb instead of config.ru.
• Breaking Separate complete protocol responses from semantic controller results. Use respond! with a Protocol::HTTP::Response, or succeed! with a value serialized by module Utopia::Controller::Respond.
• Parse request bodies at the controller layer using protocol-content, independently of URL query parameters.
• Resolve localization through immutable request preferences, avoiding repeated internal controller requests.
• Split redirection handling into focused middleware for rewrites, moved resources, directory indexes, and error documents.
• Security Fix handling of redirects that start with // to prevent open redirect vulnerabilities.
• Normalize request URLs using Protocol::URL and use structured paths throughout the middleware stack.
• Resolve static files through encoded URL paths, with improved HEAD, range, and validator handling.
• Use protocol-media and protocol-http for response and language negotiation, removing the http-accept dependency.

v2.31.0

• Add agent context.
• Better simplification of relative paths, e.g. ../../foo is not modified to foo.
• Move top level classes into class Middleware in their respective namespaces.
• Move Utopia::Responder into Utopia::Controller layer.

v2.30.1

• Minor compatibility fixes.

v2.27.0

• Improved error logging using Console gem.
• Only install npm ls --production dependencies into public/_components.