add shopify tools type generation #6748

olavoasantos · 2026-01-08T19:00:36Z

WHY are these changes introduced?

Fixes https://github.com/shop/issues-admin-extensibility/issues/2126

Currently, developers building UI extensions with tools don't have TypeScript support for the shopify.tools.register API. This means they lose type safety when registering tool handlers, making it harder to catch errors at compile time and reducing the developer experience with no autocomplete or inline documentation.

WHAT is this pull request doing?

This PR adds automatic TypeScript type generation for Shopify tools in UI extensions. When a tools field is defined in an extension point configuration pointing to a tools.json file, the CLI will:

Parse the tools JSON file containing tool definitions with name, description, inputSchema, and optional outputSchema
Generate TypeScript interfaces from JSON schemas using json-schema-to-typescript
Create a typed ShopifyTools interface with properly typed register methods for each tool
Augment the extension's type definition to include shopify.tools with full type support

Summary of changes

Added json-schema-to-typescript dependency to @shopify/app
Created createToolsTypeDefinition() function in type-generation.ts
Updated createTypeDefinition() to accept optional tools type definitions
Modified ui_extension.ts to read tools files and generate corresponding types
Added warning messages when tools files are not found or fail to parse

Example generated types:

type MyToolInput = {
  query: string;
}
type MyToolOutput = {
  results: string[];
}

interface ShopifyTools {
  /**
   * Searches for products
   */
  register(name: 'my-tool', handler: (input: MyToolInput) => MyToolOutput | Promise<MyToolOutput>);
}

Changes summary:

How to test your changes?

Create a UI extension with a tools.json file:

[
  {
    "name": "search-products",
    "description": "Search for products by query",
    "inputSchema": {
      "type": "object",
      "properties": {
        "query": {"type": "string"}
      },
      "required": ["query"]
    },
    "outputSchema": {
      "type": "object",
      "properties": {
        "products": {"type": "array", "items": {"type": "string"}}
      }
    }
  }
]

Reference it in your extension config:

[[extensions.targeting]]
target = "admin.product-details.block.render"
module = "./src/index.tsx"
tools = "./tools.json"

Run shopify app dev and verify:

The generated .d.ts file includes ShopifyTools interface
shopify.tools.register('search-products', ...) has proper types
Input/output types are correctly inferred from the JSON schemas

// shopify.tools.register's first argument is strongly typed based on the tools.json file entries' name property
shopify.tools.register('search-products', (input) => {
  // this is typed as { query: string }
  input.query;

  // this is typed as { products: string[] }
  return {
    products: ['product1', 'product2'],
  };
});

Measuring impact

How do we know this change was effective? Please choose one:

n/a - this doesn't need measurement, e.g. a linting rule or a bug-fix

Checklist

I've considered possible cross-platform impacts (Mac, Linux, Windows)
I've considered possible documentation changes

olavoasantos · 2026-01-08T19:00:59Z

add shopify tools type generation #6748 👈 (View in Graphite)
main

This stack of pull requests is managed by Graphite. Learn more about stacking.

github-actions · 2026-01-08T21:24:51Z

