Skip to content

feat: allow library asset url to be set and passed as a prop#613

Open
DNR500 wants to merge 1 commit into
scratchfoundation:developfrom
RaspberryPiFoundation:library-asset-url
Open

feat: allow library asset url to be set and passed as a prop#613
DNR500 wants to merge 1 commit into
scratchfoundation:developfrom
RaspberryPiFoundation:library-asset-url

Conversation

@DNR500

@DNR500 DNR500 commented Jun 16, 2026

Copy link
Copy Markdown

Proposed Changes

Adds a libraryAssetUrlTemplate prop to scratch-gui so embedders can control how library thumbnail URLs are built (sprite, costume, backdrop, and sound libraries).

  • New libraryAssetUrlTemplate prop on the GUI container/component
  • LibraryAssetConfigProvider context to pass the template into library modals
  • buildLibraryAssetServiceUri() helper that substitutes {assetPath} into the template
  • Library components use this when resolving thumbnail/asset URLs

The template controls the full URL shape, not only the hostname. Embedders can match whatever asset API they run (path segments, trailing slashes, etc.), as long as they include the {assetPath} placeholder where the asset id (and extension when needed) should go.

Default (unchanged when the prop is omitted):

https://cdn.assets.scratch.mit.edu/internalapi/asset/{assetPath}/get/

Example: asset abc123 with format png{assetPath} becomes abc123.png:

https://cdn.assets.scratch.mit.edu/internalapi/asset/abc123.png/get/

Example embedder override (same placeholder, different service shape):

https://assets.example.com/v1/library/{assetPath}

https://assets.example.com/v1/library/abc123.png

When the prop is omitted, behaviour is unchanged and library assets still load from the standard Scratch CDN (cdn.assets.scratch.mit.edu).

Reason for Changes

Scratch is often embedded in other products (classroom platforms, LMSs, custom editors). Those hosts may need library assets served from their own infrastructure instead of the public Scratch CDN — for example:

  • Serving assets from the same origin as the host app (CSP, cookies, or auth requirements)
  • Routing library requests through a proxy or internal API
  • Environments where the default CDN is blocked or inappropriate

Today, library thumbnail URLs are effectively fixed to the Scratch asset service. Project assets can already be configured by embedders via storage/host settings, but library browsing does not have an equivalent hook.

A URL template (rather than a fixed host or path prefix) lets each embedder align library requests with their own asset API contract while keeping scratch-gui agnostic of each host's URL layout. This change closes that gap with a small, optional prop and no impact on the default Scratch experience.

Test Coverage

Unit tests added for:

  • test/unit/lib/library-asset-url.test.js — URL building from templates, {assetPath} substitution, custom URL shapes, and default fallback to the MIT CDN template
  • test/unit/contexts/library-asset-config-context.test.jsx — context provider supplies the template to consumers and falls back to the default when unset

* feat: library host url prefix prop added

* feat: allow change of the full url using a url template
@DNR500 DNR500 requested a review from a team as a code owner June 16, 2026 17:49
@github-actions

github-actions Bot commented Jun 16, 2026

Copy link
Copy Markdown
Contributor

All contributors have signed the CLA ✍️ ✅
Posted by the CLA Assistant Lite bot.

@DNR500

DNR500 commented Jun 16, 2026

Copy link
Copy Markdown
Author

I have read the CLA Document and I hereby sign the CLA

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant