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]>
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
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:
- Generate package code with TypeSpec.
- Build the package.
- Generate and run tests (optional, with warnings displayed if they fail).
- Generate samples, if enabled.
- Create or update the
CHANGELOG.md. - Bump the version according to the Azure SDK for JS policy.
- Generate or update
ci.mgmt.ymlorci.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
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.