Creating and developing a theme

A theme is a folder of text files — templates, sections, snippets, CSS — that Riseact publishes as immutable versions. Organizations install a version and decide when to move to a newer one.

You need a Partner account. If you do not have one yet, follow the getting started guide.

Installing the CLI

Download the build for your operating system from the releases page, extract the archive and put the executable in a folder on your PATH.

Then authenticate:

riseact auth login

Starting from an existing theme

riseact theme init

It clones a starter theme and asks for the manifest.json details: name, identifier, version, author. It creates a folder named after the identifier you chose: that is where you will work. What the subfolders contain is in the theme structure.

The identifier is permanent

It is the key Riseact uses to recognise that a new version belongs to the same theme, and it cannot be changed. The command warns you if somebody else has already taken it.

If the theme already exists and you want to start from a published version:

riseact theme pull -p ./empty-folder

It asks which of your themes and which version, and downloads that version's files.

Developing with the live preview

cd your-theme
riseact theme dev

On the first run the command asks which organization to work on and installs the theme there. Then it prints two addresses: the public preview and the visual editor in the panel.

The theme is not published: it stays in the organization's theme library, and the site donors see does not change. Closing with Ctrl+C deletes nothing — next time you run theme dev in the same folder you carry on where you left off.

You need an organization to work on. If you have none, create a development organization from your partner profile: it is free and touches no real data.

The sync goes both ways

While theme dev is running, the folder and the theme stay aligned in both directions:

• you save a file → it is uploaded straight away, you only need to reload the preview page
• you change something in the visual editor and save → the matching file is updated in your folder

The second direction is the useful one. Colours, texts and page composition are easier to choose in the visual editor than by hand in a JSON file: compose the homepage by dragging sections, and templates/homepage.json in your folder updates itself. That file is the one that ends up in the release and defines how the theme looks when freshly installed.

On startup the command realigns both sides before it starts watching, so you also get back the changes made from the visual editor while you were not working.

note

In a conflict the most recent change wins. If the same file changed on both sides while theme dev was not running, the copy on the server is kept and the file name is printed on screen.

The command saves the session state in .riseact/dev.json inside the theme folder: which theme and which organization you are using. Add .riseact/ to your .gitignore and do not send it to anyone — deleting it makes the next theme dev start from a new theme.

Deleting files

A file removal is propagated only while theme dev is running. If you delete a section with the command stopped, it is downloaded again on restart: to the command, a file gone from disk and a new file on the server are indistinguishable, and downloading it back is the only recoverable mistake of the two.

Excluding files from upload

A theme often contains build tooling that should not end up on Riseact. List it in a .riseactignore file at the root of the theme, with the same syntax as .gitignore:

node_modules
package.json
package-lock.json
yarn.lock
tailwind.config.js
riseact.yml

The rules apply both to the package and to the sync during theme dev. .git, node_modules and .riseact are excluded anyway, even without the file.

danger

Always include riseact.yml: it is the file where the CLI stores your credentials, and without this line it would be uploaded as a theme file.

The compiled output, on the other hand, is needed. If you use Tailwind, assets/main.css has to be uploaded: that is the file the site actually reads.

Publishing a version

When the theme is ready, raise the version in manifest.json and publish:

riseact theme release

The command opens your editor to write the version's changelog. Organizations read it before deciding whether to update, so write it for them: what changes, not how.

Saving an empty message cancels the release.

If you would rather not use the CLI, riseact theme package prepares the zip you can upload from the Partner Area: the validation rules are the same.

Versioning rules

The version is written as MAJOR.MINOR.PATCH — 1.4.0 for example — and every release must have a version higher than the previous one. Suffixes such as 1.4.0-beta are not allowed.

A release is refused when:

• the version has already been published for that theme
• the version is lower than the latest published one
• the changelog is empty
• a file does not compile, or a section's {% schema %} block is not valid JSON

For file errors, the response lists every problem found with the path of each one, and no version is created. It is the check that stops you publishing a theme that would break on your clients' sites.

Versions are immutable

Once published, a version is never modified. To fix something you publish a new version. That is what lets an organization know exactly which files it has, and lets us tell it what would change by updating.

What the organization sees

In the panel, under Themes, every installed theme has a Theme version button. From there the organization can:

• pick a version from the list and read its changelog
• see which files, if it has edited any, would be overwritten by updating
• update the theme, or install that version as a separate theme

Updates only move forward. To go back to an earlier version it is installed as a new theme, without touching the published site.

What an update preserves

This distinction is the most important thing to understand when designing a theme.

files	on update
sections/, snippets/, layout/, assets/, config/settings_schema.json, templates/**/*.html	replaced by the new version
config/settings_data.json	kept; new settings are added with their default value
templates/**/*.json	kept; templates new to the version are added

In short: the theme's code is yours, the organization's choices are its own. If you change a section's HTML, the change reaches everybody. If you add a section to the homepage in your templates/homepage.json, that does not reach anyone who already has the theme installed — page composition belongs to the organization. It only reaches those who install it from scratch.

caution

If you rename or remove a section, the templates of the organizations using it will keep referencing it and the page will show an error in its place. Keep section names stable, or leave them in place even when you add a new one.

Distributing the theme

The versions you publish reach the organizations that already have your theme straight away. To let others install it, from the theme page in the Partner Area choose:

• My organizations — every organization you administer finds it in its theme store. No approval: they are your clients.
• Submit for Approval — to appear in the theme store, visible to every Riseact organization. We review it and reply by email.

The details are in Partner Area → Themes.

Template reference

How to write a theme's files — available variables, objects, tags, filters, section schema — is documented in the other pages of this section, starting from the theme engine overview.