Configuration Reference

This document provides a comprehensive reference for all AshTypescript configuration options.

Application Configuration

Configure AshTypescript in your config/config.exs file:

# config/config.exs
config :ash_typescript,
  # File generation (multi-file architecture)
  output_file: "assets/js/ash_rpc.ts",
  types_output_file: nil,             # Auto-derives as ash_types.ts in output_file dir
  zod_output_file: nil,               # Auto-derives as ash_zod.ts in output_file dir

  # RPC endpoints
  run_endpoint: "/rpc/run",
  validate_endpoint: "/rpc/validate",

  # Field formatting
  input_field_formatter: :camel_case,
  output_field_formatter: :camel_case,

  # Multitenancy
  require_tenant_parameters: false,

  # Zod schema generation
  generate_zod_schemas: false,
  zod_import_path: "zod",
  zod_schema_suffix: "ZodSchema",

  # Validation functions
  generate_validation_functions: false,

  # Phoenix channel-based RPC actions
  generate_phx_channel_rpc_actions: false,
  phoenix_import_path: "phoenix",

  # Custom type imports
  import_into_generated: [],

  # Type mapping overrides
  type_mapping_overrides: [],

  # TypeScript type for untyped maps
  untyped_map_type: "Record<string, any>",

  # RPC resource warnings
  warn_on_missing_rpc_config: true,
  warn_on_non_rpc_references: true,

  # RPC namespace files
  enable_namespace_files: false,      # Generate separate files for namespaced RPC actions
  namespace_output_dir: nil,          # Directory for RPC namespace files (defaults to output_file dir)

  # Typed channel event subscriptions
  typed_channels: [],
  typed_channels_output_file: nil,

  # Typed controllers
  typed_controllers: [],
  router: nil,
  routes_output_file: nil,
  typed_controller_mode: :full,
  typed_controller_path_params_style: :object,
  typed_controller_base_path: "",             # Base URL prefix for all generated route URLs
  enable_controller_namespace_files: false,  # Generate separate files for namespaced routes
  controller_namespace_output_dir: nil,       # Directory for controller namespace files

  # Typed controller lifecycle hooks
  typed_controller_before_request_hook: nil,
  typed_controller_after_request_hook: nil,
  typed_controller_hook_context_type: "Record<string, any>",
  typed_controller_import_into_generated: [],

  # Typed controller error handling
  typed_controller_error_handler: nil,
  typed_controller_show_raised_errors: false,

  # Dev codegen behavior
  always_regenerate: false,

  # Get action behavior
  not_found_error?: true,

  # Developer experience - JSDoc
  add_ash_internals_to_jsdoc: false,
  source_path_prefix: nil,

  # Developer experience - Manifest
  manifest_file: nil,
  add_ash_internals_to_manifest: false

Multi-File Output

AshTypescript generates multiple TypeScript files, each with a specific responsibility:

types_output_file and zod_output_file auto-derive from the output_file directory — set output_file and the others follow. Override individually if needed.

Quick Reference

Lifecycle Hook Configuration

See Lifecycle Hooks and Typed Controllers for complete documentation.

Domain Configuration

Configure RPC actions and typed queries in your domain modules:

defmodule MyApp.Domain do
  use Ash.Domain, extensions: [AshTypescript.Rpc]

  typescript_rpc do
    resource MyApp.Todo do
      # Standard CRUD actions
      rpc_action :list_todos, :read
      rpc_action :get_todo, :get
      rpc_action :create_todo, :create
      rpc_action :update_todo, :update
      rpc_action :destroy_todo, :destroy

      # RPC action options
      rpc_action :list_limited, :read, allowed_loads: [:user]
      rpc_action :list_no_filter, :read, enable_filter?: false
      rpc_action :list_no_sort, :read, enable_sort?: false

      # Typed queries for SSR
      typed_query :dashboard_todos, :read do
        ts_result_type_name "DashboardTodo"
        ts_fields_const_name "dashboardTodoFields"
        fields [:id, :title, :priority, %{user: [:name]}]
      end
    end
  end
