Theme integration
Placing widgets in your theme
App embeds, section blocks and the theme editor.
Widgets are added in Shopify's theme editor. There are two kinds — app embeds that load globally, and section blocks you place on specific templates.
Enable the app embed first#
Theme editor → App embeds → enable WySync app bootstrap. It loads the shared vehicle state that every other widget reads. Nothing works properly without it, and half of "the widget isn't doing anything" tickets are this.
Two other embeds are optional: the persistent bar and the search autocomplete attachment.
Where each block goes#
| Widget | Template | Notes |
|---|---|---|
| YMMS hero | Homepage (or a landing page) | Above the fold |
| Collection list | Collection list (/collections) | Where the hero's blank redirect lands |
| Collection page | Collection template | Replace the theme's product grid |
| Product fits check | Product template | Near the buy button |
| Fitment table | Product template | Below the fold, or in a tab |
| Cart re-verification | Cart template | Plus the embed if you use a cart drawer |
| Garage | App embed or header block | Header if your theme allows app blocks there |
The CLI cannot do this#
Widget placement is theme-editor-only. Pushing config/settings_data.json or templates/*.json with the Shopify CLI silently strips shopify://apps/... block and embed references — the push succeeds and your widgets vanish.
Reading theme JSON is fine; only writes are stripped. The Storefront → Widgets screen in the app exists for exactly this: it reads your published theme, shows what's actually installed, and deep-links to the right editor panel.
Removing the native product grid to fit the WySync one is reversible in the editor, but working on a duplicate means a mistake is a theme swap rather than a rebuild. It costs thirty seconds.
Themes that need a nudge#
Horizon — sections are a three-column grid, and width: 100% on a block fills only the centre column. The hero and collection blocks ship with the override that lets them go edge-to-edge, so no custom section wrapper is needed.
Themes with a search dialog — several modern themes render search inside a <dialog>. The autocomplete embed handles that; if suggestions work on /search but not in the header, tell us which theme.
Vintage (non-OS 2.0) themes — app embeds work; section blocks do not, because vintage themes have no block architecture. In practice that means the bar, garage and autocomplete work and the rest need a theme upgrade.
After you save#
Storefront changes go live immediately. Extension version updates propagate over a minute or two, so a page loaded mid-deploy may still run the previous bundle. Reload once before investigating anything.
Support is answered by the people who wrote this code — not a ticket queue.