Dekiru.TypeScriptClientBuilder 6.2.0-preview.1

TypeScript Client Builder

A .NET library that automatically generates TypeScript client code and DTOs from ASP.NET Core controllers. Reduce boilerplate and keep your frontend and backend in sync.

Features

• Automatic Client Generation: Generates TypeScript HTTP client methods from your ASP.NET Core controllers
• DTO Export: Automatically exports C# DTOs to TypeScript interfaces
• Enum Support: Multiple enum export options (numbers, strings, unions, const enums)
• Type Safety: Full type safety between your C# API and TypeScript client
• Inheritance Support: Optional support for inheritance chains in generated types
• Customizable: Extensive configuration options for indentation, naming, and behavior
• Checksum Optimization: Skip regeneration when nothing has changed
• XML Documentation: Import your XML documentation comments into TypeScript
• Flexible Parameters: Support for named parameters, headers, event callbacks, and more

Installation

Install via NuGet:

dotnet add package Dekiru.TypeScriptClientBuilder

Or via Package Manager Console:

Install-Package Dekiru.TypeScriptClientBuilder

Quick Start

Basic Usage

Add the following to your ASP.NET Core application (typically in Program.cs):

using TypeScriptClientBuilder;

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddControllers();

var app = builder.Build();
app.MapControllers();

// Generate TypeScript client
ClientBuilder.Build(new ClientConfiguration
{
    Output = "ClientOutput"
});

app.Run();

This will scan all your controllers and generate TypeScript files in the ClientOutput directory.

Example Controller

[ApiController]
[Route("[controller]")]
public class WeatherForecastController : ControllerBase
{
    [HttpGet(Name = "GetWeatherForecast")]
    public IEnumerable<WeatherForecast> Get(CancellationToken cancellationToken)
    {
        // Your implementation
    }
}

This generates a TypeScript client with type-safe methods to call your API.

Configuration Options

ClientConfiguration

Example Configuration

ClientBuilder.Build(new ClientConfiguration
{
    Output = "wwwroot/api",
    CleanOutput = true,
    UseChecksum = true,
    XmlDocumentationFile = "bin/Debug/net8.0/MyApi.xml",
    EnumType = EnumTypes.Strings | EnumTypes.Union,
    ConvertNullablePropsToOptional = true,
    UseNamedParameters = true,
    Indentation = new Indentation 
    { 
        Character = ' ', 
        Size = 2 
    },
    LoggingCallback = message => Console.WriteLine($"[ClientBuilder] {message}")
});

Attributes

Controller & Method Attributes

[ClientBuilderAttribute]

Configure client generation at controller or method level:

[ClientBuilder(ClientBuilderSettings.AddHeader | ClientBuilderSettings.AddEventCallback)]
public class MyController : ControllerBase
{
    [ClientBuilder(ClientBuilderSettings.OmitHeader)]
    public IActionResult MyMethod() { }
}

[ClientBuilderIgnore]

Exclude controllers, methods, properties, or parameters from generation:

[ClientBuilderIgnore]
public class InternalController : ControllerBase { }

[ClientBuilderMethodName]

Override the generated method name:

[ClientBuilderMethodName("fetchWeather")]
public IActionResult GetWeather() { }

[ClientBuilderReturnsUrl] / [ClientBuilderRedirect]

Control file download behavior (GET requests only):

[ClientBuilderReturnsUrl]
public FileResult DownloadFile() { }

[AddQueryParameter]

Add query parameters without declaring them in the method:

[AddQueryParameter("version", typeof(int))]
public IActionResult Get() { }

Type Attributes

[UnionType]

Generate string union types:

public class Model
{
    [UnionType("success", "error", "pending")]
    public string Status { get; set; }
}

Generates: status: "success" | "error" | "pending"

[KeyOf]

Generate keyof types:

public class Model
{
    [KeyOf(typeof(User))]
    public string Field { get; set; }
}

Generates: field: keyof User

[TypedIdOf]

Override property type:

public class Model
{
    [TypedIdOf(typeof(User))]
    public int UserId { get; set; }
}

[Partial]

Generate Partial<T> types:

public IActionResult Update([Partial] User user) { }

[Nullable] / [Optional]

Mark properties as nullable or optional:

public class Model
{
    [Nullable]
    public string Name { get; set; }
    
    [Optional]
    public int? Age { get; set; }
}

Supported Frameworks

• .NET 8.0
• .NET 9.0
• .NET 10.0

Development

Building

dotnet build

Running Sample

The Sample project demonstrates the library's features:

cd Sample
dotnet run

Check the Output directory for generated TypeScript files.

Publishing to NuGet (Internal use only)

1. Update version in Source/TypeScriptClientBuilder.csproj:

   <BaseVersion>6.2.0</BaseVersion>
   <PreviewVersion>-preview.1</PreviewVersion>
   

   Preview versions will have -preview.x suffix, while stable releases will leave the PreviewVersion empty.

2. Commit and push changes

3. Run the DevOps pipeline

4. Package will appear on nuget.org within a few minutes

License

MIT

Authors

Dekiru Solutions