### Issues associated with this PR https://github.com/Azure/azure-sdk-for-js/issues/38757 https://github.com/Azure/azure-sdk-for-js/issues/38296 --------- Co-authored-by: Copilot <[email protected]> Co-authored-by: Copilot Autofix powered by AI <[email protected]>
6.0 KiB
Getting Started: Generate JavaScript/TypeScript DPG Libraries with TypeSpec
Before you start
⚠️ Ensure that your TypeSpec definition has been merged into the main branch of the Azure REST API specs repository before you begin.
For an overview of the review and release process for new libraries, visit: https://aka.ms/azsdk/dpcodegen.
If you have code generation queries, post them in the TypeSpec Discussion channel. Tag @DPG TypeScript for JavaScript/TypeScript-specific inquiries.
Join the JavaScript - Reviews channel for assistance with the API review process.
Prerequisites
- LTS versions of Node.js
- Install pnpm with the pnpm installation instructions.
- Install tsp-client dependencies with
npm --prefix eng/common/tsp-client ci
Set up your development environment
Follow the setup guide for environment prerequisites in the azure-sdk-for-js repository.
Identify your project's service and package name
The service name is a concise identifier for the Azure service and should be consistent across all SDK languages. It's typically the name of the directory in the azure-rest-api-specs repository containing your service's REST API definition.
The package name is used when publishing to npmjs. It usually follows the format @azure/{service-name} or @azure/{service-name}-{module} for services with multiple modules.
Structure your project
-
SDK Repo Root: the generated libraries should be in the azure-sdk-for-js repo, so fork and clone it in your local then the absolute path is called ${SDK_REPO_ROOT} folder.
-
Project Folder Structure: the typical structure is
sdk/{servicename}/{servicename}-{modulename}, e.g.,sdk/storage/storage-blob. That folder is under {SDK_REPO_ROOT} and will be your ${PROJECT_ROOT} folder. -
Package Name Convention: follow the format
@azure/{service-name}-{module}, like@azure/storage-blob.
Steps to generate DPG
-
Configure tspconfig.yaml in spec repository
In your specs repository, update or create
tspconfig.yamlto configure the TypeScript emitter. ReplaceYOUR_SERVICE_DIRECTORY,YOUR_SERVICE_FOLDERandYOUR_PACKAGE_NAMEwith your specific details.parameters: "service-dir": default: "YOUR_SERVICE_DIRECTORY" emit: ["@azure-tools/typespec-ts"] options: "@azure-tools/typespec-ts": emitter-output-dir: "{output-dir}/{service-dir}/YOUR_SERVICE_FOLDER" package-details: name: YOUR_PACKAGE_NAME description: "SHORT_DESCRIPTION" version: "1.0.0-beta.1" -
Generate code
Initialize a new TypeScript DPG library
For initial set up, use the
tsp-clientCLI tool to initialize the generation process. From the root of your localazure-sdk-for-jsrepository clone, run the following command, replacingYOUR_REMOTE_TSPCONFIG_URLwith the URL to your TypeSpec configuration file:npm --prefix eng/common/tsp-client exec --no -- tsp-client init -c YOUR_REMOTE_TSPCONFIG_URLIf you are generating the DPG library for Azure Cognitive Services Content Safety, and your TypeSpec configuration file is located at
https://github.com/Azure/azure-rest-api-specs/blob/46ca83821edd120552403d4d11cf1dd22360c0b5/specification/cognitiveservices/ContentSafety/tspconfig.yaml, you would initialize the library like this:npm --prefix eng/common/tsp-client exec --no -- tsp-client init -c https://github.com/Azure/azure-rest-api-specs/blob/46ca83821edd120552403d4d11cf1dd22360c0b5/specification/cognitiveservices/ContentSafety/tspconfig.yamlThis command sets up your local SDK repository with the necessary structure and files based on your
tspconfig.yamlfile and then generate SDKs with given url typespec.Re-generate an existing TypeScript DPG library
If you'd like to update/regenerate an existing SDK, go to your SDK folder and then update
tsp-location.yaml. You can refer to the tsp-location.yaml which describes the supported properties in the file.directory: specification/agrifood/DataPlane commit: b646a42aa3b7a0ce488d05f1724827ea41d12cf1 # the commit id you'd like to refer for generation repo: Azure/azure-rest-api-specsRun the
updatecommand from SDK directory (i.e sdk/agrifood/agrifood-farming) to re-generate the code:npm --prefix ../../../eng/common/tsp-client exec --no -- tsp-client update
NOTE The version of typespec-ts is configured in emitter-package.json and relevant lock file emitter-package-lock.json. Change them in local, if you would like to use a different version of typespec-ts.
After SDK generation
The generated code is not enough to release at once and you need to update it for better usage experience. Please follow steps after generation guide to check the code.