Skip to main content

Getting Started: Installation, Initialization & Local Watch

Setting up your environment for SitePack theme development is simple and highly automated. This step-by-step guide will walk you through preparing your machine, initializing your first theme project, starting local hot-reloading development, and publishing a release to the SitePack Marketplace.

Step 1: Fulfill the Prerequisites​

Before initiating your project, make sure you have configured your environment with the following items:

1. The SitePack CLI Tool​

You must have the SitePack command-line tool installed on your computer. The CLI is the central driver for syncing local files, watching changes, and managing themes.

2. A SitePack Partner Account​

All themes are owned and deployed on behalf of a partner organization.

  • Create Organization: You can register or join a partner organization for free via the SitePack Partner Dashboard.
  • Organization CLI Management: You can check which organization you are active in directly from your terminal by running sitepack whoami. If you belong to multiple organizations, you can change your active workspace using sitepack partner:change-organisation. Learn more about Managing Organizations.

Step 2: Initialize Your Theme Project​

With your CLI authenticated, choose a directory in your terminal where you want to store your local theme projects, and run the initialization command:

sitepack theme:init

The CLI interactive wizard will guide you through the setup process step-by-step:

  1. Organization Verification: If your developer profile is connected to multiple organizations, the wizard will display a menu and ask you to select the organization that will own the new theme.
  2. Target Directory Name: Specify the local directory folder where the project should be initialized (defaults to my-theme).
  3. Theme Display Name: Input a user-friendly name for your theme (e.g., Summit Minimalist). This name will be registered in your manifest file and can be edited later.

What Happens Under the Hood?​

When you run sitepack theme:init, the CLI requests a new theme UUID from the SitePack API, clones the Official SitePack Theme Skeleton straight into your specified target directory, then writes your new uuid, name, and author into theme.json automatically — so you never have to hand-edit those fields yourself.

Step 3: Local Development & Live Synchronization​

SitePack features an advanced, near-zero-latency watch engine. Instead of requiring you to run a heavy database or server infrastructure locally, the SitePack CLI stream-uploads code changes securely to our staging server in real-time.

Navigate into your newly initialized theme directory in your terminal:

cd your-theme-directory

And execute the watch process:

sitepack theme:watch

Explaining sitepack theme:watch​

  • Active Monitoring: The CLI boots a lightweight background watcher that listens for any file creations, edits, or deletions across your template, config, translations, and asset directories.
  • Instant Synchronization: When you hit save in your code editor (e.g., VS Code, PHPStorm), the CLI securely syncs the changed lines directly to your staging environment in a fraction of a second.
  • Staging Environment Preview: You can interactively preview and click through your theme using the special staging prefix combined with your SitePack store domain: https://staging-[your-subdomain].sitepack.app

:::tip Pro Development Tip Keep your terminal window running sitepack theme:watch open while you write code. It acts as an instant deployment logger, showing you file sync confirmations or template compilation errors. :::

Step 4: Version Control Best Practices​

It is strongly recommended to track your theme development with a version control system like Git. This provides incremental backups, allows collaborative development, and keeps a clear history of your design changes.

Initialize Git inside your root theme directory:

git init

Suggested .gitignore Configuration​

Create a .gitignore file in your theme's root directory to prevent pushing temporary build assets or local configurations:

# Local Node modules or build caches
node_modules/
.DS_Store
Thumbs.db

# Temp IDE or workspace folders
.idea/
.vscode/

# Build or distribution outputs from custom pipelines
dist/
build/

Step 5: Publishing Your Theme Release​

When you have thoroughly built and tested your storefront skin and are ready to deploy a production-ready version, you can compile and publish it to the SitePack cloud.

In your theme directory, execute the publishing command:

sitepack theme:publish

The Deployment Process:​

  1. Integrity Checks: The CLI checks your theme.json to ensure valid JSON structures and metadata definitions.
  2. Asset Upload & Distribution: Static resources in your assets directory are safely synchronized and uploaded to the globally edge-cached SitePack CDN. Remember that SitePack does not compile SCSS/Sass or minify CSS files; you should supply your final completed build with minified CSS directly in the assets folder.
  3. Active Version Update: The new code is tagged as the latest release, instantly updating all merchant stores actively linked to this theme.

Step 6: Managing Distribution and Pricing​

Once published, navigate to the SitePack Partner Dashboard to configure how merchants can interact with your creation:

  • Custom Store Mapping: Link the theme to specific client stores under your direct management to test in production or build a custom layout.
  • Visibility Control:
    • Keep Private: Limit installation access strictly to your own organization or select white-listed store IDs.
    • Go Public: Publish your creation on the official SitePack Theme Marketplace.
  • Monetization Configuration: Select a monetization plan that fits your business model: Free distribution, One-time lifetime licenses, or recurring monthly/yearly subscriptions. Learn more in the Publishing & Monetization guide.

Exploring Further:​

Now that your local environment is humming, learn how your theme directory and page templates are mapped out in the Directory Structure documentation!