Files
Timo van VeenendaalandGitHub fd8f1db3d3 [dev-tool] Remove v1 customization tool (#37306)
### Packages impacted by this PR

- `@azure-tools/dev-tool`
- Packages using the customization workflow

### Issues associated with this PR

- Resolves #36012 

### Describe the problem that is addressed by this PR

The v1 customization tool is deprecated and not used by any existing
packages other than the template. This PR cleans up dev-tool to remove
it in favor of the v2 customization tool that is actually being used. As
part of this:

- Migrated `template-dpg` package to use Customization v2
- Added a `dev-tool customization init` command that sets up a package
for customization
- Removed the old `dev-tool customization apply` command logic. Calling
`dev-tool customization apply` now runs the v2 logic instead.
- Added a warning to `dev-tool customization apply-v2` to say that it
will be removed soon. `apply-v2` now just aliases to `apply`. (TODO:
remove it once we have updated our automation and docs)
- Moved the Modular Customization Guide wiki page into a doc under
`documentation/` so that AI can see it (TODO after merge: remove the
wiki page and update the AKA link).
2026-02-18 13:56:21 -08:00

4.2 KiB

Modular (DPG) Customization Guide

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.

Before You Customize

Before customizing generated code, consider whether your change should be made in TypeSpec (client.tsp) instead. TypeSpec customizations are cleaner and survive regeneration. See the TypeSpec Client Customizations Reference for available decorators like @@clientName, @@access, etc.

Setting Up for Customization

If your package has not been set up for customization yet, run the following command from the package directory:

npx dev-tool customization init

This will copy the contents of src/ into generated/, establishing the baseline for the customization workflow. The command will fail if a generated/ folder already exists (meaning customization is already set up).

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

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.