create-app

Use this skill when creating a new Hanami 2.x application.

Core principle: hanami new generates a production-ready application structure with slices, ROM, and dry-system preconfigured.

---

Quick Reference

---

Core Rules

1. Generate the application:

   hanami new my_app --database=postgres
   cd my_app

2. Generated directory layout:

   my_app/
   ├── app/                    # Default application slice
   │   ├── actions/           # Action classes
   │   ├── views/             # View classes
   │   ├── templates/         # HTML/JSON templates
   │   ├── relations/         # ROM Relations
   │   ├── repos/             # ROM Repositories
   │   └── entities/          # ROM Entities
   ├── config/
   │   ├── app.rb             # App class, slice registration, plugin config
   │   ├── routes.rb          # Root route and resource routing
   │   ├── settings.rb        # Typed environment variable declarations
   │   └── providers/         # External dependency providers
   ├── db/
   │   ├── migrate/           # Database migration files
   │   └── seeds.rb           # Seed data setup
   ├── slices/                # Modular slices (bounded contexts)
   ├── spec/
   ├── Gemfile
   ├── config.ru
   └── README.md

3. Environment detection:

   Hanami detects the environment via HANAMI_ENV:

   • development (default) — code reloading enabled
   • test — used by RSpec
   • production — code reloading disabled, logging to stdout

4. Initial configuration:

   # config/app.rb
   # frozen_string_literal: true
   
   module MyApp
     class App < Hanami::App
     end
   end

5. Database configuration is read from DATABASE_URL:

   DATABASE_URL=postgres://localhost/my_app_development

6. Install dependencies and set up the database:

   bundle install
   hanami db create      # Creates the database
   hanami db migrate     # Applies migrations
   hanami db version     # Verify migrations applied successfully

7. Run the development server:

   hanami dev

---

Common Mistakes & Red Flags

---

Integration