Skip to content

add shopify tools type generation #6748

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Open
olavoasantos wants to merge 1 commit into
base: main
Choose a base branch
from
Open

add shopify tools type generation #6748

olavoasantos wants to merge 1 commit into from
+262 −10

Conversation

@olavoasantos
Copy link
Contributor

@olavoasantos olavoasantos commented Jan 8, 2026 •
edited
Loading

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:

  1. Parse the tools JSON file containing tool definitions with name, description, inputSchema, and optional outputSchema
  2. Generate TypeScript interfaces from JSON schemas using json-schema-to-typescript
  3. Create a typed ShopifyTools interface with properly typed register methods for each tool
  4. 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?

  1. 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"}}
      }
    }
  }
]
  1. Reference it in your extension config:
[[extensions.targeting]]
target = "admin.product-details.block.render"
module = "./src/index.tsx"
tools = "./tools.json"
  1. 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 Graphite App
Copy link
Contributor Author

olavoasantos commented Jan 8, 2026

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

@olavoasantos olavoasantos force-pushed the 01-08-add_shopify_tools_type_generation branch from 257c0cc to d77fe8b Compare January 8, 2026 19:08
@olavoasantos olavoasantos marked this pull request as ready for review January 8, 2026 21:24
@olavoasantos olavoasantos requested a review from a team as a code owner January 8, 2026 21:24
@github-actions
Copy link
Contributor

github-actions bot commented Jan 8, 2026

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.

@olavoasantos 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
@github-actions
Copy link
Contributor

github-actions bot commented Jan 8, 2026 •
edited
Loading

Coverage report

St.❔
 Category Percentage Covered / Total
🟡 Statements
79.27% (+0.04% 🔼)
 14232/17954
🟡 Branches
73.46% (+0.35% 🔼)
 6988/9513
🟡 Functions
79.46% (+0.09% 🔼)
 3645/4587
🟡 Lines
79.63% (+0.05% 🔼)
 13458/16901
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%
🔴
... / 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%
🔴
... / type-generation.ts
59.06% (-11.94% 🔻)
44.94% (-7.11% 🔻)
57.14% (-31.75% 🔻)
59.2% (-11.51% 🔻)
🟡
... / ui_extension.ts
77.85% (-16.98% 🔻)
67.31% (-13.94% 🔻)
80.77% (-19.23% 🔻)
79.86% (-16.6% 🔻)
🟢
... / 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% 🔻)
🟢
... / ConcurrentOutput.tsx
98.36% (-1.64% 🔻)
92% (-4% 🔻)
 100%
98.33% (-1.67% 🔻)
🟢
... / 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

3586 tests passing in 1420 suites.

Report generated by 🧪jest coverage report action from 27792ef

@olavoasantos olavoasantos force-pushed the 01-08-add_shopify_tools_type_generation branch 3 times, most recently from dfd5d46 to 6d50ad7 Compare January 9, 2026 20:28
@olavoasantos olavoasantos force-pushed the 01-08-add_shopify_tools_type_generation branch from 6d50ad7 to ead2c83 Compare January 9, 2026 20:46
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@olavoasantos