Skip to content
Cratis Cratis Cratis

Getting Started

This guide covers the installation and basic setup of the Cratis Arc proxy generator.

Package Dependency

Section titled “Package Dependency”

To enable proxy generation, add a reference to the Cratis.Arc.ProxyGenerator.Build NuGet package to your project:

<PackageReference Include="Cratis.Arc.ProxyGenerator.Build" Version="1.0.0" />

Important: All projects that contain controllers, commands, or queries should reference this package, as the proxy generation runs as part of the compilation process.

Required Configuration

Section titled “Required Configuration”

Configure the proxy generator by adding MSBuild properties to your .csproj file:

<PropertyGroup>
    <CratisProxiesOutputPath>$(MSBuildThisFileDirectory)../Web</CratisProxiesOutputPath>
</PropertyGroup>
  • CratisProxiesOutputPath: Specifies where the generated TypeScript files will be written. This should typically point to your frontend project directory.

Note: The proxy generator uses incremental generation by default — only files whose content has changed are written to disk, and timestamps of unchanged files are preserved. This means committed proxies will not be modified by a build unless their source types actually change. See Configuration - Output Deletion Behavior for details.

Frontend Prerequisites

Section titled “Frontend Prerequisites”

The generated proxies depend on the @cratis/arc NPM package. Install it in your frontend project:

Terminal window
npm install @cratis/arc

Build Integration

Section titled “Build Integration”

The proxy generation runs automatically during the build process. Simply build your project:

Terminal window
dotnet build

The generator will:

  1. Load your compiled assembly
  2. Discover controllers, commands, and queries
  3. Analyze parameter types and return values
  4. Generate TypeScript proxies with proper typing
  5. Create index files for easy importing
  6. Maintain the folder structure based on namespaces

What Gets Generated

Section titled “What Gets Generated”

The proxy generator creates TypeScript proxies for:

  • Commands: Both controller-based and model-bound approaches. See Commands documentation for implementation details.
  • Queries: Single model, enumerable, and observable queries. See Queries documentation for implementation details.
  • Types: Complex types used as parameters or return values
  • Enums: Enumerations referenced by commands or queries
  • Identity Details: Types from IProvideIdentityDetails<TDetails> implementations

Next Steps

Section titled “Next Steps”