<!--
SPDX-FileCopyrightText: 2025 Torkild G. Kjevik
SPDX-FileCopyrightText: 2025 ash_typescript contributors <https://github.com/ash-project/ash_typescript/graphs/contributors>
SPDX-License-Identifier: MIT
-->
# Typed Controllers
Typed controllers are a simple abstraction that generates ordinary Phoenix controllers from a declarative DSL. The same DSL also enables generating TypeScript path helpers and typed fetch functions, giving you end-to-end type safety for controller-style routes.
## When to Use Typed Controllers
Typed controllers are especially useful for server-rendered pages or endpoints, for example with regards to cookie session management, and anything
else where an rpc action isn't a natural fit.
## Quick Start
### 1. Define a Typed Controller
Create a module that uses `AshTypescript.TypedController` and define your routes. The preferred syntax uses HTTP verb shortcuts (`get`, `post`, `patch`, `put`, `delete`):
```elixir
defmodule MyApp.Session do
use AshTypescript.TypedController
typed_controller do
module_name MyAppWeb.SessionController
get :auth do
run fn conn, _params ->
render(conn, "auth.html")
end
end
post :login do
argument :magic_link_token, :string, allow_nil?: false
argument :remember_me, :boolean
run fn conn, %{magic_link_token: token, remember_me: remember_me} ->
case MyApp.Auth.get_user_from_magic_link_token(token) do
{:ok, user} ->
conn
|> put_session(:user_id, user.id)
|> redirect(to: "/dashboard")
{:error, _} ->
conn
|> put_flash(:error, "Invalid token")
|> redirect(to: "/auth")
end
end
end
get :logout do
run fn conn, _params ->
conn
|> clear_session()
|> redirect(to: "/auth")
end
end
end
end
```
### 2. Add Routes to Your Phoenix Router
The `module_name` in the DSL determines the generated Phoenix controller module. Wire it into your router like any other controller:
```elixir
defmodule MyAppWeb.Router do
use Phoenix.Router
scope "/auth" do
pipe_through [:browser]
get "/", SessionController, :auth
post "/login", SessionController, :login
get "/logout", SessionController, :logout
end
end
```
### 3. Configure Code Generation
Add the typed controller configuration to your `config/config.exs`:
```elixir
config :ash_typescript,
typed_controllers: [MyApp.Session],
router: MyAppWeb.Router,
routes_output_file: "assets/js/routes.ts"
```
### 4. Generate TypeScript
Run the code generator:
```bash
mix ash.codegen
# or
mix ash_typescript.codegen
```
This generates a TypeScript file with path helpers and typed fetch functions:
```typescript
// assets/js/routes.ts (auto-generated)
/**
* Configuration options for typed controller requests
*/
export interface TypedControllerConfig {
headers?: Record<string, string>;
fetchOptions?: RequestInit;
customFetch?: (
input: RequestInfo | URL,
init?: RequestInit,
) => Promise<Response>;
}
export async function executeTypedControllerRequest(
url: string,
method: string,
actionName: string,
body: string | undefined,
config?: TypedControllerConfig,
): Promise<Response> {
const processedConfig = config || {};
const headers: Record<string, string> = {
"Content-Type": "application/json",
...processedConfig.headers,
};
const fetchFunction = processedConfig.customFetch || fetch;
const fetchInit: RequestInit = {
...processedConfig.fetchOptions,
method,
headers,
...(body !== undefined ? { body } : {}),
};
const response = await fetchFunction(url, fetchInit);
return response;
}
export function authPath(): string {
return "/auth";
}
export function loginPath(): string {
return "/auth/login";
}
export type LoginInput = {
magicLinkToken: string;
rememberMe?: boolean;
};
export async function login(
input: LoginInput,
config?: TypedControllerConfig,
): Promise<Response> {
return executeTypedControllerRequest(
"/auth/login", "POST", "login", JSON.stringify(input), config,
);
}
export function logoutPath(): string {
return "/auth/logout";
}
```
### 5. Use in Your Frontend
```typescript
import { authPath, login, logoutPath } from "./routes";
// GET routes generate path helpers
const authUrl = authPath(); // "/auth"
// POST/PATCH/PUT/DELETE routes generate typed async functions
const response = await login(
{ magicLinkToken: "my-token", rememberMe: true },
{ headers: { "X-CSRF-Token": csrfToken } },
);
const logoutUrl = logoutPath(); // "/auth/logout"
```
## DSL Reference
### `typed_controller` Section
| Option | Type | Required | Description |
|--------|------|----------|-------------|
| `module_name` | atom | Yes | The Phoenix controller module to generate (e.g., `MyAppWeb.SessionController`) |
| `namespace` | string | No | Default namespace for all routes in this controller. Can be overridden per-route. |
### Three Route Syntaxes
The DSL supports three ways to define routes:
**Verb shortcuts (preferred)** — the HTTP method is the entity name:
```elixir
get :auth do
run fn conn, _params -> render(conn, "auth.html") end
end
post :login do
run fn conn, _params -> handle_login(conn) end
argument :code, :string, allow_nil?: false
end
```
**Positional method arg** — method as second argument to `route`:
```elixir
route :logout, :post do
run fn conn, _params -> handle_logout(conn) end
end
```
**Default method** — `route` without method defaults to `:get`:
```elixir
route :home do
run fn conn, _params -> render(conn, "home.html") end
end
```
### Route Options
| Option | Type | Required | Default | Description |
|--------|------|----------|---------|-------------|
| name | atom | Yes | — | Controller action name (positional arg) |
| `method` | atom | No | `:get` | HTTP method: `:get`, `:post`, `:patch`, `:put`, `:delete`. Implicit with verb shortcuts. |
| `run` | fn/2 or module | Yes | — | Handler function or module |
| `description` | string | No | — | JSDoc description in generated TypeScript |
| `deprecated` | boolean or string | No | — | Mark as deprecated in TypeScript (`true` for default message, string for custom) |
| `see` | list of atoms | No | `[]` | Related route names for JSDoc `@see` tags |
| `namespace` | string | No | — | Namespace for this route (overrides controller-level namespace) |
| `zod_schema_name` | string | No | — | Override generated Zod schema name (avoids collisions with RPC) |
### `argument` Options
| Option | Type | Required | Default | Description |
|--------|------|----------|---------|-------------|
| name | atom | Yes | — | Argument name (positional arg) |
| type | atom or `{atom, keyword}` | Yes | — | Ash type (`:string`, `:boolean`, `:integer`, etc.) or `{type, constraints}` tuple |
| `constraints` | keyword | No | `[]` | Type constraints |
| `allow_nil?` | boolean | No | `true` | If `false`, argument is required |
| `default` | any | No | — | Default value |
## Route Handlers
### Inline Functions
The simplest approach — define the handler directly in the DSL:
```elixir
get :auth do
run fn conn, _params ->
render(conn, "auth.html")
end
end
```
### Handler Modules
For more complex logic, implement the `AshTypescript.TypedController.Route` behaviour:
```elixir
defmodule MyApp.Handlers.Login do
@behaviour AshTypescript.TypedController.Route
@impl true
def run(conn, %{magic_link_token: token}) do
case MyApp.Auth.get_user_from_magic_link_token(token) do
{:ok, user} ->
conn
|> Plug.Conn.put_session(:user_id, user.id)
|> Phoenix.Controller.redirect(to: "/dashboard")
{:error, _} ->
conn
|> Phoenix.Controller.put_flash(:error, "Invalid token")
|> Phoenix.Controller.redirect(to: "/auth")
end
end
end
```
Then reference it in the DSL:
```elixir
post :login do
argument :magic_link_token, :string, allow_nil?: false
run MyApp.Handlers.Login
end
```
Handlers **must** return a `%Plug.Conn{}` struct. Returning anything else results in a 500 error.
## Request Handling
When a request hits a typed controller route, AshTypescript automatically:
1. **Strips** Phoenix internal params (`_format`, `action`, `controller`, params starting with `_`)
2. **Normalizes** camelCase param keys to snake_case
3. **Extracts** only declared arguments (undeclared params are dropped)
4. **Validates** required arguments (`allow_nil?: false`) — missing args produce 422 errors
5. **Casts** values using `Ash.Type.cast_input/3` — invalid values produce 422 errors
6. **Dispatches** to the handler with atom-keyed params
### Error Responses
**422 Unprocessable Entity** (validation errors):
```json
{
"errors": [
{ "field": "code", "message": "is required" },
{ "field": "count", "message": "is invalid" }
]
}
```
All validation errors are collected in a single pass, so the client receives every issue at once.
**500 Internal Server Error** (handler doesn't return `%Plug.Conn{}`):
```json
{
"errors": [
{ "message": "Route handler must return %Plug.Conn{}, got: {:ok, \"result\"}" }
]
}
```
## Generated TypeScript
### GET Routes — Path Helpers
GET routes generate synchronous path helper functions:
```elixir
get :auth do
run fn conn, _params -> render(conn, "auth.html") end
end
```
```typescript
export function authPath(): string {
return "/auth";
}
```
### GET Routes with Arguments — Query Parameters
Arguments on GET routes become query parameters:
```elixir
get :search do
argument :q, :string, allow_nil?: false
argument :page, :integer
run fn conn, params -> render(conn, "search.html", params) end
end
```
```typescript
export function searchPath(query: { q: string; page?: number }): string {
const base = "/search";
const searchParams = new URLSearchParams();
searchParams.set("q", String(query.q));
if (query?.page !== undefined) searchParams.set("page", String(query.page));
const qs = searchParams.toString();
return qs ? `${base}?${qs}` : base;
}
```
### Mutation Routes — Typed Fetch Functions
POST, PATCH, PUT, and DELETE routes generate async fetch functions with typed inputs:
```elixir
post :login do
argument :code, :string, allow_nil?: false
argument :remember_me, :boolean
run fn conn, params -> handle_login(conn, params) end
end
```
```typescript
export type LoginInput = {
code: string;
rememberMe?: boolean;
};
export async function login(
input: LoginInput,
config?: TypedControllerConfig,
): Promise<Response> {
return executeTypedControllerRequest(
"/auth/login", "POST", "login", JSON.stringify(input), config,
);
}
```
The `TypedControllerConfig` interface and `executeTypedControllerRequest` helper are generated once at the top of the file and shared by all mutation functions. See [Lifecycle Hooks](#lifecycle-hooks) for how hooks integrate with this helper.
### Routes with Path Parameters
When a router path includes parameters (e.g., `/organizations/:org_slug`), they become a separate `path` parameter in the generated TypeScript. Every path parameter must have a matching `argument` in the route definition.
For GET routes, path params are interpolated into the path helper:
```elixir
get :settings do
argument :org_slug, :string
run fn conn, _params -> render(conn, "settings.html") end
end
```
Router:
```elixir
scope "/organizations/:org_slug" do
get "/settings", OrganizationController, :settings
end
```
Generated TypeScript (default `:object` style):
```typescript
export function settingsPath(path: { orgSlug: string }): string {
return `/organizations/${path.orgSlug}/settings`;
}
```
When a GET route has both path params and additional arguments, the path params are placed in a `path` object and the remaining arguments become query parameters:
```elixir
get :members do
argument :org_slug, :string
argument :role, :string
argument :page, :integer
run fn conn, params -> render(conn, "members.html", params) end
end
```
Router:
```elixir
scope "/organizations/:org_slug" do
get "/members", OrganizationController, :members
end
```
Generated TypeScript:
```typescript
export function membersPath(
path: { orgSlug: string },
query?: { role?: string; page?: number }
): string {
const base = `/organizations/${path.orgSlug}/members`;
const searchParams = new URLSearchParams();
if (query?.role !== undefined) searchParams.set("role", String(query.role));
if (query?.page !== undefined) searchParams.set("page", String(query.page));
const qs = searchParams.toString();
return qs ? `${base}?${qs}` : base;
}
```
For mutation routes, path params are separated from the request body input:
```elixir
patch :update_provider do
argument :provider, :string
argument :enabled, :boolean, allow_nil?: false
argument :display_name, :string
run fn conn, params -> handle_update(conn, params) end
end
```
Router:
```elixir
patch "/providers/:provider", SessionController, :update_provider
```
Generated TypeScript:
```typescript
export type UpdateProviderInput = {
enabled: boolean;
displayName?: string;
};
export async function updateProvider(
path: { provider: string },
input: UpdateProviderInput,
config?: TypedControllerConfig,
): Promise<Response> {
return executeTypedControllerRequest(
`/auth/providers/${path.provider}`, "PATCH", "updateProvider",
JSON.stringify(input), config,
);
}
```
Path parameters are excluded from the input type and placed in the `path` parameter.
### Function Parameter Order
Generated functions follow this parameter order:
1. **`path`** (if route has path params): `path: { param: Type }`
2. **`input`** (if route has non-path arguments): `input: InputType`
3. **`config`** (always optional): `config?: TypedControllerConfig`
## Multi-Mount Routes
When a controller is mounted at multiple paths, AshTypescript uses the Phoenix `as:` option to disambiguate:
```elixir
scope "/admin", as: :admin do
get "/auth", SessionController, :auth
post "/login", SessionController, :login
end
scope "/app", as: :app do
get "/auth", SessionController, :auth
post "/login", SessionController, :login
end
```
Generated TypeScript uses scope prefixes:
```typescript
// Admin scope
export function adminAuthPath(): string { return "/admin/auth"; }
export async function adminLogin(input: AdminLoginInput, config?: TypedControllerConfig): Promise<Response> { ... }
// App scope
export function appAuthPath(): string { return "/app/auth"; }
export async function appLogin(input: AppLoginInput, config?: TypedControllerConfig): Promise<Response> { ... }
```
If routes are mounted at multiple paths without unique `as:` options, codegen will raise an error with instructions to add them.
## Base Path
When your frontend is deployed separately from the backend (e.g., a standalone SPA calling an API on a different domain), you can configure a base path that is prepended to all generated route URLs:
```elixir
config :ash_typescript,
typed_controller_base_path: "https://api.example.com"
```
Generated TypeScript:
```typescript
const _basePath = "https://api.example.com";
export function authPath(): string {
return `${_basePath}/auth`;
}
export async function login(
input: LoginInput,
config?: TypedControllerConfig,
): Promise<Response> {
return executeTypedControllerRequest(
`${_basePath}/auth/login`, "POST", "login", JSON.stringify(input), config,
);
}
```
### Runtime Expressions
For dynamic base paths (e.g., from environment variables or app config), use `{:runtime_expr, "..."}`:
```elixir
config :ash_typescript,
typed_controller_base_path: {:runtime_expr, "AppConfig.getBasePath()"}
```
This embeds the expression directly in the generated code:
```typescript
const _basePath = AppConfig.getBasePath();
export function authPath(): string {
return `${_basePath}/auth`;
}
```
This follows the same `{:runtime_expr, "..."}` pattern used by [Dynamic RPC Endpoints](../reference/configuration.md#dynamic-rpc-endpoints).
When `typed_controller_base_path` is not set or is `""` (the default), no `_basePath` variable is generated and paths remain as plain strings (e.g., `"/auth"`).
## Paths-Only Mode
If you only need path helpers (no fetch functions), use the `:paths_only` mode:
```elixir
config :ash_typescript,
typed_controller_mode: :paths_only
```
This generates only path helpers for all routes, skipping input types and async functions. Useful when you handle mutations via a different client library or directly with `fetch`.
## Namespaces
Typed controllers support namespaces for organizing generated route helpers into separate files — the same concept as [RPC namespaces](../features/developer-experience.md#namespaces).
### Configuration
Set a default namespace at the controller level, and optionally override per-route:
```elixir
defmodule MyApp.Session do
use AshTypescript.TypedController
typed_controller do
module_name MyAppWeb.SessionController
namespace "auth" # Default namespace for all routes
get :auth do
run fn conn, _params -> render(conn, "auth.html") end
end
post :login do
run fn conn, _params -> handle_login(conn) end
argument :code, :string, allow_nil?: false
end
# This route goes into a different namespace
get :profile do
namespace "account" # Overrides the controller-level "auth"
run fn conn, _params -> render(conn, "profile.html") end
end
end
end
```
### Precedence
Route-level namespace overrides controller-level. Routes without any namespace go into the main routes file.
### Generated Output
With the example above, code generation produces:
- `routes.ts` — imports and re-exports from namespace files
- `namespace/auth.ts` — `authPath`, `login`, `LoginInput`, etc.
- `namespace/account.ts` — `profilePath`
## JSDoc `@see` Tags
Use the `see` option to add cross-references between related routes:
```elixir
post :login do
see [:auth, :logout]
argument :code, :string, allow_nil?: false
run fn conn, params -> handle_login(conn, params) end
end
```
Generated TypeScript includes `@see` tags in the JSDoc comments:
```typescript
/**
* POST /auth/login
* @see auth
* @see logout
*/
export async function login(input: LoginInput, config?: TypedControllerConfig): Promise<Response> {
...
}
```
The `@see` tags reference route names using their formatted output names (camelCase by default).
## Lifecycle Hooks
Lifecycle hooks let you intercept typed controller requests to add custom behavior like authentication headers, logging, or telemetry.
### Configuration
```elixir
config :ash_typescript,
typed_controller_before_request_hook: "RouteHooks.beforeRequest",
typed_controller_after_request_hook: "RouteHooks.afterRequest",
typed_controller_hook_context_type: "RouteHooks.RouteHookContext",
typed_controller_import_into_generated: [
%{import_name: "RouteHooks", file: "./routeHooks"}
]
```
### Hook Signatures
**beforeRequest** — called before the HTTP request, can modify config:
```typescript
export async function beforeRequest(
actionName: string,
config: TypedControllerConfig,
): Promise<TypedControllerConfig> {
// Add auth headers, set credentials, start timing, etc.
return {
...config,
fetchOptions: { ...config.fetchOptions, credentials: "include" },
};
}
```
**afterRequest** — called after the HTTP request completes:
```typescript
export async function afterRequest(
actionName: string,
response: Response,
config: TypedControllerConfig,
): Promise<void> {
// Log, measure timing, report errors, etc.
console.log(`[${actionName}] status: ${response.status}`);
}
```
### Hook Context
When hooks are enabled, the `TypedControllerConfig` interface includes an optional `hookCtx` field typed to your configured context type. This lets you pass per-request metadata (like timing flags or custom headers) through the request lifecycle:
```typescript
await login(
{ code: "abc123" },
{
hookCtx: { enableLogging: true, enableTiming: true },
},
);
```
## Custom Imports
Use `typed_controller_import_into_generated` to add custom TypeScript imports to the generated routes file. This is typically used alongside lifecycle hooks:
```elixir
config :ash_typescript,
typed_controller_import_into_generated: [
%{import_name: "RouteHooks", file: "./routeHooks"},
%{import_name: "Analytics", file: "./analytics"}
]
```
Generated output:
```typescript
import * as RouteHooks from "./routeHooks";
import * as Analytics from "./analytics";
```
## Zod Schema Generation
When `generate_zod_schemas: true` is configured, mutation routes also generate Zod validation schemas alongside their input types:
```typescript
export type LoginInput = {
code: string;
rememberMe?: boolean;
};
export const loginZodSchema = z.object({
code: z.string().min(1),
rememberMe: z.boolean().optional(),
});
```
The schemas use the same `zod_import_path` and `zod_schema_suffix` settings as RPC Zod schemas. The `z` import is automatically added to the generated routes file.
## Error Handling
### Error Handler
Configure a custom error handler to transform validation errors before they are sent to the client:
```elixir
config :ash_typescript,
typed_controller_error_handler: {MyApp.ErrorHandler, :handle, []}
```
The handler is called for each error (both 422 validation errors and 500 server errors). It receives the error map and a context map containing the route name and source module:
```elixir
defmodule MyApp.ErrorHandler do
def handle(error, %{route: route_name, source_module: module}) do
# Transform, log, or filter errors
# Return nil to suppress the error, or a modified error map
Map.put(error, :code, "VALIDATION_ERROR")
end
end
```
You can also pass a module implementing `handle_error/2`:
```elixir
config :ash_typescript,
typed_controller_error_handler: MyApp.ErrorHandler
```
### Show Raised Errors
By default, unhandled exceptions in route handlers return a generic "Internal server error" message. For development, you can expose the actual exception message:
```elixir
# config/dev.exs
config :ash_typescript,
typed_controller_show_raised_errors: true
```
When enabled, 500 responses include the real exception message instead of the generic one. **Do not enable in production.**
## Configuration Reference
| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `typed_controllers` | list of modules | `[]` | TypedController modules to generate route helpers for |
| `router` | module | `nil` | Phoenix router for path introspection |
| `routes_output_file` | string | `nil` | Output file path (when `nil`, route generation is skipped) |
| `typed_controller_mode` | `:full` or `:paths_only` | `:full` | Generation mode |
| `typed_controller_path_params_style` | `:object` or `:args` | `:object` | Path params style (see below) |
| `typed_controller_base_path` | string or `{:runtime_expr, string}` | `""` | Base URL prefix for all generated route URLs |
| `typed_controller_before_request_hook` | string or nil | `nil` | Function called before requests |
| `typed_controller_after_request_hook` | string or nil | `nil` | Function called after requests |
| `typed_controller_hook_context_type` | string | `"Record<string, any>"` | TypeScript type for hook context |
| `typed_controller_import_into_generated` | list of maps | `[]` | Custom imports for generated file |
| `typed_controller_error_handler` | MFA tuple, module, or nil | `nil` | Custom error transformation handler |
| `typed_controller_show_raised_errors` | boolean | `false` | Show exception messages in 500 responses |
| `enable_controller_namespace_files` | boolean | `false` | Generate separate files for namespaced routes |
| `controller_namespace_output_dir` | string or nil | `nil` | Directory for namespace files (defaults to `routes_output_file` dir) |
All three of `typed_controllers`, `router`, and `routes_output_file` must be configured for route generation to run.
Route helpers are part of AshTypescript's multi-file output architecture — shared types and Zod schemas are generated into separate files that both RPC and controller code import from. See [Configuration Reference — Multi-File Output](../reference/configuration.md#multi-file-output) for the full file layout.
### Path Params Style
Controls how path parameters are represented in all generated TypeScript functions (GET path helpers, mutation path helpers, and mutation action functions):
- **`:object`** (default) — path params are wrapped in a `path: { ... }` object:
```typescript
settingsPath(path: { orgSlug: string })
updateProvider(path: { provider: string }, input: UpdateProviderInput, config?)
```
- **`:args`** — path params are flat positional arguments:
```typescript
settingsPath(orgSlug: string)
updateProvider(provider: string, input: UpdateProviderInput, config?)
```
## Compile-Time Validation
AshTypescript validates typed controllers at compile time:
- **Unique route names** — no duplicates within a module
- **Handlers present** — every route must have a `run` handler
- **Valid argument types** — all types must be valid Ash types
- **Valid names for TypeScript** — route and argument names must not contain `_1`-style patterns or `?` characters
Path parameters are also validated at codegen time:
- Every `:param` in the router path must have a matching DSL argument
- **Always-present path params** must have `allow_nil?: false` — if a path parameter exists at every mount of a route, it is always provided by the router and can never be nil
- **Sometimes-present path params** must have `allow_nil?: true` — if a route is mounted at multiple paths and a parameter only appears at some mounts, it will be nil at the others
```elixir
# ✅ Correct — :provider is always a path param, so allow_nil?: false
get :provider_page do
argument :provider, :string, allow_nil?: false
run fn conn, _params -> render(conn, "provider.html") end
end
# ✅ Correct — :id is only a path param at /admin/pages/:id, nil at /app/pages
get :page do
argument :id, :string # allow_nil?: true (default) is correct here
run fn conn, _params -> render(conn, "page.html") end
end
```
## Next Steps
- [Configuration Reference](../reference/configuration.md) - Full configuration options
- [Mix Tasks Reference](../reference/mix-tasks.md) - Code generation commands
- [Troubleshooting](../reference/troubleshooting.md) - Common issues
