Skip to main content

Full‑Stack Movie Catalog (Shelf + Ormed)

Welcome to the Full-Stack Movie Catalog tutorial! In this guide, we'll build a complete web application from scratch using Ormed for database persistence and Shelf for the web server.

Prerequisites​

  • Quick Start
  • Basic familiarity with Dart and Shelf-style handlers

What You’ll Learn​

  • How Ormed integrates into a real server-side app architecture
  • How models, migrations, API routes, templates, storage, and tests fit together
  • How to run a production-style workflow from one tutorial path

How To Use This Guide​

Follow the pages in order. Each page has a concrete outcome that the next page depends on.

  1. Scaffold the project and initialize Ormed.
  2. Define models and generate ORM code.
  3. Apply migrations and seed initial data.
  4. Boot server routes and verify web/API behavior.
  5. Add templates, storage, and tests.
  6. Use the CLI/runbook for repeatable local workflows.

This isn't just a "Hello World" example. We'll build a meaningful application that includes:

  • Database Modeling: Defining structured data with relations.
  • Migrations & Seeding: Managing schema changes and initial data.
  • Web Routing: Handling both HTML pages and JSON API endpoints.
  • Template Rendering: Using Liquify for dynamic HTML.
  • File Storage: Handling image uploads for movie posters.
  • Structured Logging: Using Contextual for observable applications.
  • Testing: Ensuring reliability with unit and integration tests.
note

This guide is built from a runnable example project in packages/ormed/example/fullstack with region markers. Code blocks are embedded directly from the source to keep docs and code in sync.

What You’ll Build​

By the end of this tutorial, you'll have a movie catalog app with:

  • Server-rendered pages: Catalog, detail, edit, delete, and genre listings.
  • REST APIs: JSON endpoints for CRUD operations.
  • SQLite persistence: Using Ormed models and migrations.
  • Layout inheritance: Clean templates with shared layouts.
  • Asset uploads: Storing movie posters on disk.
  • Observability: Structured logging for easier debugging.

Fast Path (Command Order)​

If you want the shortest path first, run commands in this order while following the guide pages:

dart pub get
dart run build_runner build --delete-conflicting-outputs
dart run ormed_cli:ormed migrate
dart run ormed_cli:ormed seed
dart test
dart run bin/server.dart

Guide Map​

  1. Setup & Scaffolding - Project compiles, Ormed is initialized.
  2. Models & Codegen - Models + generated ORM/DTO artifacts exist.
  3. Migrations & Seed Data - Database can be rebuilt deterministically.
  4. Server & Web Routes - HTML and JSON route handlers are wired.
  5. JSON API - CRUD contract and payload/error behavior are explicit.
  6. Templates & Storage - UI templates and upload flow are integrated.
  7. Testing Strategy - Web/API/property/UI tests cover core flows.
  8. CLI & Runbook - Day-to-day operational workflow is repeatable.

Project Layout​

Understanding the project structure is key to navigating this tutorial:

example/fullstack/
├── bin/                # Entry points (server + CLI)
├── lib/src/            # App code (models, server, templates, storage)
├── templates/          # Liquify templates
├── uploads/            # Local storage for assets
└── test/               # HTTP + property tests