Skip to content
Cratis

Proxy generator configuration

Configure generation through properties and items inside the existing .csproj’s Project element. The examples in these reference pages are project fragments, not standalone project files. Item Include values supply MSBuild identities; the generator consumes each item’s named metadata.

Choose a topic

Section titled “Choose a topic”
  • Basic options: output path, namespace segments, source-file grouping, decorators.
  • Library mode: collect models beyond endpoint references; separate CLI interface output.
  • Emit interfaces: plain interfaces with no decorators and no runtime dependency.
  • Proxy file suffix: name generated files Name.proxy.ts to tell them apart from hand-written TypeScript.
  • Type exclusions: omit types or namespace patterns.
  • Namespace roots: remap output folders without changing API routes.
  • Slice location: the module, feature and slice of each command and query, on the backend and on generated proxies.
  • Assembly-to-package mappings: import shared model packages.
  • Type mapping: primitive mappings and TypeToTsType overrides.
  • Routing: conventional model-bound route options and runtime alignment.
  • Output behavior: incremental writes, full deletion, and cleanup limitations.

Framework selection

Section titled “Framework selection”

React output is the default and is unchanged when this setting is omitted. For a non-React client, set:

<PropertyGroup>
  <CratisProxiesFramework>none</CratisProxiesFramework>
</PropertyGroup>

The executable accepts --framework=none or --framework=react; other values fail before generation. An MSBuild command-line override such as -p:CratisProxiesFramework=none takes precedence over the project setting.

none emits the same command, query and observable-query classes, metadata, routes, validation and models, but without React imports or hook helpers (use, paging, suspense and change-stream hooks). Use their imperative execute(), perform() and subscribe() APIs with @cratis/arc; @cratis/arc.react is not required by these proxies. Changing the selection invalidates incremental generation state. This setting is independent of CratisProxiesEmitInterfaces and does not turn runtime proxy classes into interfaces.

MSBuild reference

Section titled “MSBuild reference”
Property or item Default / required metadata Topic
CratisProxiesOutputPath Empty disables generation Basic
CratisProxiesSegmentsToSkip Empty resolves to 0 Basic
CratisProxiesUseSourceFileAsOutputFile Off unless true Basic
CratisProxiesLibraryMode false Library mode
CratisProxiesEmitInterfaces false Emit interfaces
CratisProxiesFramework react; none omits framework adapters Framework selection
CratisProxiesUseProxyFileSuffix false Proxy file suffix
ExcludeType item Include, TypeName Exclusions
ExcludeNamespace item Include, Namespace Exclusions
NamespaceRoot item Include, Namespace, Folder (may be empty) Namespace roots
AssemblyToPackageMapping item Include, Assembly, Package Package mappings
TypeToTsType item Include, TypeName, TsType; optional Package Type mapping
CratisProxiesSkipCommandNameInRoute false Routing
CratisProxiesSkipQueryNameInRoute false Routing
CratisProxiesApiPrefix api Routing
CratisProxiesIncremental true; skip discovery when inputs and recorded outputs match Output behavior
CratisProxiesSkipIndexGeneration Off unless true Output behavior
CratisProxiesSkipOutputDeletion true in MSBuild; direct executable differs Output behavior
CratisProxiesSkipFileIndexTracking false; setting true is currently ignored by the executable Output behavior

Community: Discord