October 2, 2026 · Muhammad Umar · More by Muhammad Umar
Shopify Themes Cap Out At 300 Theme Blocks
Every .liquid file in a Shopify theme's /blocks folder counts toward a 300-block cap — including every block Sidekick generates for you.
The hard limit nobody warns you about
Shopify's theme architecture documentation sets a hard ceiling: a theme can contain at most 300 theme blocks. Every .liquid file in the theme's /blocks folder counts toward that limit — including blocks that no section or template currently references, and blocks generated by Sidekick's AI block feature. Once a theme hits 300, no new theme blocks can be added until existing ones are removed from /blocks. The docs don't describe an override or an exception-request path; the limit is the limit.
Why Sidekick changes the math
Sidekick lets merchants and developers describe a block in plain text inside the theme editor, and Sidekick generates the Liquid, the HTML structure, any CSS or JavaScript, and the JSON schema definition for it. From a developer's perspective, the result is an ordinary theme block: it lands in /blocks alongside every hand-written block, and it can be added to any section or theme block that supports theme blocks.
That's the part worth flagging to clients and teammates: AI-generated blocks draw from the same 300-block budget as manually authored ones, with no separate quota and no visible counter in the editor. A theme that leans on Sidekick for rapid iteration can accumulate unused or duplicate blocks in /blocks without anyone noticing a limit existed — until a deploy or a new block addition hits the wall.
Section groups carry the same caps
A related limit sits one level up, in section groups — the JSON files used for layout areas like headers and footers. A section group can render up to 25 sections, and each of those sections can have up to 50 blocks; the same caps apply to the sections rendered by JSON templates. There's no stated mechanism for a warning or counter here either — just the cap and the consequence.
Section groups have one more wrinkle worth knowing when something renders differently per market: a contextual section group. When a merchant adapts a section group for a specific buyer context, Shopify creates a new file named like header-group.context.<context>.json, where the context is declared as either a market handle or b2b: true. It's a separate mechanic from the block and section caps, but it lives in the same /sections directory and is worth checking first when a header looks different in one market than another.
If you maintain a theme that's been through months of Sidekick-assisted iteration, an audit of /blocks for orphaned or duplicate files is worth doing before you hit 300 — not after a deploy stalls out because there's no room left for the block a client actually needs.