Skip to Content
APIs & ToolsTheme Development KitConfiguration and features

This page describes how to configure the Theme Development Kit and what it offers for local theme development.

Configuration

The Theme Development Kit can be configured with an optional .env file in your theme (or project) root. All fields are optional; defaults are used when a value is omitted.

Project config file

Create .env in the same directory you run finqu-theme-dev serve from (typically the theme root). When you use finqu theme dev, this is the same .env file as the CLI configuration.

Override the listen port per run with the --port / -p flag (default 3000):

finqu-theme-dev serve --port 8080

Command-line options take precedence over values in .env. Use --port to avoid clashes with other tools.

If you still have a legacy finqu.config.json, convert it with finqu migrate.

Credentials and auth

Authentication is handled by the finqu-theme-dev auth command. Credentials are stored in ~/.finqu-theme-dev/credentials.json and are not configured via .env. You only need to run auth once per machine (or when you switch store or channel).

Features

The Theme Development Kit is built for fast, realistic local development of Finqu Liquid themes.

Live preview with real store data

The dev server fetches data from your live Finqu store (products, collections, pages, cart, customer, etc.) and renders your theme with that data. You see the same content and behavior you’ll get in production, without deploying. This avoids mock data and surprises when going live.

Hot reload

When you save changes to Liquid files, styles, or scripts, the server detects the change and triggers a browser refresh (or injects updates where supported). You don’t need to restart the server or reload the page manually for most edits.

Full theme support

The same theme structure and features supported in production work locally:

  • Liquid templates — Layouts, templates, sections, snippets, and blocks.
  • Theme configuration — config/settings_schema.json and config/settings_data.json are read and applied.
  • Assets — SCSS (compiled with Dart Sass), .liquid assets, JavaScript, images, fonts, and SVGs. Use the asset_url filter and standard theme asset layout as in production.
  • Locales — Translation files in locales/ are loaded so you can test multiple languages.

You can develop and debug the full theme surface locally before pushing to Finqu.

Simple workflow

  • Authenticate once — finqu-theme-dev auth stores credentials for your store and channel.
  • Serve from the theme directory — finqu-theme-dev serve (optionally with --port or --dir) starts the server. Open the URL in your browser and start editing.

No build step or extra tooling is required beyond the single binary and your theme files. You can run the kit directly (finqu-theme-dev serve) or via the CLI: finqu theme dev, which uses the kit under the hood. For theme configure, download, and deploy workflows (syncing with the Finqu backend), use the Command Line Interface (CLI) (finqu theme configure, finqu theme download, finqu theme deploy).