Documentation — Axint

Getting Started

Axint compiles TypeScript definitions to native Swift code for Apple platforms. Install and start building in seconds.

Installation

npm install -g @axint/compiler

Requires Node 22+ and TypeScript 5+

Your First Compilation

import { defineIntent, param } from "@axint/compiler";

export default defineIntent({
  name: "OpenApp",
  title: "Open App",
  description: "Opens the app from Siri or Shortcuts.",
  params: {},
});

Then run npx @axint/compiler compile to generate Swift.

Compilation Surfaces

Axint compiles to four Apple platform surfaces. Each uses a specific diagnostic code range.

defineIntent()

AX000–AX202

App Intents for Siri shortcuts and voice commands

defineView()

AX310–AX322

SwiftUI views and view hierarchies

defineWidget()

AX410–AX422

WidgetKit widgets for iOS/macOS lock screen

defineApp()

AX500–AX522

SwiftUI App lifecycle and main entry

App Intents (AX0xx)

Define Siri intents in TypeScript. Compiles to AppIntent protocol with parameters, error handling, and shortcuts integration.

Basic Intent

interface PayParams {
  recipient: string;
  amount: number;
}

defineIntent("PayUser", {
  params: PayParams,
  async handle(params) {
    await paymentService.send(params.recipient, params.amount);
    return { success: true, transactionId: "tx123" };
  },
});

Generated Swift Output

import AppIntents

struct PayUserIntent: AppIntent {
  static var title: LocalizedStringResource = "Pay User"

  @Parameter(title: "Recipient") var recipient: String
  @Parameter(title: "Amount") var amount: Double

  var display: some IntentResult & Opaque {
    .result()
  }

  @MainActor
  func perform() async throws -> some IntentResult & Opaque {
    let result = await paymentService.send(recipient: recipient, amount: amount)
    return .result()
  }

  static var parameterizedContexts: some ParameterizedIntentContext {
    IntentContext(byAskingUser: [\$parameters.recipient])
  }
}

AX100: Missing required handle() method

AX102: Parameter type not serializable (use string, number, boolean, Date)

SwiftUI Views (AX3xx)

Declare views with TypeScript JSX-like syntax. Compiles to idiomatic SwiftUI structs with state, modifiers, and bindings.

TypeScript View Definition

interface CardProps {
  title: string;
  subtitle: string;
  onTap?: () => void;
}

defineView("CardView", {
  props: CardProps,
  layout: (props) => (
    <VStack spacing={8}>
      <Text weight="bold" size="lg">{props.title}</Text>
      <Text color="secondary">{props.subtitle}</Text>
      <Button onTap={props.onTap}>Tap Me</Button>
    </VStack>
  ),
});

Generated Swift Code

import SwiftUI

struct CardView: View {
  let title: String
  let subtitle: String
  let onTap: (() -> Void)?

  var body: some View {
    VStack(spacing: 8) {
      Text(title)
        .font(.system(.body, design: .default))
        .fontWeight(.bold)

      Text(subtitle)
        .font(.body)
        .foregroundColor(.secondary)

      Button(action: { onTap?() }) {
        Text("Tap Me")
      }
    }
  }
}

AX310: Unsupported view type (use VStack, HStack, ZStack, Text, Image, Button)

AX312: Binding not used correctly (@ requires state declaration)

Widgets (AX4xx)

Define WidgetKit widgets with timeline entries and dynamic content. Compiles to WidgetConfiguration and TimelineProvider.

Widget Definition

interface WeatherEntry {
  temperature: number;
  condition: string;
  location: string;
}

defineWidget("WeatherWidget", {
  data: WeatherEntry,
  timeline: [
    { temperature: 72, condition: "sunny", location: "SF" },
    { temperature: 68, condition: "cloudy", location: "SF" },
  ],
  layout: (entry) => (
    <VStack>
      <Text>{entry.location}</Text>
      <Text size="lg" weight="bold">{entry.temperature}°</Text>
      <Text color="secondary">{entry.condition}</Text>
    </VStack>
  ),
  supportedFamilies: ["systemSmall", "systemMedium"],
});

AX410: Timeline must contain at least one entry

AX415: Invalid widget family (use systemSmall, systemMedium, systemLarge, systemExtraLarge)

App Lifecycle (AX5xx)

Define the SwiftUI App structure with WindowGroups, scene configuration, and app delegates.

App Definition

defineApp("MyApp", {
  scenes: [
    {
      type: "window",
      content: "RootView",
    },
  ],
  delegates: ["AppDelegate"],
  environment: {
    colorScheme: "dark",
  },
});

AX500: App name required

AX505: Scene content must reference a valid view

MCP Tools

Axint exposes 6 MCP tools for Claude, Cursor, and Windsurf. Use them to compile, validate, and understand diagnostics.

axint_compile

Compile TypeScript definition to Swift

{ "source": "defineIntent('MyIntent', {...})", "surface": "intent" }

axint_validate

Validate TypeScript syntax without compilation

{ "source": "defineIntent(...)" }

axint_explain_diagnostic

Get human-readable explanation for a diagnostic code

{ "code": "AX102" }

axint_list_diagnostics

List all possible diagnostics for a surface

{ "surface": "intent" }

axint_supported_types

Get list of supported parameter and property types

{ "surface": "intent" }

axint_compile_from_schema

Compile from JSON schema to Swift

{ "schema": { "type": "object", "properties": {...} }, "surface": "intent" }

Diagnostic Codes Reference

Axint uses diagnostic codes to report errors and warnings. Codes are grouped by surface and severity.

Intent Diagnostics (AX0xx)

AX100

Missing required handle() method in intent definition

AX101

Invalid parameter type (must be serializable)

AX102

Parameter lacks title or description

AX110

Return type not declared on handle() function

AX111

Async intent must use async handle()

AX120

Duplicate parameter names found

AX130

Invalid shortcut phrase format

AX140

Missing AppShortcutsProvider for shortcut export

View Diagnostics (AX3xx)

AX310

Unsupported view component type

AX311

Invalid view modifier

AX312

Binding (@State) not properly declared

AX313

View props must be immutable

AX314

Invalid spacing or padding value

AX320

Missing layout property

AX321

Layout must return a single View

AX322

Invalid color value

Widget Diagnostics (AX4xx)

AX410

Timeline must contain at least one entry

AX411

Invalid widget family specified

AX412

Widget data must be Codable

AX413

Missing TimelineProvider configuration

AX414

Invalid refresh interval

AX415

Unsupported widget family for platform

AX420

Widget kind must be unique

AX422

Preview configuration invalid

App Diagnostics (AX5xx)

AX500

App name is required

AX501

Invalid WindowGroup configuration

AX502

Scene content must reference a valid view

AX503

Missing app delegate when specified

AX510

Environment keys invalid

AX511

Color scheme must be light, dark, or nil

AX520

Invalid modifier chain in app configuration

AX522

App lifecycle callback missing implementation

CLI Reference

compile

npx @axint/compiler compile [options]

--input Input TypeScript file (default: src/intents)

--output Output Swift directory (default: generated/)

--surface Compilation surface (intent, view, widget, app)

--validate-only Skip code generation, report diagnostics only

validate

npx @axint/compiler validate <file>

Validate a single definition file without generating code. Exits with code 1 if errors found.

explain

npx @axint/compiler explain <diagnostic-code>

Print detailed explanation and fix suggestions for a diagnostic code.

version

npx @axint/compiler --version

Print installed Axint version.

Ready to compile?

Start building with Axint. Check out the GitHub repo for examples and source code.

GitHub Repository Back to Home