Coming from Django?
If you already know Django, many Marten ideas will feel familiar. Marten follows a similar Model, Handler, and Template structure and borrows conventions from Django's apps, migrations, templates, and generic views. It is not a port of Django though; it is designed around Crystal's type system and compilation model.
This guide maps Django concepts to their Marten equivalents. For a hands-on introduction, you can continue with the tutorial once you have completed installation.
Concept map
| Django | Marten | Learn more |
|---|---|---|
| Model | Marten::Model | ORM, validations, callbacks |
| View (function or class-based) | Handler | Request processing |
| Template (Django template language) | Marten templates | Django-inspired syntax |
urls.py | config/routes.cr | Route maps and reverse URLs |
Form / ModelForm | Schema | Input validation in handlers |
| Generic class-based views | Generic handlers | List, detail, create, update, delete |
QuerySet | Query set | Filtering, ordering, aggregation |
| Migrations | Migrations | Auto-generated with genmigrations |
manage.py | marten CLI | Project management commands |
settings.py | config/settings/ | Per-environment configuration |
INSTALLED_APPS | installed_apps | Applications and reusable apps |
| Middleware | Middleware | Request/response pipeline |
django.contrib.auth | Authentication | Optional --with-auth app |
django.contrib.sessions | Sessions | Persisted between requests (cookie store by default) |
django.contrib.messages | Flash store | One-request messages |
| Translation / i18n | Internationalization | YAML locales via crystal-i18n |
send_mail | Emailing | Email classes and backends |
cache framework | Caching | Cache stores |
static / collectstatic | Assets | Collected with collectassets |
What works differently
Crystal comes first
Marten is a Crystal framework. Even when APIs look Django-like, you will write Crystal code with static typing, compile-time checks, macros, and native compilation. If Crystal is new to you, you may want to skim the Crystal language reference alongside this documentation.
Handlers, not views
In Django, "views" process requests and return responses. In Marten, this role is filled by handlers. A handler is a class that receives a request and returns a response. HTTP verbs map to methods such as #get and #post, or to an overridden #dispatch method. Handler callbacks can be used for logic that would otherwise live in a view's dispatch method or in middleware.
Schemas instead of forms
User input is usually validated through schemas rather than Django forms. Schemas define fields and validation rules, and handlers bind them to incoming request data. They are not model-bound like ModelForm classes; model-level validation still lives on models.
No built-in admin
Django's automatic admin interface has no direct equivalent in Marten. You can build admin-style interfaces with handlers, templates, and generic handlers, or integrate a dedicated frontend.
Dependencies and packaging
Python packages map to Crystal shards declared in shard.yml. Reusable Marten functionality is often packaged as applications, which play a similar role to Django apps distributed as installable packages. Unlike INSTALLED_APPS, the main application associated with the src/ folder is always available implicitly; only additional applications need to be listed in installed_apps.
Compile-time feedback
Many mistakes surface at compile time rather than at runtime. This is usually a good thing: the compiler can catch issues early when refactoring models, handlers, and schemas.
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 Django lineage.