Extending the SDK
How do you change what the SDK does without forking it? The commerce domains in @scayle/storefront ship as base classes: mappers that turn SCAYLE Storefront API data into the shapes your pages use, and services that fetch and cache that data. You subclass the class you want to change and register your subclass in src/server/registries.ts. The SDK's own code then uses your class, because it reaches every other domain through the same registry.
A slot is one key in a registry, such as product or basket, that holds one instance of a class for the duration of a request. There are two registries, one for mappers and one for services.

src/server/registries.ts holds two blueprints, mapperRegistry and serviceRegistry. A slot is built the first time something reads it and is reused for the rest of the request.
Controllers and pages are on Layers and Data Flow.
A slot type that you override has to stay assignable to the SDK's type, because the SDK's own code reads the slot through the same registry. An override is also code that you maintain. It builds on the base class, so a method that the SDK renames or removes shows up as a compile error after an upgrade.
Types
@scayle/storefront/types holds the shapes your pages read, such as ListingProduct, DetailedProduct, Basket, Customer, and Category. They differ from the Storefront API response shapes. A page reads ListingProduct and never the raw API product, and a mapper turns one into the other. A change in the Storefront API response then lands in the mapper and leaves every component alone.
Every export from that entry point is a type. You extend those types with declare module '@scayle/storefront/types' and an interface of the same name, instead of defining a parallel type next to them. The Storefront Application V3 adds a color to Campaign this way. The Storefront API sends the campaign color as background and text values, and the pages want a Vue style object. The campaigns guide shows the declaration block in Add a field from the Storefront API to the campaign.
Until a mapper assigns the field, TypeScript still believes it exists. A mapper that spreads the base result still compiles, so color arrives as undefined on every request. Only typed objects that lack the field, such as test fixtures, fail the typecheck. A ?? '' somewhere in a template absorbs it quietly. Add the type field and update the mapper in the same merge request. The next section fills it.
A value that you configure in the SCAYLE Panel as customData needs a second declaration, against @scayle/storefront-api, in src/shared/types/customData.ts. NavigationMapperService reads item.customData?.linkColor through the NavigationItemCustomData declaration there.
Put the declare module block in a file that already imports or exports something, or add export {}. A file with only the block is no module, so TypeScript reads it as a fresh declaration of the whole entry point, and every other import from @scayle/storefront/types fails with "has no exported member". src/shared/types/Navigation.ts carries an export {} for this reason.
Layers and Data Flow covers what shape a field may take, such as a domain entity instead of a page bundle.
Mappers
A mapper is the one place where a Storefront API response becomes a storefront type. Mappers are synchronous covers what a mapper may and may not do.
The SDK's own services read mappers from the same registry. ProductDetailService maps the detail page with this.mappers.product.mapDetailedProduct, and the listing, search, wishlist, basket, and recommendation code call this.mappers.product.mapProduct. One override of mapProduct changes the product shape on all of those. The detail page uses mapDetailedProduct, see Find the mapper for your type.
src/server/registries.ts registers a factory for every SDK mapper slot, plus the i18n slot that the application adds. Most slots carry an application subclass, while analytics registers the SDK class as it is. The subclasses live in src/server/services/mappers/ and carry a Service suffix, as in ProductMapperService. They are mappers, and the suffix only follows the directory name.
Abstract and concrete classes
A concrete class works as it is. An abstract class declares members that the SDK cannot answer for you because the answer depends on your shop, such as your URL scheme or the fields your pages read. TypeScript refuses to compile a subclass that leaves one out. A mapper is abstract only when no default would suit every shop. These mappers are abstract, for example:
| Slot | Base class | Members you implement |
|---|---|---|
product | ProductMapper | Includes, DetailedIncludes, HreflangIncludes, getPath, and the protected method mapImage |
category | CategoryMapper | Includes, NavigationIncludes, getPath |
search | SearchMapper | Includes, getSearchResultsPath |
wishlist | WishlistMapper | Includes, getWishlistKey |
basket | BasketMapper | Includes |
No SDK service is abstract.
Hooks you can override
A subclass can override every public and protected member, and private members stay internal. Go to the definition of the base class in your editor to see what is available. NavigationMapper resolves links in private methods, so to change a navigation link you override mapNavigationItem and replace href in its result. The base class calls its own methods through this, so your override applies wherever the base calls it, including every depth of the navigation tree.
Registering a mapper
Add a factory for the slot in src/server/registries.ts, and declare the slot in src/server/types/index.ts only when your subclass adds a public method.
Add the factory
A mapper factory receives { storefront, mappers }. storefront is the StorefrontContext of the request, and mappers is the mapper registry, which is how one mapper reaches another. ProductMapper builds breadcrumb links with this.mappers.category.getPath(...), and that call lands in your CategoryMapperService, a class the SDK could not import itself.

Import SDK classes from the package entry points, such as @scayle/storefront/mappers, and never from a file path inside the package.
Every slot needs a factory, including the ones you never customize. TypeScript fails in registries.ts when one is missing. Once the factory is in place, this.mappers.campaign returns your CampaignMapperService. To replace a mapper, extend its base class and register it the same way.
Declare the slot when you add a method
MapperRegistry merges your MapperOverrides over the SDK's default slots. When your subclass adds a public method, declare the slot so callers see the method without a type assertion. PromotionMapperService adds mapPromotionForSummary, ProductMapperService adds VariantIncludes, and ShopConfigMapperService adds mapDeliveryCost, so all three have an entry. CampaignMapperService only overrides SDK methods, so it needs none.
With the entry in place, mappers.promotion.mapPromotionForSummary(...) type-checks without a cast. The application adds the i18n slot the same way, because the SDK ships no such slot. A cast such as this.mappers.promotion as PromotionMapperService compiles, but nothing checks it against registries.ts, so it survives a change of registration.
Add a field to a mapped entity
The type declares the field and the mapper fills it. Continuing with the color of Campaign, CampaignMapperService spreads the SDK result and adds the field:
The Storefront API types campaign.color as optional, because a campaign with no color configured leaves it out, so the mapper falls back to theme variables. Registration stays as it is, because campaign already has a factory. The steps, from the type to a component that reads the field, are in Add a field from the Storefront API to the campaign. Test the campaign mapper shows how to test an override.
Find the mapper for your type
Look for the mapper method that returns your type. The names follow the type: mapCampaign returns Campaign, mapNavigationItem returns NavigationItem, mapCategory returns Category, and mapBasket, mapWishlist, mapOrder, and mapCustomer follow the pattern. "Find all references" on the type in your editor leads to the mapper that produces it.
Products are the exception. mapProduct returns ListingProduct for listings, search, wishlist, basket items, and recommendations, and mapDetailedProduct returns DetailedProduct for the detail page. Both build on the protected mapBaseProduct, and the second does not call the first. A field added in mapProduct alone shows on listing cards and stays undefined on the detail page, and TypeScript stays quiet when the field is optional. Override both methods, or override mapBaseProduct, which both call.

A listing field that comes from an attribute also needs the attribute key in ProductMapperService.Includes, because the Storefront API returns only the attributes that a query asks for. The detail page already requests all attributes.
Implement a required hook
ProductMapper.getPath is abstract, so a subclass does not compile until you implement it. The application builds the path with buildProductDetailRoute from src/shared/routes.ts:
The SDK builds several URLs from getPath:

The product detail page adds the country prefix to product.link and redirects with a 301 when the request path differs from the result, so getPath also decides which URL a product page is served on. CategoryMapperService.getPath does the same for category pages with buildProductListingRoute.
Services
A service fetches and caches the data that a mapper turns into a shared type. See Services fetch and cache.
The SDK declares a slot for each of its domain services, such as basket, productDetail, and wishlist, and src/server/registries.ts registers a factory for every one. The application does not extend services by default. Only the attributes slot carries a subclass of an SDK service, ShopAttributeService. The cms slot holds the CMS provider of your shop and is built by createCMSService, and every other slot registers the SDK class.
Registering a service
Service factories receive { storefront, request, mappers, services }. The last two are the difference from a mapper factory. request is the inbound request, described on Request Lifecycle, and services is the registry being built, which is how a service reaches a sibling.
BasketService uses both in one method. It reads this.services.campaigns.getActiveCampaignKey() and this.services.orderCustomData.resolve(), then maps the response with this.mappers.basket.mapBasket(...).
ServiceRegistry works like MapperRegistry and merges your ServiceOverrides over the SDK's slots. Factories and declarations follow the rules in Registering a mapper.
Extend an existing service
Order custom data is metadata, such as a purchase order number, that travels with the basket and the order. It is not the customData of navigation items that Types describes.
OrderCustomDataService is a service with a designed hook. It resolves to no custom data by default. Override the protected getCustomData() in a subclass and register the subclass on the orderCustomData slot, and every Storefront API basket call and the checkout token carry your metadata. The result is memoized per request, so an override may read the session or call an upstream service. How memoization, thrown errors, the per-call customData merge, and the checkout token behave is described under Constraints and limits on the Checkout page. The basket calls have no per-call value, so this service is their only source of it.
getCustomData() is the hook you override. Consumers call the public resolve(), which memoizes the result so concurrent callers share one resolution. A hook override needs a factory change and no ServiceOverrides entry, because the type that the SDK declares is still accurate.
The other way to extend a service is to add a public method. ShopAttributeService extends AttributeService and adds fetchImageViewOptions, which the base class does not have. It reads attribute groups through the inherited fetchAttributeGroup and maps the result. Because code calls a method the SDK type lacks, the slot needs an entry in ServiceOverrides as well as a factory:
Replacing a service follows the rule for mappers: every SDK service slot is typed as a class, so a replacement has to be assignable to that class and in practice extends it.
Add a custom service
Your shop shows average ratings from a review provider. The SDK has no reviews domain, so you add a service and a slot for it. i18n is the same case on the mapper side. The service reads the provider's URL and API key from privateFields, which Configure a third-party API declares and fills from STOREFRONT_REVIEWS_API_URL and STOREFRONT_REVIEWS_API_KEY:
Declare the slot type first, then add the factory:
A service tests with the same doubles. createMockStorefrontContext gives the service an in-memory cache and takes overrides for config and storefrontAPI, and createMockRequestContext covers a service that reads the request:
Run it with pnpm exec vitest run src/server/services/review-summary-service.test.ts.
With the declaration in place, TypeScript reports the missing factory in registries.ts. Once both exist, code reads the service as this.services.reviewSummary, and an oRPC procedure, the application's typed layer for mutations, reads it as context.services.reviewSummary. If the service needs to map data or call a sibling, add mappers or services to the factory, as BasketService does.
Common mistakes
Start every override from super
Spread super.mapX(...) first and add your fields after it. TypeScript rejects a dropped required field but says nothing about a dropped optional one, so the field arrives undefined in the browser. A hand-built shape also misses every optional field that a later SDK release adds. Put the spread before your fields, because a field that you set before it is overwritten by the base value.
Read the slot instead of building the class
new CampaignMapper(storefront) gives you the SDK's mapper and not your CampaignMapperService, and nothing warns you. Read the slot from the registry.
Do work in methods, not constructors
Reading a sibling in a constructor builds that sibling immediately. When two classes read each other in their constructors, the second read throws a RegistryCycleError with the path, such as a → b → a. A constructor read is safe when the sibling does not read you back, which is how ProductMapperService takes mappers.i18n. Otherwise store the registry and read siblings inside methods, as ProductMapper does with this.mappers.category. Read request.session in methods too, because it throws SessionNotReadyError until the session middleware has run.