Quick start

This guide takes you from nothing to a live preview of your own theme in about ten minutes.

You need staff access to the firm with the Manage themes permission (the firm owner always has it), and a terminal: Terminal on macOS, PowerShell on Windows.

1. Install Node.js and the theme CLI#

The theme CLI is the npm package @mattersimple/theme. It runs on Node.js 20.10 or newer.

1. Install Node.js: download the LTS installer from nodejs.org and run it. npm comes with it. Then, in a new terminal window, check the versions:

   Terminal

   node --version    # v20.10.0 or newer
   npm --version
   

2. Install the CLI:

   Terminal

   npm install --global @mattersimple/theme
   

3. Check it works:

   Terminal

   mattersimple-theme --version
   mattersimple-theme --help     # every command and option
   

To update it later, run npm install --global @mattersimple/theme@latest.

If npm answers with a permissions error (EACCES) on macOS or Linux, don't use sudo: follow npm's guide to fixing permissions for global packages, or skip the global install and put npx @mattersimple/theme in front of each command instead (npx @mattersimple/theme login …). npx downloads the CLI the first time and reuses it after.

Every theme project also gets its own copy of the CLI in node_modules/, listed in its package.json, so a teammate who clones your theme only needs npm install. Inside a theme folder, npm run dev and npx mattersimple-theme … use that copy.

2. Create a developer token#

1. In your firm's admin, open Themes.
2. Click Developer tools → Developer access.
3. Give the token a name (for example, the computer you work on), choose when it expires, and click Create token.
4. Copy the Sign the CLI in command it shows. The token is shown only once.

A token acts as you, on this firm only, and only for themes: it can create, change, preview and publish themes. Revoke it from the same dialog when you no longer need it. Tokens also stop working if you lose permission to manage the firm's themes.

3. Sign in and create a theme#

Paste the command you copied. It starts with npx @mattersimple/theme, which works whether or not you installed the CLI globally:

npx @mattersimple/theme login --host https://<platform address> --token rtk_…

It answers with the firm's name, for example ✔ Signed in to The Coders as Ada Lovelace. You only sign in once per computer. Then create your theme:

mattersimple-theme init my-theme --name "My theme"
cd my-theme

init downloads the starter kit (also under Developer tools → Download starter kit), unpacks it into my-theme/ and runs npm install. You get:

my-theme/
  layout/  
  sections/  
  snippets/  
  templates/  
  config/  
  locales/  
  assets/theme.css  
  assets/theme.js
  screenshots/  
  theme.json  
  README.md
  src/theme.css        ← your stylesheet source (Tailwind CSS)
  package.json         ← build scripts
  docs/                ← this guide

4. Start the live preview#

npm run dev

This:

1. builds your CSS and keeps rebuilding it as you edit,
2. uploads the theme as your private development theme (it doesn't appear in the firm's theme library, and visitors never see it),
3. prints two links and opens the preview in your browser,
4. pushes every file you save. The preview reloads itself after each push.

The console shows something like this:

Uploading your theme to its development theme…
✔ Synced to My theme.
  Preview: https://<firm>.<platform address>/_theme-preview/<id>?expires=…&signature=…
  Editor:  https://<platform address>/firms/<firm>/admin/themes/<id>/editor
  The preview link is valid for 12 hours.

Watching for changes. Press Ctrl+C to stop.

Use npm run dev -- --no-open if you don't want the preview to open by itself; the links are printed either way.

Open sections/hero.liquid, change some text, save, and watch the preview update. Each push is listed in the console with the files it sent.

The development theme is deleted after 7 days without a push. Run npm run dev again to recreate it.

5. Ship it#

When your theme is ready:

npm run push        # uploads it to the firm's theme library, unpublished

The command prints a preview link and a link to the theme editor. Customise it there, then publish it from Website → Themes, or with npx mattersimple-theme publish --theme <id>.

To update the theme later:

npx mattersimple-theme list                      # find its id
npx mattersimple-theme push --theme <id>         # sends only what changed

Pages and settings changed in the theme editor are kept: a push only sends the JSON documents you changed locally since your last push. Run npx mattersimple-theme pull --theme <id> --only-json first to bring the editor's changes into your project.

Without the CLI#

npm run build:css

Then zip the folder and upload it in Website → Themes → Upload a theme. To update an uploaded theme, open its ⋯ menu and choose Upload new version. Development files (src/, node_modules/, package.json, docs/, dotfiles) are skipped automatically. npx mattersimple-theme package builds a clean zip in dist/ if you prefer.

Before you publish#

• Replace screenshots/desktop.png (at least 1600×1000) with a screenshot of your theme. It's shown in the theme library.
• Set name, version and author in theme.json.
• Check every template: home, the page layouts (contact, legal…), practice areas and a practice area, the blog, an archive and an article, the sign-in and invitation pages, a missing page (404), and the client portal's account pages.