Skip to main content

​
Import, Export, And Upgrades

This page explains theme import/export/upgrade behavior at a practical level.
This page is “how it works in practice”, not an API reference. If you are building a theme, you mostly care about file structure and build output.

​
Theme Files (Editable vs Read-Only)

When themes are edited through a web editor, some paths are treated as read-only:
  • lockfiles (bun.lockb, pnpm-lock.yaml, yarn.lock)
  • node_modules/
This is mainly to keep builds stable and prevent huge/unbounded edits.

​
Export

Export means:
  • download the theme source files
  • include metadata (like theme.json or manifest)

​
Import

Import means:
  • upload a theme package
  • validate it (does it look like a theme project?)
  • store it as an editable theme project in Shoppex

​
Upgrades

An upgrade usually means:
  • take a newer upstream version of a theme
  • merge it with user changes
  • flag conflicts if the same file changed in both places
Think of it like a controlled “template update” workflow.

​
Quick Mental Model

1

Import

Upload a theme project (source files). Shoppex stores it as an editable theme project.
2

Build

Shoppex runs bun install + bun run build and publishes the dist/ output as static files.
3

Upgrade

Apply an upstream update to your theme project while trying to keep your edits. Conflicts may happen.
The import/export/upgrade implementation is platform-internal. The important part for theme developers is your project structure and the dist/ build output.

​
Next Steps

Theme Package Format

What files matter for import/export.

Build Pipeline

How the platform turns source files into a deployed storefront.