Mix Tasks Reference

This document provides a comprehensive reference for all AshTypescript Mix tasks.

Installation Commands

mix igniter.install ash_typescript

Automated installer that sets up everything you need to get started with AshTypescript.

Usage

# Basic installation (prompts for frontend framework)
mix igniter.install ash_typescript

# Full-stack React + TypeScript setup
mix igniter.install ash_typescript --framework react

# Vite bundler, or Inertia.js SSR setup
mix igniter.install ash_typescript --framework react --bundler vite
mix igniter.install ash_typescript --framework svelte --inertia

What It Does

The installer performs the following tasks:

1. Dependency Setup

   • Adds AshTypescript to your mix.exs dependencies
   • Runs mix deps.get to install the package

2. Configuration

   • Configures AshTypescript settings in config/config.exs
   • Sets default output paths and RPC endpoints

3. Manifest Module (required since 0.18)

   • Creates the app-wide manifest module (lib/my_app/ash_typescript_manifest.ex with use AshTypescript.Manifest, otp_app: :my_app)
   • Registers it via config :ash_typescript, manifest: MyApp.AshTypescriptManifest

4. RPC Controller

   • Creates RPC controller at lib/*_web/controllers/ash_typescript_rpc_controller.ex
   • Implements handlers for run and validate endpoints

5. Phoenix Router

   • Adds RPC routes to your Phoenix router
   • Configures /rpc/run and /rpc/validate endpoints

6. Frontend Setup (with --framework)

   • Sets up a complete TypeScript environment for the chosen framework
   • Configures esbuild or Vite for frontend builds
   • Creates welcome page with getting started guide
   • Installs necessary npm packages

Options

When to Use

• ✅ New projects starting with AshTypescript
• ✅ Adding AshTypescript to existing Phoenix projects
• ✅ Setting up frontend with React integration
• ❌ Projects that already have AshTypescript installed

This is the recommended approach for initial setup.

Code Generation Commands

mix ash.codegen

Recommended approach for most projects. This command runs code generation for all Ash extensions in your project, including AshTypescript.

# Generate types for all Ash extensions including AshTypescript
mix ash.codegen --dev

For detailed information about mix ash.codegen, see the Ash documentation.

mix ash_typescript.codegen

Generate TypeScript types, RPC clients, Zod schemas, and validation functions only for AshTypescript.

Usage

# Basic generation (AshTypescript only)
mix ash_typescript.codegen

# Custom RPC endpoints
mix ash_typescript.codegen \
  --run-endpoint "/api/rpc/run" \
  --validate-endpoint "/api/rpc/validate"

# Check if generated code is up to date (CI usage)
mix ash_typescript.codegen --check

# Preview generated code without writing to file
mix ash_typescript.codegen --dry-run

# Override the configured output location for a single run
mix ash_typescript.codegen --output assets/js
mix ash_typescript.codegen --output myfolder/client.ts

Options

Output file locations are otherwise controlled by configuration (output_file and friends) — see the Configuration Reference.

Overriding the output location

--output overrides the output_file config, which is the path every other generated file auto-derives from. A path ending in .ts is used verbatim as the RPC functions file; anything else is treated as a directory and gets ash_rpc.ts appended.

# both write assets/js/ash_rpc.ts + assets/js/ash_types.ts (+ ash_zod.ts / ash_valibot.ts when enabled)
mix ash_typescript.codegen --output assets/js
mix ash_typescript.codegen --output assets/js/ash_rpc.ts

# writes myfolder/client.ts + myfolder/ash_types.ts (+ ash_zod.ts / ash_valibot.ts when enabled)
mix ash_typescript.codegen --output myfolder/client.ts

Paths set explicitly via types_output_file, zod_output_file, valibot_output_file, routes_output_file or typed_channels_output_file still win over the derived location — --output only moves the paths that were left to auto-derive. To relocate everything, either leave those keys unset or override them in config as well.

Generated Content

When run, this task generates:

1. TypeScript Interfaces

   • Resource types with field metadata
   • Schema types for field selection
   • Result types for each action

2. RPC Client Functions

   • HTTP-based RPC functions for each action
   • Channel-based RPC functions (if enabled)
   • Type-safe configuration objects

3. Filter Input Types

   • Comprehensive filter operators
   • Type-safe query building
   • Nested relationship filtering

4. Zod / Valibot Validation Schemas (if enabled)

   • Runtime type validation (into ash_zod.ts / ash_valibot.ts)
   • Schema for each resource
   • Nested validation support

5. Form Validation Functions

   • Client-side validation helpers
   • Error message handling
   • Field-level validation

6. Typed Query Constants

   • Pre-configured field selections
   • SSR-optimized types
   • Type-safe result extraction

7. Custom Type Imports

   • Imports for custom types
   • Integration with external types
   • Type mapping support

8. Typed Controller Route Helpers (if configured)

   • Path helpers for all routes
   • Typed async fetch functions for mutation routes
   • Input types from route arguments
   • See Typed Controllers for details

Examples

Basic Generation:

mix ash_typescript.codegen

Custom RPC Endpoints:

mix ash_typescript.codegen \
  --run-endpoint "/api/rpc/run" \
  --validate-endpoint "/api/rpc/validate"

CI Check:

# In CI pipeline - fails if generated code is out of date
mix ash_typescript.codegen --check

Preview Without Writing:

# See what would be generated
mix ash_typescript.codegen --dry-run | less

When to Use

• ✅ Want to run codegen specifically for AshTypescript
• ✅ Need custom output paths or endpoints
• ✅ Debugging generated TypeScript code
• ✅ CI/CD pipelines with --check flag
• ❌ Have other Ash extensions that need codegen (use mix ash.codegen)

Test Environment Code Generation

For projects using test-only resources (common in library development), use the test environment:

# Generate types in test environment
MIX_ENV=test mix ash_typescript.codegen

# Or use the test.codegen alias (if defined)
mix test.codegen

Setting Up Test Codegen Alias

Add to your mix.exs:

# In your project/0 function, add preferred_envs to cli/0:
def cli do
  [
    preferred_envs: [
      "test.codegen": :test
    ]
  ]
end

# In your aliases:
defp aliases do
  [
    "test.codegen": "ash_typescript.codegen",
    # ... other aliases
  ]
end

This ensures mix test.codegen always runs in the test environment without needing MIX_ENV=test.

Workflow Integration

Development Workflow

# 1. Make changes to resources or domain configuration
vim lib/my_app/resources/todo.ex

# 2. Generate TypeScript types
mix ash.codegen --dev

# 3. Verify TypeScript compilation (in frontend directory)
cd assets && npm run typecheck

# 4. Run tests
mix test

CI/CD Workflow

# In your CI pipeline (.github/workflows/ci.yml, etc.)

# Check generated code is up to date
mix ash_typescript.codegen --check

# If out of date, the task raises Ash.Error.Framework.PendingCodegen,
# listing the files whose generated content differs from disk

Example GitHub Actions:

- name: Check TypeScript codegen
  run: mix ash_typescript.codegen --check

- name: Type check generated code
  run: |
    cd assets
    npm run typecheck

Pre-commit Hook

Add to .git/hooks/pre-commit:

#!/bin/bash
# Regenerate TypeScript on commit
mix ash_typescript.codegen --check || {
  echo "TypeScript code out of date. Regenerating..."
  mix ash_typescript.codegen
  git add assets/js/ash_*.ts
}

Troubleshooting

Common Issues

"No :manifest module configured for AshTypescript"

Problem: The task raises because no manifest module is registered — either the config is missing, or the module (and the config that points at it) only exists in another Mix environment.

Solution: Ensure config :ash_typescript, manifest: MyApp.AshTypescriptManifest is set and the module exists (see Configuration Reference). For projects with test-only resources, run in the correct MIX_ENV:

# Wrong - uses dev environment
mix ash_typescript.codegen

# Correct - uses test environment for test resources
MIX_ENV=test mix ash_typescript.codegen

Generated code doesn't compile

Problem: TypeScript compilation fails after generation.

Solution: Check for:

1. Invalid field names (use field name mapping)
2. Custom types not defined in imported modules
3. Missing type mapping overrides for dependency types

See Configuration Reference for field name mapping and type overrides.

Changes not reflected

Problem: Made changes to resources but generated TypeScript unchanged.

Solution:

1. Recompile Elixir code: mix compile --force
2. Regenerate TypeScript: mix ash_typescript.codegen
3. Verify output file path matches configuration

Permission errors

Problem: Cannot write to output file.

Solution: Check file permissions and directory structure:

# Ensure directory exists
mkdir -p assets/js

# Check permissions
ls -la assets/js

# Fix if needed
chmod 755 assets/js

See Also

• Configuration Reference - Configure code generation
• Installation - Initial setup guide
• Troubleshooting Reference - Common problems and solutions