Skip to main content

Getting Started

Creating a block​

Blocks are added from the custom blocks library manager in the app editor. Picking a block type creates a new entry with starter code for that type (a minimal Hello custom block! component if the type has no specific default). From there it's edited like any other file, with a live preview updating as you type.

Each block is stored as a JS object with (at minimum) an id, a name, a type (one of the block types), and a jsx field holding its TSX source. Blocks with settings (see below) also carry data and configurationSchema.

Blocks without settings vs. blocks with settings​

Block types fall into two layout kinds:

  • Without settings - product-display-card, collection-display-card, product-sticker, product-information. Just one .tsx file, no merchant-configurable settings panel.
  • With settings - header, footer, drawer-menu, section, page. A small folder per block instance:
    • index.tsx - the component source
    • data.json - the default/preview values for that instance's configurable fields
    • configurationSchema.json - the settings-panel field definitions (see Settings Panel)

Each block instance's folder/file name is a slugified version of its name (lowercase, hyphen-separated), nested under a folder for its type (e.g. a section named "Hero Banner" lives at sections/hero-banner/index.tsx).

Live preview​

Your TSX is transpiled with Babel directly in the browser as you type and rendered immediately in the preview pane - there's no deploy step to see a change. The same transpiled build is what actually ships to the live storefront, so what you see in the preview is what shoppers get once you save.

Generating a block with AI​

Instead of writing code by hand, you can describe the block you want (optionally attaching a reference screenshot) and have it generated for you. The assistant:

  • only has access to the same packages and component library documented here - it never invents an import that isn't available in the sandboxed runtime
  • for a block with settings, also generates data and configurationSchema for whatever configurable content the description implies
  • can be pointed at an existing block afterward ("modify with AI") to apply a follow-up change to it, preserving the rest of the code as-is

The same rules documented on the Block Types and Settings Panel pages apply whether the code was generated or written by hand.

Constraints​

  • Only a default-exported function component - no named exports, no class components.
  • Only the packages in the available packages list can be imported. No relative/local imports, and no browser-only globals (window, document, fetch).
  • A block should render only what its type is for (see each type's "Where & how it's rendered" section) - e.g. a product-sticker should stay a small overlay badge, not a full product card.