end

RPC Action Options

See RPC Action Options for complete documentation.

Dynamic RPC Endpoints

For separate frontend projects, use runtime expressions:

config :ash_typescript,
  # Environment variables
  run_endpoint: {:runtime_expr, "process.env.RPC_RUN_ENDPOINT || '/rpc/run'"},

  # Vite environment variables
  # run_endpoint: {:runtime_expr, "import.meta.env.VITE_RPC_RUN_ENDPOINT || '/rpc/run'"},

  # Custom functions
  # run_endpoint: {:runtime_expr, "MyAppConfig.getRunEndpoint()"}

RPC Resource Warnings

AshTypescript provides compile-time warnings for configuration issues:

Missing RPC Configuration Warning

Appears when resources have AshTypescript.Resource extension but are not in any typescript_rpc block.

Non-RPC References Warning

Appears when RPC resources reference other resources that are not configured as RPC resources.

To disable warnings:

config :ash_typescript,
  warn_on_missing_rpc_config: false,
  warn_on_non_rpc_references: false

Always Regenerate Mode

By default, mix ash_typescript.codegen --check compares the generated output against existing files and raises Ash.Error.Framework.PendingCodegen if they differ. This is useful for CI but in development—especially when using AshPhoenix.Plug.CheckCodegenStatus—you may want to skip the diff check and always write the generated files.

# config/dev.exs
config :ash_typescript, always_regenerate: true

When enabled, --check mode will write files directly instead of comparing, so the PendingCodegen error page is never shown during development.

Typed Channel Configuration

Configure typed channels to generate TypeScript event subscription helpers from Ash PubSub publications. Both typed_channels and typed_channels_output_file must be configured for generation to run.

config :ash_typescript,
  typed_channels: [MyApp.OrgChannel, MyApp.ActivityChannel],
  typed_channels_output_file: "assets/js/ash_typed_channels.ts"

Channel types (branded types, payload aliases, event maps) are appended to the shared types file (ash_types.ts). Channel functions (factory, subscription helpers) go into typed_channels_output_file and import their types from ash_types.ts.

See Typed Channels for complete documentation.

Typed Controller Configuration

Configure typed controllers to generate TypeScript path helpers and typed fetch functions for Phoenix controller routes. All three settings (typed_controllers, router, routes_output_file) must be configured for route generation to run.

config :ash_typescript,
  # List of TypedController modules
  typed_controllers: [MyApp.Session],

  # Phoenix router for path introspection
  router: MyAppWeb.Router,

  # Output file for generated route helpers
  routes_output_file: "assets/js/routes.ts",

  # Generation mode (optional)
  typed_controller_mode: :full,              # :full (default) or :paths_only
  typed_controller_path_params_style: :object, # :object (default) or :args
  typed_controller_base_path: "",            # Base URL prefix (string or {:runtime_expr, "..."})

  # Namespace files (optional)
  enable_controller_namespace_files: false,  # Generate separate files per namespace
  controller_namespace_output_dir: nil,      # Directory for namespace files (defaults to routes_output_file dir)

  # Lifecycle hooks (optional)
  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"}
  ],

  # Error handling (optional)
  typed_controller_error_handler: {MyApp.ErrorHandler, :handle, []},
  typed_controller_show_raised_errors: false  # true only in dev

See Typed Controllers for complete documentation.

Detailed Documentation

For in-depth configuration guides, see:

• Custom Types - Custom Ash types with TypeScript integration
• Field Name Mapping - Mapping invalid field names
• Developer Experience - Namespaces, JSDoc, and manifest generation
• Lifecycle Hooks - HTTP and channel lifecycle hooks
• Phoenix Channels - Channel-based RPC configuration
• Typed Channels - Typed event subscriptions from PubSub
• Multitenancy - Tenant parameter configuration
• Form Validation - Zod schema configuration
• Typed Controllers - Controller route helpers

See Also

• Installation - Initial setup
• Mix Tasks Reference - Code generation commands
• Troubleshooting Reference - Common problems and solutions