Skip to content

Client Emitters

How to Use Emitters to Generate HTTP Clients from TypeSpec

Section titled “How to Use Emitters to Generate HTTP Clients from TypeSpec”

Introduction

Section titled “Introduction”

This guide will walk you through the process of using different client emitters (JavaScript, Python, Java, C#) to generate HTTP clients from TypeSpec. Please note that all client emitters are currently in preview and are subject to changes in future versions.

By following this guide, you will learn:

  1. How to set up client emitters in package.json.
  2. Update the client emitter configurations in tspconfig.yaml.
  3. How to generate HTTP clients for each specific programming language.

Location of All Client Emitters

Section titled “Location of All Client Emitters”

The client emitters are defined in the package.json file within your project.

Emitter NameLanguageVersion
@typespec/http-client-jsJavaScript
@typespec/http-client-pythonPython
@typespec/http-client-javaJava
@typespec/http-client-csharpC#

Below is an example of the package.json snippet where client emitters are defined:

  "dependencies": {
    "@typespec/http-client-csharp": "^0.1.9-alpha.20250113.2",
    "@typespec/http-client-java": "^0.1.9",
    "@typespec/http-client-python": "^0.6.6",
    "@typespec/http-client-js": "^0.38.1",
  }

Client Emitter Settings

Section titled “Client Emitter Settings”

This part provides an overview of the common and language-specific settings for each client emitter. These settings are stored in the tspconfig.yaml file.

Common Configuration Options

Section titled “Common Configuration Options”

The below option applies to all client emitters.

  • emitter-output-dir: Defines where the generated SDK files will be stored.

JavaScript Client Emitter Settings

Section titled “JavaScript Client Emitter Settings”

JavaScript generally requires minimal configuration. However, it is recommended to provide packageDetails for package metadata, which is used in package.json and README.md files.

packageDetails

Section titled “packageDetails”

Provide the metadata for package.json, README.md information.

PropertyDescription
namePackage name used in package.json
descriptionPackage description used in package.json file
versionDetailed version for your package, the default value is 1.0.0-beta.1

Example configuration:

packageDetails:
  name: "${your_package_name}"
  version: 1.0.0

Java Client Emitter Settings

Section titled “Java Client Emitter Settings”

Prerequisites

Section titled “Prerequisites”

Before using the Java client emitter, ensure the following dependencies are installed:

  • Java 17 or later - Download here
    (Verify installation with java --version)
  • Maven - Download here
    (Verify installation with mvn --version)

C# Client Emitter Settings

Section titled “C# Client Emitter Settings”

Before using the C# client emitter, ensure that the .NET 8.0 SDK (or higher) is installed. Full configuration options can be found in the C# Client Emitter README

JavaScript Client Emitter Example

Section titled “JavaScript Client Emitter Example”

Step 1: Install Dependencies

Section titled “Step 1: Install Dependencies”

Add the following dependencies to your package.json file:

"dependencies": {
  "@typespec/http-client-js": "^0.38.1"
}

Run the following command to install the dependencies:

Terminal window
tsp install

Step 2: Update Configuration

Section titled “Step 2: Update Configuration”

Update your tspconfig.yaml file with the following configuration:

emit:
  - "@typespec/http-client-js"
options:
  "@typespec/http-client-js":
    emitter-output-dir: "{project-root}/clients/javascript"
    packageDetails:
      name: "your_package_name"
      version: 1.0.0

Step 3: Generate Client

Section titled “Step 3: Generate Client”

Run the following command to generate the JavaScript client:

Terminal window
tsp compile {path to main.tsp}/main.tsp

Python Client Emitter Example

Section titled “Python Client Emitter Example”

Step 1: Install Dependencies

Section titled “Step 1: Install Dependencies”

Add the following dependencies to your package.json file:

"dependencies": {
  "@typespec/http-client-python": "^0.6.6"
}

Run the following command to install the dependencies:

Terminal window
tsp install

Step 2: Update Configuration

Section titled “Step 2: Update Configuration”

Update your tspconfig.yaml file with the following configuration:

emit:
  - "@typespec/http-client-python"
options:
  "@typespec/http-client-python":
    emitter-output-dir: "{project-root}/clients/python"

Step 3: Generate Client

Section titled “Step 3: Generate Client”

Run the following command to generate the Python client:

Terminal window
tsp compile {path to main.tsp}/main.tsp

Java Client Emitter Example

Section titled “Java Client Emitter Example”

Step 1: Install Dependencies

Section titled “Step 1: Install Dependencies”

Add the following dependencies to your package.json file:

"dependencies": {
  "@typespec/http-client-java": "^0.1.9"
}

Run the following command to install the dependencies:

Terminal window
tsp install

Step 2: Update Configuration

Section titled “Step 2: Update Configuration”

Update your tspconfig.yaml file with the following configuration:

emit:
  - "@typespec/http-client-java"
options:
  "@typespec/http-client-java":
    emitter-output-dir: "{project-root}/clients/java"

Step 3: Generate Client

Section titled “Step 3: Generate Client”

Run the following command to generate the Java client:

Terminal window
tsp compile {path to main.tsp}/main.tsp

C# Client Emitter Example

Section titled “C# Client Emitter Example”

Step 1: Install Dependencies

Section titled “Step 1: Install Dependencies”

Add the following dependencies to your package.json file:

"dependencies": {
  "@typespec/http-client-csharp": "^0.1.9-alpha.20250113.2"
}

Run the following command to install the dependencies:

Terminal window
tsp install

Step 2: Update Configuration

Section titled “Step 2: Update Configuration”

Update your tspconfig.yaml file with the following configuration:

emit:
  - "@typespec/http-client-csharp"
options:
  "@typespec/http-client-csharp":
    emitter-output-dir: "{project-root}/clients/dotnet"

Step 3: Generate Client

Section titled “Step 3: Generate Client”

Run the following command to generate the C# client:

Terminal window
tsp compile {path to main.tsp}/main.tsp

Running Language-Specific Emitters in CLI

Section titled “Running Language-Specific Emitters in CLI”

  1. Ensure that your package.json file is correctly configured to include the necessary dependencies for running the emitters

  2. Update the tspconfig.yaml file for properly configured for the language-specific emitter.

    emit:
      - "@typespec/http-client-csharp"
      - "@typespec/http-client-java"
      - "@typespec/http-client-python"
      - "@typespec/http-client-js"
    options:
      "@typespec/http-client-csharp":
        emitter-output-dir: "{project-root}/clients/dotnet"
      "@typespec/http-client-java":
        emitter-output-dir: "{project-root}/clients/java"
      "@typespec/http-client-python":
        emitter-output-dir: "{project-root}/clients/python"
      "@typespec/http-client-js":
        emitter-output-dir: "{project-root}/clients/javascript"

  3. Once the package.json and tspconfig.yaml files are updated, you need to install all required dependencies by running the following command in the project root:

    Terminal window
    tsp install

  4. Run the emitter to compile your TypeScript code into the desired language. Use the following command to trigger the emitter and compile your project:

    Terminal window
    tsp compile {path to main.tsp}/main.tsp

Disclaimer

Section titled “Disclaimer”