Testing & Previewing

Learn how to test and preview your themes during development.

Three ways to preview a theme

Workflow	Who uses it	What you get
Theme Development Kit (local)	Theme developers	Hot reload, real store data, full Liquid — recommended for day-to-day work
Deployed theme on a store	After `finqu theme deploy` or partner publish	Production-like behavior on a live or staging store
Admin designer preview	Merchants editing in Finqu admin	Preview draft theme changes before publishing; unpublished products and articles are visible in preview

Use ThemeDev while building. Deploy to a test store before submission. Merchants use the admin designer separately — you do not need to replicate that workflow locally.

Local development (recommended)

The recommended way to develop and preview Liquid themes locally is the Theme Development Kit. It runs a local server that renders your theme with real store data and supports hot reload.

Install the Theme Development Kit.
Follow Getting started to authenticate and run finqu-theme-dev serve (or use finqu theme dev from the CLI).
Open the local URL in your browser and iterate on your theme.

When you are ready, deploy with the CLI (finqu theme deploy) or publish through the partner portal.

ThemeDev API

The Theme Development Kit talks to your store through these endpoints:

Endpoint	Purpose
`POST /api/themedev/init`	Authenticate (Bearer token) and upload initial theme files (tar.gz)
`POST /api/themedev/delta`	Push file changes (tar.gz) or removals (`X-Removed-Files` header)
`POST /api/themedev/render`	Request server-side HTML for a page type, resource handle, and language
`GET /api/themedev/routes`	Discover products, pages, categories, and system URLs for preview

All requests after init require the X-Session-Id header returned from the session.

See Theme Development Kit overview for full setup and configuration.

Live storefront preview

While a ThemeDev session is active, you can preview your local theme on the real storefront by sending the X-ThemeDev-Session header with your session ID. The store loads your uploaded files instead of the deployed theme for that channel.

Compiled assets are served from a temporary path (/themedev-{sessionId}/...). Use asset_url in your Liquid as usual — the platform resolves the correct URLs during preview.

Upload limits

ThemeDev validates every uploaded file:

Limit	Value
Max file size	2 MB
Max bundle size	20 MB
Max file count	500

Allowed directories: assets, config, layout, locales, sections, snippets, templates, public, modules.

Allowed extensions include liquid, json, css, scss, js, common image and font formats.

Note: If you use blocks/ or section-groups/ directories, include them in your full theme deploy. ThemeDev’s upload allowlist may not accept every directory — use finqu theme deploy to verify a complete theme package.

Admin designer preview

When a merchant edits a theme in the Finqu admin designer, changes are held as a draft until they publish. In preview mode:

Draft section and setting changes are visible before going live.
Unpublished products and articles can appear in the preview so merchants can verify layout before launch.

As a theme author you do not configure this — it is built into the designer. Test your theme locally with ThemeDev; ask merchants to use designer preview for post-deploy customization.

Testing strategies

Test your theme across the page types your channel requires (see Theme Submission Guidelines).

Recommended checklist:

Templates — Open every template type (frontpage, product, cart, customer account pages, etc.) with real and edge-case data (empty cart, long product titles, missing images).
Section groups — Verify header and footer groups render and reorder correctly on multiple templates.
Blocks — Test layout blocks with nested containers, private child blocks, and allowed_blocks restrictions.
Settings — Exercise theme, section, and block settings including setting_blocks, color styles, and resource pickers (product, menu, page).
Locales — Switch languages and confirm locales/ strings and schema labels render correctly.
Assets — Confirm compiled CSS loads after deploy (asset_url); check SVG icons via inline_asset_content or svg_tag.
Forms — Submit customer, cart, and search forms on a deployed test store.
Responsive — Test common breakpoints for header, product grid, and cart.

Common issues

Problem	Likely cause	What to do
Styles missing after deploy	Source SCSS not compiled to `public/`	Run deploy/publish so assets compile; always reference CSS via `asset_url`
Section not in “add section” list	`templates` or `section_groups` restriction	Check section schema matches current template type and group
Block not addable	`private`, `allowed_blocks`, or `templates` mismatch	See Blocks
ThemeDev session expired	Session timed out	Re-run `finqu-theme-dev serve` and re-initialize
Preview shows old theme	Deployed theme still active	Confirm `X-ThemeDev-Session` header or redeploy
Liquid error on one page only	Template-specific object missing	Guard with `{% if %}` and test with empty collections