Skip to content

Modular (DPG) Customization Guide

Jump to bottom
Timo van Veenendaal edited this page Dec 10, 2025 · 5 revisions

This document outlines the workflow for customizing Modular (DPG) generated SDKs using the JavaScript customization tool. This tool allows you to make alterations to the generated TypeScript code directly. The tool manages the regeneration process, applying your customizations to the new version of the generated code using a 3-way merge.

When should I use this tool?

The JavaScript customization tool described is intended as an escape hatch for customizations that cannot be implemented in TypeSpec. For information on using TypeSpec client.tsp for customizations, see the Azure TypeSpec documentation. If TypeSpec customization does not fulfil your needs, the customization workflow described here allows you to make more complex changes to the generated source code. This workflow should be used only with architect approval.

Folder Structure

The customization tool assumes you have the following folder structure:

my-sdk-package/
  generated/
    <generated source files (NO src/ underneath this path!)
  src/
    <generated code with hand-applied customizations>
  test/
    <tests run against code in src/>  
  README.md
  package.json
  (etc...)

The original generated code and the customized code live side-by-side in the package. The modified source code in the src/ directory is the source of truth and is what is ultimately built and shipped to customers. The generated code in generated/ is kept for reference and to help calculate the diff generated by your customizations when you regenerate.

Customization workflow

Making customizations is straightforward. Directly edit the code in the src/ folder with the customizations you need (rename/add/remove/modify functions, methods, exports, files...). Just treat it as if you're refactoring any other code.

Tip

You can make any customization you want, but it's a good idea to minimize and consolidate the changes that you do make: no reformatting, reordering, etc., outside of the customizations you are making. This will make your life easier when it comes time to regenerate.

If you are making a large number of additions (e.g. helper functions and types), it may be worth separating these to a different file and re-exporting them in the customized file instead of making the additions inline.

Once you are happy with your customizations, check everything in as normal (both the generated/ folder and the src/ folder). You are done!

Regeneration workflow

As the service specification changes, it will become necessary to update your library. This should start with regenerating the code under the generated/ folder. Leave these changes unstaged.

Note

It's important to leave the newly generated code unstaged at this time. The customization tool relies on this to rebase your customizations to the previous version onto the newly generated version.

Once you've done this, you can now run npx dev-tool customization apply-v2. This command will:

  • Determine the diff between the customized version of your code (in src/) and the previous version of the generated code (what was in generated/ before you ran the command to regenerate)
  • Attempt a three way merge of the customized code into the new version of the generated code, with the previous version of the generated code as the common parent. The result of the merge attempt will be output into the src/ folder (including any merge conflict markers)

If the merge was successful, there is no further work to do. If merge conflicts are present, this means that the changes in the generated code conflicted with your customizations. Resolve the conflicts as you would do for any other merge, taking parts from the new generated code and parts from the customized code as makes sense to you. After resolving the conflicts, the src/ folder should be the result of applying your customizations to the new version of the generated code.

Clone this wiki locally