Provider authoring
+Custom providers
++ A provider translates a normalized image source and modifiers into a URL. Define the mapping once, register it + under a name, then use it through the core API or any framework package. +
+ + +Provider contract
+
+ Register an object or a setup function with a getImage() method. The runtime resolves aliases, validates
+ the source, merges options, and calls the provider for each requested image candidate.
+
Implement the provider
+
+ This example maps shared width, height, quality, format, and fit values to a query-string API. It also accepts
+ one service-specific modifier, sharpen.
+
{data.provider}
+ defineProvider() memoizes setup. configureProvider() creates a named provider with factory
+ defaults, so each application can point the same implementation at a different endpoint.
+
Register it
+
+ Save the implementation as acme-provider.ts, then register its factory in shared image
+ configuration:
+
{data.configuration}Top-level provider options are merged in this order, with later values taking priority:
+-
+
- Defaults declared by the provider setup. +
- Defaults passed to the provider factory. +
- Overrides from
providerOptions.acme.
+
+ The runtime merges modifiers separately: provider defaults, config-level provider modifiers,
+ resolved preset and per-image modifiers, then per-image width, height,
+ quality, and format props.
+
Use it
+{installCommands[framework]}
+ Use the same imageConfig with the {frameworkNames[framework]} API. Standard props and custom modifiers
+ reach getImage() through its merged modifiers object.
+
{data.examples[framework]}Choose source rules deliberately
+-
+
-
+ Set
validateDomains: truewhen the provider fetches remote sources. Applications must then allow + each source throughdomainsorremotePatterns. +
+ -
+ Set
acceptsOpaqueSource: truethrough the fourthconfigureProvider()argument only + when values such asasset_123are valid service identifiers. +
+ -
+ Leave
supportsAliasunset unless the provider needs to interpret alias prefixes itself. The + runtime otherwise resolves aliases before callinggetImage(). +
+ -
+ When delegating through
context.$img, select another provider or a preset backed by another + provider. Calling the active provider again would recurse. +
+
Keep signing secrets on the server
+
+ Framework components can execute provider code in the browser. Generate signed URLs in server-only code, pass
+ the finished URL to the client, and render it with provider="none".
+
Test the URL contract
+
+ A black-box test through createImage() covers provider registration, option merging, source validation,
+ and URL generation together.
+
{data.test}Also cover requests with no modifiers, local and remote sources, mapped enum values, and invalid inputs.
+Authoring utilities
+Query parameters
+appendQuery, mappedModifiers, and createMappedQueryProvider.
Path operations
+createOperationsGenerator, pathOperations, and joinURLParts.
Source handling
+providerBaseURL, sourceWithBase, and sourcePath.