Coming from Rails?
If you already know Ruby on Rails, Marten will feel familiar in spirit. It provides a convention-oriented structure, models with validations and callbacks, migrations, and a batteries-included backend toolkit. Marten also draws from Django in areas like templates and applications. It is not a port of Rails though; it is designed around Crystal.
This guide maps Rails concepts to their Marten equivalents. For a hands-on introduction, you can continue with the tutorial once you have completed installation.
Concept map
| Rails | Marten | Learn more |
|---|---|---|
| ActiveRecord model | Marten::Model | ORM, validations, callbacks |
| Controller | Handler | Request processing |
| View (ERB/Haml) | Marten templates | Django-inspired syntax, not ERB |
routes.rb | config/routes.cr | Route maps and reverse URLs |
| Strong parameters / form objects | Schema | Input validation in handlers |
| Scaffold / resourceful routing | Generic handlers | List, detail, create, update, delete |
ActiveRecord::Relation | Query set | Filtering, ordering, aggregation |
| Migrations | Migrations | Auto-generated with genmigrations |
bin/rails | marten CLI | Project management commands |
config/application.rb / environments | config/settings/ | Per-environment configuration |
| Engine | Application | Reusable app packaged as a shard |
| Rack middleware | Middleware | Request/response pipeline |
| Authentication (eg. Devise) | Authentication | Optional --with-auth app |
session | Sessions | Persisted between requests (cookie store by default) |
flash | Flash store | One-request messages |
| I18n | Internationalization | YAML locales via crystal-i18n |
| Action Mailer | Emailing | Email classes and backends |
Rails.cache | Caching | Cache stores |
| Asset pipeline / Propshaft | Assets | Collected with collectassets |
| Generators | Generators | Models, handlers, schemas, etc. |
What works differently
Crystal, not Ruby
Crystal's syntax is Ruby-inspired, which can ease the transition, but Marten applications are compiled Crystal programs. You get static typing, compile-time checks, and native binaries. Types and nilability are explicit, and the compiler is part of your day-to-day feedback loop.
Handlers, not controllers
Rails controllers map to Marten handlers. Handlers receive a request object and return a response. You can use #get, #post, and other HTTP verb methods, or override #dispatch, instead of defining action methods on a controller. Handler callbacks replace much of what you might otherwise do with before_action.
Schemas instead of strong parameters
Request data is usually validated through schemas rather than strong parameters or ActiveModel form objects. Schemas declare fields and rules; handlers initialize and validate them against incoming data. Model validations remain on models.
Templates are not ERB
Marten templates use a Django-inspired language with tags, filters, and auto-escaping. They are not ERB templates. The mental model is closer to Django templates than to Rails views.
No built-in admin
Marten has no equivalent to tools like Rails Admin or ActiveAdmin out of the box. Admin interfaces are built with handlers and templates.
Dependencies and packaging
Gems map to Crystal shards declared in shard.yml. Reusable features are packaged as Marten applications, which play a similar role to Rails engines. Application routes can be included in the main routes map under a common prefix. The main application associated with the src/ folder is always available implicitly; only additional applications need to be listed in installed_apps.
Frontend is your choice
Marten is backend-oriented. It does not prescribe a JavaScript bundler or SPA architecture. You can use server-rendered templates, a separate frontend, or whichever frontend toolchain best fits your project.
Where to go next
- The installation guide will help you install Crystal and the Marten CLI
- The Applications guide explains how projects and apps are organized
- The models and handlers guides cover the core request and data flow
- The tutorial will walk you through building a small application
- Why Marten? compares Marten to other Crystal frameworks
Please refer to Acknowledgements for a deeper look at Marten's Rails lineage.