Packaging

Once your theme is ready, it can be packaged into a distributable archive using the Masthead CLI.

Packaged themes can be uploaded to Masthead or shared with others for installation on self-hosted instances.

Packaging a theme

From the root of your theme, run:

masthead package

Before creating the archive, the CLI validates the theme to ensure it meets the same requirements enforced by Masthead.

If validation succeeds, the resulting ZIP archive is written to your Desktop by default using the theme’s slug and version.

my-theme-1.0.0.zip

Choosing an output location

Use the --out option to choose where the archive should be written.

masthead package --out ./dist

You can also provide an exact filename.

masthead package --out ./dist/my-theme.zip

The short form is also available.

masthead package -o ./dist/my-theme.zip

Versioning

The CLI can automatically bump the theme version before packaging.

masthead package --bump patch

Supported version increments are:

• patch
• minor
• major

The updated version is written back to the theme manifest before the archive is created.

Included files

Only files required by Masthead are included in the package.

Typical contents include:

manifest.json
theme.css
templates/
assets/

Development files are excluded automatically, including:

preview.json
preview.local.json
README.md
.git/
*.zip

This keeps packaged themes small and ensures no local development data is accidentally distributed.

Validation

Packaging always performs a full validation before creating the archive.

Validation includes:

• Theme manifest
• Liquid templates
• Theme page definitions
• Theme tokens
• Page metadata

If validation fails, the package is not created until the reported issues have been resolved.

Installing a packaged theme

Packaged themes can be uploaded through Masthead or installed on a self-hosted instance.

When uploading a theme, Masthead identifies it by its slug.

• If no theme with that slug exists, a new theme is created.
• If a theme with the same slug already exists and the uploaded version is newer, the existing theme is updated.
• If the uploaded version is the same or older than the installed version, the upload is rejected.

This allows theme authors to distribute updates while preserving existing installations. Site owners can then upgrade to the latest version without changing the theme they have installed.