We detected some changes at packages/*/src and there are no updates in the .changeset.
If the changes are user-facing, run pnpm changeset add to track your changes and include them in the next release CHANGELOG.

Caution

DO NOT create changesets for features which you do not wish to be included in the public changelog of the next CLI release.

github-actions · 2026-01-08T21:42:56Z

Coverage report

St.^❔	Category	Percentage	Covered / Total
🟡	Statements	79.48% (+0.25% 🔼)	14274/17959
🟡	Branches	73.67% (+0.56% 🔼)	7010/9515
🟡	Functions	79.6% (+0.23% 🔼)	3653/4589
🟡	Lines	79.85% (+0.27% 🔼)	13499/16905

Show new covered files 🐣

St.^❔	File	Statements	Branches	Functions	Lines
🟢	`...` / admin-as-app.ts	100%	100%	100%	100%
🟢	`...` / metafield_definitions.ts	100%	100%	100%	100%
🟢	`...` / metaobject_definitions.ts	100%	100%	100%	100%
🟢	`...` / bulk-operation-cancel.ts	100%	100%	100%	100%
🟢	`...` / bulk-operation-run-mutation.ts	100%	100%	100%	100%
🟢	`...` / bulk-operation-run-query.ts	100%	100%	100%	100%
🟢	`...` / get-bulk-operation-by-id.ts	100%	100%	100%	100%
🟢	`...` / list-bulk-operations.ts	100%	100%	100%	100%
🟢	`...` / staged-uploads-create.ts	100%	100%	100%	100%
🔴	`...` / import-custom-data-definitions.ts	0%	100%	0%	0%
🔴	`...` / cancel.ts	0%	100%	0%	0%
🔴	`...` / execute.ts	0%	0%	0%	0%
🔴	`...` / status.ts	0%	0%	0%	0%
🔴	`...` / pull.ts	0%	100%	0%	0%
🟡	`...` / execute-operation.ts	73.53%	50%	100%	73.53%
🔴	`...` / pull.ts	0%	0%	0%	0%
🟢	`...` / bulk-operation-status.ts	96.55%	92.11%	100%	100%
🟢	`...` / cancel-bulk-operation.ts	100%	100%	100%	100%
🟢	`...` / constants.ts	100%	100%	100%	100%
🟢	`...` / download-bulk-operation-results.ts	100%	100%	100%	100%
🟢	`...` / execute-bulk-operation.ts	92.42%	86.67%	100%	93.75%
🟢	`...` / format-bulk-operation-status.ts	100%	100%	100%	100%
🟢	`...` / run-mutation.ts	100%	100%	100%	100%
🟢	`...` / run-query.ts	100%	100%	100%	100%
🟡	`...` / stage-file.ts	73.53%	62.5%	85.71%	72.73%
🟢	`...` / watch-bulk-operation.ts	100%	94.74%	100%	100%
🟢	`...` / declarative-definitions.ts	98.54%	93.18%	100%	98.51%
🟢	`...` / common.ts	97.22%	93.75%	100%	96.55%
🟢	`...` / execute-command-helpers.ts	100%	100%	100%	100%
🟢	`...` / file-formatter.ts	100%	100%	100%	100%
🔴	`...` / promiseWithResolvers.ts	33.33%	50%	50%	33.33%

Show files with reduced coverage 🔻

St.^❔	File	Statements	Branches	Functions	Lines
🔴	`...` / execute.ts	0%	0% (-100% 🔻)	0%	0%
🟢	`...` / extension-instance.ts	84.8% (+0.23% 🔼)	77.6% (-0.91% 🔻)	92.06% (+0.13% 🔼)	85.11% (+0.24% 🔼)
🟡	`...` / specification.ts	69.09%	75.61% (+2.44% 🔼)	76.47% (-1.31% 🔻)	68.75%
🟢	`...` / ui_extension.ts	87.25% (-7.58% 🔻)	74.04% (-7.21% 🔻)	84.62% (-15.38% 🔻)	89.58% (-6.88% 🔻)
🟢	`...` / Logs.tsx	90%	90.91% (-5.97% 🔻)	100%	90%
🟢	`...` / app-event-watcher-handler.ts	86.36% (-4.11% 🔻)	75%	86.67%	85.71% (-5.19% 🔻)
🟢	`...` / bundle.ts	93.22%	63.33% (-3.33% 🔻)	94.12% (+5.88% 🔼)	96.3%
🟢	`...` / developer-platform-client.ts	84.62% (-1.5% 🔻)	71.43% (+0.84% 🔼)	81.82% (+1.82% 🔼)	93.75% (+0.42% 🔼)
🔴	`...` / http-reverse-proxy.ts	58.97% (-4.91% 🔻)	37.04% (-2.96% 🔻)	58.33% (-5.3% 🔻)	59.46% (-5.25% 🔻)
🟢	`...` / api.ts	87.07% (-0.43% 🔻)	76.71% (-0.1% 🔻)	100%	86.49% (-0.43% 🔻)
🟢	`...` / SingleTask.tsx	84.21% (-15.79% 🔻)	50% (-50% 🔻)	80% (-20% 🔻)	84.21% (-15.79% 🔻)
🔴	`...` / environment.ts	35% (-5% 🔻)	41.18%	40% (-10% 🔻)	36.84% (-5.26% 🔻)
🔴	`...` / ui.tsx	50.82% (-0.79% 🔻)	42.86% (-5.53% 🔻)	54.55% (+1.42% 🔼)	50% (-0.82% 🔻)
🟢	`...` / console.ts	81.82% (+15.15% 🔼)	75% (-25% 🔻)	100% (+33.33% 🔼)	81.82% (+15.15% 🔼)
🟢	`...` / init.ts	88% (-0.89% 🔻)	71.43% (+4.76% 🔼)	86.67% (+4.85% 🔼)	88% (-0.89% 🔻)
🟢	`...` / storefront-renderer.ts	90.2% (-0.54% 🔻)	78.95%	81.82% (-1.52% 🔻)	90.2% (-0.54% 🔻)
🟡	`...` / theme-polling.ts	67.12% (-0.93% 🔻)	68.75%	78.57%	66.67% (-0.98% 🔻)

Test suite run success

3603 tests passing in 1422 suites.

Report generated by 🧪jest coverage report action from e7993e6

henrytao-me

🎩-ed including file watching while dev server is running. LGTM

henrytao-me

Note that: to temporary test the files watching. Follow these steps:

Run dev clone ui-extensions
Add to packages/ui-extensions/src/surfaces/admin/extension-targets.ts

  'admin.app.tools.data': RenderExtension<
    BlockExtensionApi<'admin.app.tools.data'>,
    BlockExtensionComponents
  >;

Now you can use target admin.app.tools.data.
You may need to add app beta flag 1p_internal to your app on prod or run local server

packages/app/src/cli/models/extensions/specifications/ui_extension.ts

packages/app/src/cli/models/extensions/specifications/type-generation.ts

packages/app/src/cli/models/extensions/specifications/ui_extension.test.ts

vividviolet · 2026-01-12T20:19:36Z

packages/app/src/cli/models/extensions/specifications/ui_extension.test.ts

Can we add unit tests for the tools type generation?

olavoasantos · 2026-01-12T20:51:39Z

packages/app/src/cli/api/graphql/business-platform-organizations/generated/types.d.ts

SEE https://shopify.slack.com/archives/C07UJ7UNMTK/p1768248887491109

vividviolet

Looks good, just some minor feedback. I am also blocked on tophatting until we can get a snapshot release of the new ui-extensions library

vividviolet · 2026-01-13T06:42:14Z

packages/app/src/cli/models/extensions/specifications/type-generation.test.ts

+    const result = await createToolsTypeDefinition(tools)
+
+    // Then
+    expect(result).toContain('interface ComplexToolInput')


Is it possible to just post the full expected text for these tests? It's hard to understand what the results are supposed to be when the assertions are broken up

olavoasantos force-pushed the 01-08-add_shopify_tools_type_generation branch from 257c0cc to d77fe8b Compare January 8, 2026 19:08

olavoasantos marked this pull request as ready for review January 8, 2026 21:24

olavoasantos requested a review from a team as a code owner January 8, 2026 21:24

olavoasantos force-pushed the 01-08-add_shopify_tools_type_generation branch 2 times, most recently from 16010c0 to a421a8e Compare January 8, 2026 21:36

olavoasantos force-pushed the 01-08-add_shopify_tools_type_generation branch 4 times, most recently from 6d50ad7 to ead2c83 Compare January 9, 2026 20:46

henrytao-me approved these changes Jan 12, 2026

View reviewed changes

vividviolet reviewed Jan 12, 2026

View reviewed changes

olavoasantos force-pushed the 01-08-add_shopify_tools_type_generation branch 5 times, most recently from 4432a33 to 09f5bf7 Compare January 12, 2026 19:25

vividviolet reviewed Jan 12, 2026

View reviewed changes

olavoasantos force-pushed the 01-08-add_shopify_tools_type_generation branch from 09f5bf7 to 8c45152 Compare January 12, 2026 20:34

add shopify tools type generation

e7993e6

olavoasantos force-pushed the 01-08-add_shopify_tools_type_generation branch from 8c45152 to e7993e6 Compare January 12, 2026 20:50

olavoasantos commented Jan 12, 2026

View reviewed changes

vividviolet reviewed Jan 13, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

add shopify tools type generation #6748

add shopify tools type generation #6748

olavoasantos commented Jan 8, 2026 •

edited

Loading

Uh oh!

olavoasantos commented Jan 8, 2026

Uh oh!

github-actions bot commented Jan 8, 2026

Uh oh!

github-actions bot commented Jan 8, 2026 •

edited

Loading

Uh oh!

henrytao-me left a comment

Uh oh!

henrytao-me left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

vividviolet Jan 12, 2026

Uh oh!

olavoasantos Jan 12, 2026

Uh oh!

olavoasantos Jan 12, 2026

Uh oh!

vividviolet left a comment

Uh oh!

vividviolet Jan 13, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

add shopify tools type generation #6748

Are you sure you want to change the base?

add shopify tools type generation #6748

Conversation

olavoasantos commented Jan 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

WHY are these changes introduced?

WHAT is this pull request doing?

Summary of changes

Example generated types:

Changes summary:

How to test your changes?

Measuring impact

Checklist

Uh oh!

olavoasantos commented Jan 8, 2026

Uh oh!

github-actions bot commented Jan 8, 2026

Uh oh!

github-actions bot commented Jan 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Coverage report

Test suite run success

Uh oh!

henrytao-me left a comment

Choose a reason for hiding this comment

Uh oh!

henrytao-me left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

vividviolet Jan 12, 2026

Choose a reason for hiding this comment

Uh oh!

olavoasantos Jan 12, 2026

Choose a reason for hiding this comment

Uh oh!

olavoasantos Jan 12, 2026

Choose a reason for hiding this comment

Uh oh!

vividviolet left a comment

Choose a reason for hiding this comment

Uh oh!

vividviolet Jan 13, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

olavoasantos commented Jan 8, 2026 •

edited

Loading

github-actions bot commented Jan 8, 2026 •

edited

Loading