Skip to content

Serve UI extension source maps during app dev - #8212

Open
vividviolet wants to merge 1 commit into
mainfrom
serve-ui-extension-source-maps-in-dev
Open

Serve UI extension source maps during app dev#8212
vividviolet wants to merge 1 commit into
mainfrom
serve-ui-extension-source-maps-in-dev

Conversation

@vividviolet

@vividviolet vividviolet commented Jul 30, 2026

Copy link
Copy Markdown
Member

WHY are these changes introduced?

Source maps stopped working for UI extensions in shopify app dev. The main asset is served from
https://localhost:3458/extensions/dev-<uuid>/assets/<target>/main.js and ends with a relative
//# sourceMappingURL=<handle>.js.map, so the browser requests
/assets/<target>/<handle>.js.map. Nothing emits that URL key, so the dev server 404'd it and
DevTools only ever showed minified output.

The map itself is generated — it just isn't in the directory the dev server reads from.
ExtensionInstance.keepBuiltSourcemapsLocally moves <handle>.js.map out of the bundle and
into the extension directory, which is what keeps .js.map files out of deploy bundles. That
invariant has to stay, so the fix is on the serving side only.

WHAT is this pull request doing?

  • services/dev/extension/payload.ts: when a built asset has a source map in the extension
    directory, register it on the asset resolver under the key the relative sourceMappingURL
    resolves to (<target>/<handle>.js.map). It is not added to the payload's assets — it's a
    fetchable sibling, not a declared asset.
  • services/dev/extension/server/middlewares.ts: resolve .js.map paths against the extension
    directory instead of the bundle (traversal guard follows the new root), and serve .map as
    application/json. .js.map requests without a resolver entry 404, so the resolver remains the
    allowlist for this route and the extension directory isn't otherwise readable.

No build step changes, so nothing new can reach a deploy bundle. .js.map is unambiguous as a
marker here because deploy bundles exclude those files unconditionally
(BUNDLE_EXCLUSION_PATTERNS).

How to test your changes?

  1. shopify app dev with an app that has an admin UI extension.
  2. Open the extension in Admin and check the Network tab: the .js.map request should be 200
    (application/json) and DevTools Sources should show the original TSX.
  3. Edit a source file so the extension rebuilds, then confirm the map still resolves.

Automated coverage (real temp dirs, no fs mocking):

  • payload.test.ts — map registered when present, not registered when absent.
  • middlewares.test.ts — a registered map is served from the extension directory while the bundle
    dir is deliberately map-free (so it also pins "not served from the bundle"); an unregistered
    .js.map 404s.

Checklist

  • I've considered possible cross-platform impacts (Mac, Linux, Windows)
  • I've considered possible documentation changes
  • I've considered analytics changes to measure impact
  • The change is user-facing — I've identified the correct bump type (patch) and added a changeset

The built bundle ends with a relative `//# sourceMappingURL=<handle>.js.map`, so
the browser requests the map next to the asset's own URL —
`/assets/<target>/<handle>.js.map` — a key no asset payload emits. The request
404'd and DevTools only ever showed minified output.

Register that key on the asset resolver when the map exists, and serve `.js.map`
requests from the extension directory. Maps are deliberately absent from the
bundle: `keepBuiltSourcemapsLocally` moves them back into the extension
directory so `.js.map` files never reach a deploy bundle. No build step changes,
so that invariant is untouched.

Unregistered `.js.map` paths 404, keeping the resolver the allowlist for this
route.

Assisted-By: devx/5a367c53-dfe0-42d0-8b9f-5258f54d589a
@vividviolet
vividviolet requested review from a team as code owners July 30, 2026 13:06
@github-actions github-actions Bot added the Area: @shopify/app @shopify/app package issues label Jul 30, 2026
@vividviolet
vividviolet enabled auto-merge July 30, 2026 14:08
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Area: @shopify/app @shopify/app package issues

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants