Storefront Integration Guide
This guide is for technically versed merchants, theme developers, and agencies who run the Fancy Product Designer (FPD) app in a Shopify store and want to understand, customize, or extend how the designer integrates with their storefront theme.
It documents the public surface of the storefront bundle (fpd-fe-shopify-v2.js): the HTML it expects, the web components it provides, the events it emits, the cart data it writes, and the styling and configuration hooks you can use — without touching app internals.
What the storefront bundle does
The bundle is loaded into your storefront by the FPD Shopify app and activates itself depending on the page type:
| Page | What happens |
|---|---|
| Product page | Detects designable products, loads the FPD product configuration, renders the designer and its modules, intercepts the add-to-cart flow, and attaches the design data to the line item. See Product page. |
| Cart page | Replaces line item thumbnails with the customized preview image and offers an edit link back to the designer. See Cart page. |
| All other pages | Keeps cart previews correct wherever your theme renders cart contents dynamically (AJAX carts, cart drawers). |
How to use this guide
- Start with Getting started if you are integrating FPD into a new or heavily customized theme.
- Read The Product Designer for the core concepts (products, views, elements, modules) used throughout.
- Use the reference chapters when you build on top of the integration:
- Product page — designer lifecycle, external modules, add-to-cart flow
- Cart page — thumbnails, edit flow, line item properties
- Events — everything you can listen to from your own theme code
- JavaScript API — runtime objects you can access
- Configuration — options that change frontend behavior
- Theming — CSS hooks for matching the designer to your brand
- Troubleshooting — debug tools and common pitfalls
Ground rules
A few invariants to keep in mind before customizing anything:
- Never strip
_fpdline item properties. All properties prefixed with_fpdon a cart line item belong to the designer integration. Theme code or apps that rewrite line item properties must pass every_fpd*property through unchanged — otherwise orders lose their design data. - Don't rename or remove the DOM anchors the bundle hooks into (product form, add-to-cart button, cart line markup) without checking the corresponding chapter of this guide first.
- Prefer documented hooks (events, CSS custom properties, options) over patching markup or globals — documented hooks are kept stable across releases; internals are not.