Skip to main content
Most theme bugs come from something outside the file you’re editing: a script Fluid injects, a value Fluid resolves before Liquid sees it, or a template Fluid picks for the visitor. This page covers those pieces and the mistakes they cause.

​
Leave the FairShare SDK script alone

The FairShare SDK powers the cart, rep attribution, and the data-fluid-* attributes on your markup. It isn’t a theme file. Fluid loads it from a storefront Global Embed managed in the admin, as a script with the ID fluid-cdn-script. The floating cart and lead-capture widgets come from Global Embeds too. Fluid adds every active storefront Global Embed to each storefront page, in the head or body according to the embed’s placement. So:
  • Don’t add the SDK script to your theme, and don’t remove it.
  • If the cart or attribution stops working across the whole storefront, check that the SDK’s Global Embed still exists and is active before debugging the theme. A draft embed doesn’t render.
  • Style and toggle the floating widgets from their Global Embed settings in the admin, not from theme markup.

​
Checkout isn’t part of your theme

Your theme renders the storefront and cart only. Payment, shipping, and tax happen in Fluid Checkout, a separate app at checkout.fluid.app. Nothing in your Liquid, CSS, or JavaScript can change the checkout page.

​
Render standalone blocks with content_for

A block in blocks/<name>/index.liquid owns its markup. Render a section’s standalone blocks with {% content_for 'blocks' %}, and a single fixed block with {% content_for 'block', type: 'heading', id: 'intro' %}. See Blocks and components. {% render block %} renders only app blocks from Droplet theme extensions. For a theme block it outputs nothing. Don’t loop over section.blocks to render blocks that content_for 'blocks' already renders: they appear twice.

​
Output block.fluid_attributes on every block

The Page Editor selects a block by the attributes that {{ block.fluid_attributes }} emits. Put it on each block’s outer element, whether the block is inline in a section or standalone. Sections don’t need an equivalent: Fluid wraps each section with its own attributes.

​
Know which settings Fluid resolves

Fluid turns the value of these setting types into a Liquid object before your template reads it: product, variant, collection, category, enrollment_pack, media, link_list, and product_list. Every other type reaches Liquid exactly as saved. A post or collection_list setting, for example, gives you the stored identifier, not a record. See Resource selectors. Composite layout settings such as padding, border, and corner_radius also return structured values. Inspect the value before you interpolate it into CSS.

​
Give CSS values a fallback

An empty setting interpolated into CSS produces invalid CSS, and the browser drops the whole declaration without an error. For example, var(--color-{{ section.settings.accent }}) becomes var(--color-) when the setting is blank. Give the value a default:

​
Expect presets to fill empty sections

When a section instance has no blocks, Fluid fills in the blocks from the section’s first preset each time the page renders. A section you emptied on purpose shows its preset blocks again. To render nothing, add an empty state in the section’s Liquid rather than relying on an empty block list.

​
Read the language from localization

Use localization.language and localization.country for the visitor’s language and country. See Localization. The request object carries only path, host, page_type, query_parameters, and full_url, so a value such as request.locale renders as an empty string:
Change the visitor’s country or language with the storefront SDK, as shown in Navbar locale selector. Don’t write Fluid’s locale cookies yourself.

​
Country-specific navbars, footers, and layouts

You can assign navbar, footer, and layout templates to countries. For each visitor, Fluid serves the newest published template of that type assigned to their country. When none matches, it serves a template that isn’t assigned to any country, preferring the default. Page templates aren’t chosen by country. To give one market a different page, use a separate template and link to it, rather than branching on the country inside one template.

​
A clean lint isn’t a working page

fluid theme lint validates schemas and section references, the same checks fluid theme push runs. It doesn’t render your templates. After a clean lint, open the page in fluid theme dev and check the browser console before you push. See CLI.