AshTypescript

🔥 Automatic TypeScript type generation for Ash resources and actions

Generate type-safe TypeScript clients directly from your Elixir Ash resources, ensuring end-to-end type safety between your backend and frontend. Never write API types manually again.

✨ Features

• 🔥 Zero-config TypeScript generation - Automatically generates types from Ash resources
• 🛡️ End-to-end type safety - Catch integration errors at compile time, not runtime
• ⚡ Smart field selection - Request only needed fields with full type inference
• 🎯 RPC client generation - Type-safe function calls for all action types
• 📡 Phoenix Channel support - Generate channel-based RPC functions for real-time applications
• 🪝 Lifecycle hooks - Inject custom logic before/after requests (auth, logging, telemetry, error tracking)
• 🏢 Multitenancy ready - Automatic tenant parameter handling
• 📦 Advanced type support - Enums, unions, embedded resources, and calculations
• 📊 Action metadata support - Attach and retrieve additional context with action results
• 🔧 Highly configurable - Custom endpoints, formatting, and output options
• 🧪 Runtime validation - Zod schemas for runtime type checking and form validation
• 🔍 Auto-generated filters - Type-safe filtering with comprehensive operator support
• 📋 Form validation - Client-side validation functions for all actions
• 🎯 Typed queries - Pre-configured queries for SSR and optimized data fetching
• 🎨 Flexible field formatting - Separate input/output formatters (camelCase, snake_case, etc.)
• 🔌 Custom HTTP clients - Support for custom fetch functions and request options (axios, interceptors, etc.)
• 🏷️ Field/argument name mapping - Map invalid TypeScript identifiers to valid names

⚡ Quick Start

Get up and running in under 5 minutes:

# Basic installation
mix igniter.install ash_typescript

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

1. Add Resource Extension

defmodule MyApp.Todo do
  use Ash.Resource,
    domain: MyApp.Domain,
    extensions: [AshTypescript.Resource]

  typescript do
    type_name "Todo"
  end

  attributes do
    uuid_primary_key :id
    attribute :title, :string, allow_nil?: false
    attribute :completed, :boolean, default: false
  end
end

2. Configure Domain

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

  typescript_rpc do
    resource MyApp.Todo do
      rpc_action :list_todos, :read
      rpc_action :create_todo, :create
      rpc_action :get_todo, :get
    end
  end
end

3. Generate Types & Use

mix ash.codegen --dev

import { listTodos, createTodo } from './ash_rpc';

// ✅ Fully type-safe API calls
const todos = await listTodos({
  fields: ["id", "title", "completed"],
  filter: { completed: false }
});

const newTodo = await createTodo({
  fields: ["id", "title", { user: ["name", "email"] }],
  input: { title: "Learn AshTypescript", priority: "high" }
});

🎉 That's it! Your TypeScript frontend now has compile-time type safety for your Elixir backend.

👉 For complete setup instructions, see the Getting Started Guide

📚 Documentation

Tutorials

• Getting Started - Complete installation and setup guide
• React Setup - Full Phoenix + React + TypeScript integration

How-To Guides

• Basic CRUD Operations - Create, read, update, delete patterns
• Field Selection - Advanced field selection and nested relationships
• Error Handling - Comprehensive error handling strategies
• Custom Fetch Functions - Using custom HTTP clients and request options

Topics

• Lifecycle Hooks - Inject custom logic (auth, logging, telemetry)
• Phoenix Channels - Real-time WebSocket-based RPC actions
• Embedded Resources - Working with embedded data structures
• Union Types - Type-safe union type handling
• Multitenancy - Multi-tenant application support
• Action Metadata - Attach and retrieve action metadata
• Form Validation - Client-side validation functions
• Zod Schemas - Runtime validation with Zod

Reference

• Configuration - Complete configuration options
• Mix Tasks - Available Mix tasks and commands
• Troubleshooting - Common issues and solutions

🏗️ Core Concepts

AshTypescript bridges the gap between Elixir and TypeScript by automatically generating type-safe client code:

1. Resource Definition - Define Ash resources with attributes, relationships, and actions
2. RPC Configuration - Expose specific actions through your domain's RPC configuration
3. Type Generation - Run mix ash.codegen to generate TypeScript types and RPC functions
4. Frontend Integration - Import and use fully type-safe client functions in your TypeScript code

Type Safety Benefits

• Compile-time validation - TypeScript compiler catches API misuse before runtime
• Autocomplete support - Full IntelliSense for all resource fields and actions
• Refactoring safety - Rename fields in Elixir, get TypeScript errors immediately
• Living documentation - Generated types serve as up-to-date API documentation

🚀 Example Repository

Check out the AshTypescript Demo by Christian Alexander featuring:

• Complete Phoenix + React + TypeScript integration
• TanStack Query for data fetching
• TanStack Table for data display
• Best practices and patterns

📋 Requirements

• Elixir 1.15 or later
• Ash 3.0 or later
• Phoenix (for RPC controller integration)
• Node.js 16+ (for TypeScript)

🤝 Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes with tests
4. Ensure all tests pass (mix test)
5. Run code formatter (mix format)
6. Commit your changes (git commit -m 'Add amazing feature')
7. Push to the branch (git push origin feature/amazing-feature)
8. Open a Pull Request

Please ensure:

• All tests pass
• Code is formatted with mix format
• Documentation is updated for new features
• Commits follow conventional commit format

📄 License

This project is licensed under the MIT License - see the MIT.txt file for details.

🆘 Support

• Documentation: https://hexdocs.pm/ash_typescript
• GitHub Issues: https://github.com/ash-project/ash_typescript/issues
• Discord: Ash Framework Discord
• Forum: Elixir Forum - Ash Framework

---