Files
azure-sdk-for-js/documentation/Generate-code-from-TypeSpec.md
Timo van VeenendaalGitHubgithub-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>Copilot
5501306aeb [docs] Fix documentation inconsistencies across documentation/ folder (#38220)
I reviewed and these mostly look good IMO. From the Agentic Workflow's
issue #38215.

- Fix incorrect pnpm install command (@pnpm → pnpm) in
Generate-code-from-TypeSpec.md
- Remove invalid 'npm install -g common/tools/dev-tool' from
RLC-Swagger-quickstart.md and steps-after-generations.md
- Update @azure/test-utils-perf references to correct
@azure-tools/test-perf package name in writing-performance-tests.md
- Update Mocha/Chai patterns to Vitest patterns in
Quickstart-on-how-to-write-tests.md (import from vitest, use TestInfo
instead of mocha Context, arrow functions instead of function
expressions)
- Update npm run build/test to pnpm build/test in
migrating-to-typespec.md


Fixes #38215

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
Co-authored-by: Copilot <[email protected]>
2026-04-21 10:28:12 -07:00

6.2 KiB

Getting Started: Generate JS SDK with TypeSpec

Before you Start

TypeScript Azure SDK Design Guidelines is the overall design guideline of the client SDK.

Prerequisites

  • LTS versions of Node.js
  • Git
  • Local Clone of Rest API Spec Repo Fork
    • If you don't already have a fork, Fork the Rest API Spec Repo.
    • Clone your fork of the repo.
        git clone https://github.com/{YOUR_GITHUB_USERNAME}/azure-rest-api-specs.git
      
  • Local Clone of JS Language Repo Fork
    • If you don't already have a fork, Fork the JS Repo.

    • Clone your fork of the repo.

        git clone https://github.com/{YOUR_GITHUB_USERNAME}/azure-sdk-for-js.git
      

Generate SDK

Use TypeSpec defined in REST API specifications

It is recommended to configure TypeSpec package on REST API specifications. Please refer to these guidelines.

How to configure tspconfig.yaml

You can reference these two config files to configure the Modular or RLC package:

Please make sure service-dir, emitter-output-dir, package-details, flavor(for typespec-ts) is correctly configured. experimental-extensible-enums is the optional config.The is-modular-library option is true by default, if you want to generate RLC libraries for data-plane SDKs, you must add is-modular-library: false in your tspconfig.yaml.

  • "parameters.service-dir.default" would be sdk/<service>
  • "options.@azure-tools/typespec-ts.emitter-output-dir" would be {output-dir}/{service-dir}/<module>

SDK module would be generated under the SDK project folder at sdk/<service>/<module>.

Generate Code with code-gen-pipeline tool (recommend)

Notice These steps are to generate code using the local spec repo. If you want to generate code with the github url, please refer Generate Code with tsp-client tool

Install dependencies to use code-gen-pipeline,

npm --prefix eng/common/tsp-client ci
npm install -g pnpm
npm --prefix eng/tools/js-sdk-release-tools ci

Create a local json file named generatedInput.json with content similar to that shown below

  {
    "dryRun": false,
    "specFolder": <your-local-spec-repo-path>,
    "headSha": <commit-id-you-want-to-generate-from>,
    "repoHttpsUrl": "https://github.com/Azure/azure-rest-api-specs",
    "relatedTypeSpecProjectFolder": [
    "specification/SERVICE_DIRECTORY_NAME/PACKAGE_DIRECTORY_NAME/"
    ]
  }

Run the command

npm --prefix eng/tools/js-sdk-release-tools exec --no -- code-gen-pipeline --inputJsonPath=<path-to-generatedInput.json> --outputJsonPath=<path-to-generatedOutput.json> --typespecEmitter=@azure-tools/typespec-ts --local

path-to-generatedOutput.json is the detailed information of generated package, you can ignore it without pipeline. generateOutput.json is to show us the location of generated artifact and any other messages.

This command will automatically:

  1. Generate package code with TypeSpec.
  2. Build the package.
  3. Generate and run tests (optional, with warnings displayed if they fail).
  4. Generate samples, if enabled.
  5. Create or update the CHANGELOG.md.
  6. Bump the version according to the Azure SDK for JS policy.
  7. Generate or update ci.mgmt.yml or ci.yml (if the package is new).

After all the steps finished, you can prepare the release for this generation. See Prepare Release

Generate Code with tsp-client tool

To reduce workload and unnecessary mistakes, it is recommended to use the simple method from the previous section. Only if you are clear about what you are doing and the method from the previous section does not meet your needs, should you consider using the method below.

Install tsp-client CLI tool

npm --prefix eng/common/tsp-client ci

For initial set up, from the root of the SDK repo, call

npm --prefix eng/common/tsp-client exec --no -- tsp-client init -c <url-to-tspconfig>

For updating TypeSpec generated SDK, call below in the SDK module folder (sdk/<service>/<module>) where tsp-location.yaml exists

npm --prefix ../../../eng/common/tsp-client exec --no -- tsp-client update

Notice If you use tsp-client to generate code and your generated SDK is new, you need to do one extra thing:

1: You should add ci.yml or ci.mgmt.yml under sdk/<service>/<module. ci.yml is for Data Plane SDKs and ci.mgmt.yml is for Mgmt Plane SDKs. See Create/Update the ci.yaml

Build

See steps-after-generations.

After all the steps finished, you can prepare the release PullRequest for this generation. See Prepare Release

Prepare Release

Prepare your SDK for release. The necessary approvals, guidance for testing, documentation, and release pipelines is described in your release plan. More information about the Azure SDK Release Tool is here.