Getting started

Copy Markdown View Source

Install

Add caravela to your deps in mix.exs:

def deps do
  [
    {:caravela, "~> 0.13"},
    # Required for `mix caravela.gen.live` output (both `:live` and
    # `:rest` render modes mount through this package).
    {:caravela_svelte, "~> 0.1"}
  ]
end

Phoenix and ecto_sql are assumed to already be present in the host app; Caravela generates code against them. If you plan to generate GraphQL output, see generators for the additional optional deps.

1. Declare a domain

# lib/my_app/domains/library.ex
defmodule MyApp.Domains.Library do
  use Caravela.Domain

  entity :authors do
    field :name, :string, required: true
    field :bio, :text
    field :born, :date
  end

  entity :books do
    field :title, :string, required: true, min_length: 3
    field :isbn, :string, format: ~r/^\d{13}$/
    field :published, :boolean, default: false
    field :price, :decimal, precision: 10, scale: 2
  end

  entity :publishers do
    field :name, :string, required: true
    field :country, :string
  end

  relation :authors, :books, type: :has_many
  relation :books, :publishers, type: :belongs_to

  policy :books do
    allow :create, fn actor -> actor.role in [:admin, :editor] end
  end
end

See the DSL reference for every macro.

2. Generate the backend

mix caravela.gen MyApp.Domains.Library
# → Ecto schemas, a migration, a Phoenix context module, and JSON
#   controllers. A router snippet is printed for you to paste.

Or layer by layer:

mix caravela.gen.schema   MyApp.Domains.Library
mix caravela.gen.context  MyApp.Domains.Library
mix caravela.gen.api      MyApp.Domains.Library
mix caravela.gen.graphql  MyApp.Domains.Library
mix caravela.gen.live     MyApp.Domains.Library

All generators take --dry-run and --force. See generators for the full list.

3. Migrate and run

mix ecto.migrate
mix phx.server

curl -X POST localhost:4000/api/books \
  -H "content-type: application/json" \
  -d '{"title":"Test Title"}'
# → 201 Created on valid input, 403 if the policy denies create,
#   422 if the changeset fails validation or the hook rejects it.

Where to go next