Utopia is a website generation framework which provides a robust set of tools to build highly complex dynamic websites. It uses the filesystem heavily for content and provides functions for interacting with files and directories as structure representing the website.

Features

• Designed for both content-based websites and applications. Does not depend on a database.
• Supports flexible content localization based on industry recommendations.
• Built directly on protocol-http with a small application and middleware interface.
• Low latency and high throughput. Capable of 10,000+ requests/second out of the box.

Usage

Please see the project documentation for more details.

• 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.

Releases

Please see the project releases for all releases.

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 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 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.

See Also

• XRB — Template and markup parsers, markup generation.
• Utopia::Gallery — A fast photo gallery based on libvips.
• Utopia::Project — A Ruby project documentation tool.
• Utopia::Analytics — Simple integration with Google Analytics.
• Samovar — Command line parser used by Utopia.
• Mapping — Provide structured conversions for web interfaces.

Examples

• Financier — A small business management platform.
• mail.oriontransfer.net - Mail server account management.
• www.codeotaku.com (source) — Personal website, blog.

Contributing

We welcome contributions to this project.

1. Fork it.
2. Create your feature branch (git checkout -b my-new-feature).
3. Commit your changes (git commit -am 'Add some feature').
4. Push to the branch (git push origin my-new-feature).
5. Create new Pull Request.

Running Tests

To run the test suite:

bundle exec sus

Making Releases

To make a new release:

bundle exec bake gem:release:patch # or minor or major

Developer Certificate of Origin

In order to protect users of this project, we require all contributors to comply with the Developer Certificate of Origin. This ensures that all contributions are properly licensed and attributed.

Community Guidelines

This project is best served by a collaborative and respectful environment. Treat each other professionally, respect differing viewpoints, and engage constructively. Harassment, discrimination, or harmful behavior is not tolerated. Communicate clearly, listen actively, and support one another. If any issues arise, please inform the project maintainers.