Skip to content

Latest commit

 

History

History
120 lines (76 loc) · 6.5 KB

DPG-quickstart.md

File metadata and controls

120 lines (76 loc) · 6.5 KB

Getting Started: Generate JavaScript/TypeScript DPG Libraries with TypeSpec

Before you start

⚠️ Important: Only proceed with DPG code generation for JavaScript/TypeScript if you have been explicitly instructed to do so by the AZSDK Architecture Board. Otherwise, please use the RLC Quickstart Guide.

⚠️ 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

  • Node.js 18 or later.
  • Install Rush with npm install -g @microsoft/rush.
  • Install tsp-client with npm install -g @azure-tools/typespec-client-generator-cli

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

  1. 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.

  2. 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.

  3. Package Name Convention: follow the format @azure/{service-name}-{module}, like @azure/storage-blob.

Steps to generate DPG

  1. Configure tspconfig.yaml in spec repository

    In your specs repository, update or create tspconfig.yaml to configure the TypeScript emitter. Replace YOUR_SERVICE_DIRECTORY, YOUR_SERVICE_FOLDER and YOUR_PACKAGE_NAME with your specific details.

    parameters:
  "service-dir":
    default: "YOUR_SERVICE_DIRECTORY"

emit: ["@azure-tools/typespec-ts"]

options:
  "@azure-tools/typespec-ts":
    package-dir: "YOUR_SERVICE_FOLDER"
    isModularLibrary: true
    packageDetails:
      name: YOUR_PACKAGE_NAME
      description: "SHORT_DESCRIPTION"
      version: "1.0.0-beta.1"

  2. Generate code

    Initialize a new TypeScript DPG library

    For initial set up, use the tsp-client CLI tool to initialize the generation process. From the root of your local azure-sdk-for-js repository clone, run the following command, replacing YOUR_REMOTE_TSPCONFIG_URL with the URL to your TypeSpec configuration file:

    tsp-client init -c YOUR_REMOTE_TSPCONFIG_URL

    If 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:

    tsp-client init -c https://github.com/Azure/azure-rest-api-specs/blob/46ca83821edd120552403d4d11cf1dd22360c0b5/specification/cognitiveservices/ContentSafety/tspconfig.yaml

    This command sets up your local SDK repository with the necessary structure and files based on your tspconfig.yaml file 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-specs

    Run the update command from SDK directory (i.e sdk/agrifood/agrifood-farming) to re-generate the code:

    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.

  3. Edit rush.json

    As the libraries in azure-sdk-for-js repository are managed by rush, you need to add an entry in rush.json under projects section for the first time to make sure it works. For example:

        {
      "packageName": "@azure/agrifood-farming",
      "projectFolder": "sdk/agrifood/agrifood-farming",
      "versionPolicyName": "client"
    },

    Here you also need to replace the packageName, projectFolder into your own services'.

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.