Build your first theme

Install the theme tools, create a theme from the starter, preview and edit it, then upload it and install it on a development store.

This guide takes you from an empty folder to your own theme running on a development store. You need Git and a developer organization in the Developer Portal.

Install the Tringify CLI#

The Tringify CLI provides the tringify command. It creates, previews, validates and packages themes, and uploads them to your organization and development stores. On macOS or Linux, run:

bash

curl -fsSL https://raw.githubusercontent.com/tringify/cli/main/install.sh | sh

On Windows, download tringify-windows-amd64.zip from Releases, check it against SHA256SUMS, and add tringify.exe to your path. Then confirm the installation:

bash

tringify version

The CLI is a single program; it needs no Python or other runtime. The first time you check, package or preview a theme, it downloads the theme validator and preview renderer from the theme tools release for your platform, verifies their checksums, and keeps them in your user cache folder.

Set up your editor#

If you use Visual Studio Code, install the Vascula for Tringify Themes extension. It highlights .vasc files and section sources, completes filters, setting ids and ctx_needs names, and checks section schemas, theme.json and templates as you type. Download the .vsix file from its releases, then run Extensions: Install from VSIX… from the Command Palette.

Create a theme from the starter#

The starter theme has a template for every storefront page, editable sections, two style presets and a demo catalog. Create your theme from it:

bash

tringify theme init my-theme --name "My Theme"
cd my-theme
git init && git add . && git commit -m "Start My Theme"

init downloads the starter, copies it into a new folder, sets the theme name, builds the sections and validates the result. Keep the theme in git: publishing records the commit each version is built from. To host it on GitHub, push the folder to a new repository.

Path	Contains
`src/sections/<name>/`	Each section's `body.html`, `style.css` and `schema.json`. Edit these.
`src/_shared.css`	Styles shared by every section.
`sections/*.vasc`	Compiled sections, generated by `tringify theme build`.
`templates/`	Which sections each page shows, in order.
`blocks/`	Reusable theme blocks.
`config/`	Theme settings and style presets.
`locales/`	Shopper text (`en.json`) and editor labels (`en.schema.json`).
`demo/`	Sample products, pages and images for previews.
`theme.json`	Theme name, section index and page permissions.

See Theme package structure for every file.

Preview your theme#

bash

tringify theme preview

Open the printed URL. Choose a page from the list and switch between desktop and mobile widths. The preview uses the products and pages in demo/catalog.json. Forms, sign-in, cart changes and checkout are disabled; you will test those on a development store. Leave the preview running while you edit; it rebuilds when you save a file.

Edit a section#

Add a short note to the Rich Text section on the home page. First declare a setting in src/sections/starter-rich-text/schema.json by adding it to the settings array:

json

{
  "id": "note",
  "type": "text",
  "default": "Made in small batches.",
  "editor": { "label": "note", "group": "content" }
}

Give the setting an editor label in locales/en.schema.json:

json

"fieldLabel.note": "Note"

Then render it in src/sections/starter-rich-text/body.html, below the text:

vascula

{% if settings.note %}
  <p class="starter-note">{{ settings.note }}</p>
{% endif %}

Save the files and the preview shows the note on the home page. Merchants can now change it in the theme editor. Sections read store data through ctx_needs; run tringify theme context . --page product to see the data a page provides. Learn more in Sections and Section schema.

Check and package#

bash

tringify theme build
tringify theme check
tringify theme package

build compiles your section sources into sections/, and check validates the compiled theme with the same rules used when you upload it; run build before check after editing sources. package builds and validates in a temporary copy and writes dist/my-theme.zip. When validation fails, the message names the file and the reason; fix the source and run the command again.

Create a listing#

Sign in to the Developer Portal, open your organization, open Themes and select Create Theme. Enter a name and a slug. You do this once per theme; the listing holds the name, pricing and review details.

Publish a version from the CLI#

Sign in once. Your browser opens; choose your developer organization and approve access to its themes. Then find your listing's ID:

bash

tringify login
tringify theme listings

Commit your changes, then publish. publish only runs from a clean git checkout; it packages and validates the theme, publishes the version and records the commit in its release notes:

bash

git add . && git commit -m "My Theme 1.0.0"
tringify theme publish --listing LISTING_ID --version 1.0.0 --notes "First version"

A published version cannot change. Publish a new version number for every update.

Install on a development store#

Development stores are free stores for building and testing. Create one from the CLI, or open Dev Stores in the Developer Portal and select Create Dev Store. See Development and transfer stores.

bash

tringify store create --name "Theme Lab" --country IN --currency INR

Then run tringify theme dev with the store ID it prints. The first run opens your browser to choose that store and approve access to its themes, and adds your theme unpublished; the store's live theme does not change. Leave it running: every time you save, it builds, validates and syncs your theme to the store.

bash

tringify theme dev --store STORE_ID

To add a one-off copy instead, use tringify theme push --store STORE_ID. To install a published version, add --install-store STORE_ID to tringify theme publish, or select Install in dev store next to the version on your theme page in the Developer Portal.

In that store's Store Admin, open Storefronts, select the storefront and open its themes. Preview and customize your theme there, and refresh the preview after each sync. Select Make live to show it on the storefront. Development storefronts stay password-protected.

Test before you publish#

Test with the store's own products: variants, sale prices, long titles, missing images, the cart, Buy Now, sign-in and registration, and every page at mobile and desktop widths. Then update your theme by publishing a new version and updating the installed copy.

When your theme is ready for merchants, complete its listing and submit it for review. See Publish in the Theme Store.