# Generators and mix tasks
Caravela ships one mix task per generator, plus an all-in-one task for
the backend trio. All tasks accept `--dry-run` (print, don't write),
`--force` (overwrite without prompting), and `--output DIR` (write
under `DIR` instead of `File.cwd!()`).
| Task | What it generates |
|-------------------------------|----------------------------------------------------------------|
| `mix caravela.gen` | Schemas + migration + context + JSON controllers |
| `mix caravela.gen.schema` | Ecto schemas + one migration |
| `mix caravela.gen.context` | Phoenix context module |
| `mix caravela.gen.api` | JSON controllers + prints the router scope snippet |
| `mix caravela.gen.graphql` | Absinthe types + queries + mutations |
| `mix caravela.gen.live` | LiveViews + REST controllers + typed Svelte components + tests |
| `mix caravela.gen.auth` | Authentication stack for an `authenticatable` entity |
| `mix caravela.mcp` | Launch the MCP server ([see mcp.md](mcp.md)) |
| `mix caravela.check` | Unified validation oracle (format + compile + credo + tests) |
| `mix caravela.info` | Human-readable IR dump for a domain |
| `mix caravela.ir` | JSON IR dump for a domain |
All file paths use standard Phoenix conventions:
```
lib/my_app/library/book.ex # schema
lib/my_app/library.ex # context
lib/my_app_web/controllers/book_controller.ex # :rest entity controller
lib/my_app_web/schema/library_types.ex # GraphQL
lib/my_app_web/live/library/book_live/index.ex # :live entity
assets/svelte/library/BookIndex.svelte # Svelte (both modes)
assets/svelte/library/BookIndex.test.ts # Vitest smoke test
assets/svelte/types/library.ts # TypeScript
test/my_app_web/live/library/book_live_test.exs # :live ExUnit
test/my_app_web/controllers/book_controller_test.exs # :rest ExUnit
priv/repo/migrations/<ts>_create_library_tables.exs
```
Versioned domains nest a `v<n>/` segment in module names and file
paths; see [versioning](versioning.md).
## Flags specific to `mix caravela.gen.live`
- `--frontend MODE` — override every entity's declared render mode
(`live` or `rest`). Useful for previewing generator output for the
other transport without touching the DSL. See
[svelte frontend](livesvelte.md) for the per-entity declaration
(`entity :x, frontend: :rest do …`).
- `--no-tests` — skip emitting the ExUnit + Vitest test skeletons.
By default the generator writes one `<entity>_live_test.exs` per
`:live` entity, one `<entity>_controller_test.exs` per `:rest`
entity, and one `*.test.ts` colocated next to every Svelte file.
See [testing](testing.md).
- `--with-domain` — in addition to the three per-entity LiveViews
(`index`, `show`, `form`), also emit a `Caravela.Live.Domain`
companion module (e.g. `MyAppWeb.Library.BookLive.FormDomain`) and
generate `form.ex` from the Template-backed variant. Index and show
stay plain. Useful as an onramp to the [Live runtime](live_runtime.md).
Applies only to `:live` entities.
```bash
mix caravela.gen.live --with-domain MyApp.Domains.Library
# → lib/my_app_web/live/library/book_live/form.ex
# lib/my_app_web/live/library/book_live/form_domain.ex
mix caravela.gen.live --no-tests --frontend rest MyApp.Domains.Library
```
## Optional dependencies
Caravela's own deps are minimal (`ecto_sql`, `jason`). These are only
required if you use the corresponding generator:
```elixir
# GraphQL (mix caravela.gen.graphql)
{:absinthe, "~> 1.7"},
{:absinthe_plug, "~> 1.5"},
{:dataloader, "~> 2.0"},
# Svelte frontend (mix caravela.gen.live — both :live and :rest modes)
{:caravela_svelte, "~> 0.1"},
# Phoenix (any generator targeting web code)
{:phoenix, "~> 1.7"},
{:phoenix_live_view, "~> 1.0"},
{:postgrex, "~> 0.18"}
```
The mix tasks check at runtime and print a useful warning if a dep is
missing.
## Router registration
Caravela does not edit `router.ex` automatically. Drop one line into
your router and the `Caravela.Router` macro expands to the full
route list at compile time, reading the domain's IR:
```elixir
defmodule MyAppWeb.Router do
use Phoenix.Router
use Caravela.Router
import CaravelaSvelte.Router # needed only when any entity is :rest
scope "/", MyAppWeb.Library do
pipe_through :browser
caravela_routes MyApp.Domains.Library
end
end
```
`caravela_routes/1` emits `live` routes for `:live` entities,
`caravela_rest` routes for `:rest` entities (with `realtime: true`
when declared), and keeps version segments in module aliases so
Phoenix's scope-alias resolution continues to match
`MyAppWeb.V1.Library.BookLive.Index` under `version "v1"` domains.
`caravela_routes/2` accepts a `:session` option forwarded to
`live_session/3`, letting a group of `:live` entities share an
`on_mount` hook.
The JSON-API generator (`mix caravela.gen.api`) still prints a paste-
snippet for `resources` under `:api`, since it targets JSON-only
endpoints that don't go through `caravela_svelte`:
```elixir
scope "/api", MyAppWeb do
pipe_through :api
resources "/books", BookController, except: [:new, :edit]
end
```
See the [regeneration](regeneration.md) page for the sha256 header,
per-function `CUSTOM` blocks, and tail-marker semantics that make
re-runs safe.
## Render functions are pure
Every `Caravela.Gen.*.render/1,2` function is a pure function of the
compiled domain module — it builds a `{path, source}` tuple (or a list
of them) in memory and never touches the filesystem or starts Mix. The
mix tasks are thin CLI wrappers around these calls.
That means you can invoke a generator anywhere you have the domain
module loaded: from a test, from a Phoenix controller that previews
generator output, from an IEx session. Nothing special about the mix
entry point.
```elixir
domain = MyApp.Domains.Library.__caravela_domain__()
{path, src} = Caravela.Gen.Context.render(domain)
# `src` is the file contents; `path` is where the mix task *would*
# write it. Up to you whether to write, diff, or render inline.
```
## Deterministic migration output
`Caravela.Gen.Migration.render/2` stamps the current UTC time into the
migration filename prefix by default, so two back-to-back runs produce
different paths. For snapshot tests or demo pages that show generator
output side-by-side with a committed baseline, pin the prefix:
```elixir
Caravela.Gen.Migration.render(domain, timestamp: "00000000000000")
# → {"priv/repo/migrations/00000000000000_create_library_tables.exs", ...}
```
All other generators are already deterministic.