Skip to content

Getting Started

Jump to bottom
Anthony Baggett edited this page Oct 24, 2026 · 4 revisions

Getting Started with VAST

Complete guide to installing and setting up VAST for development.

Prerequisites

Before you begin, ensure you have:

  • Node.js v22.12 or higher
  • Shopify CLI installed globally
  • A Shopify development store (you can create one from your Partners account)

Quick Start (Recommended)

The fastest way to get started with VAST is using the interactive setup wizard:

1. Clone the Repository

git clone https://github.com/anchovie91471/vast-shopify-theme <theme-directory>
cd <theme-directory>

2. Run the Setup Wizard

npm run setup

The interactive setup wizard will:

  • Install dependencies automatically
  • Connect to your Shopify store
  • Guide you through three setup options:
    • Auto-create (recommended): Let Shopify CLI automatically create a development theme
    • Use existing: Select from themes already on your store
    • Create new: Create a permanent unpublished theme with a custom name
  • Generate your shopify.theme.toml configuration
  • Run an initial build to create the assets

3. Start the Development Server

npm run dev

This starts both Vite and Shopify CLI dev servers.

4. Accept the SSL Certificate

When Vite starts, visit https://127.0.0.1:3000 in your browser:

  • Click "Advanced" and accept the security warning
  • Once accepted, navigate to http://127.0.0.1:9292 to see your theme preview

That's it! Your theme is now running and ready for development.

Understanding Setup Paths

The setup wizard offers three ways to configure your development theme, depending on your needs:

Auto-create Development Theme (Recommended for New Users)

What it does:

  • Creates a minimal shopify.theme.toml with only your store name
  • Shopify CLI automatically creates a temporary development theme when you run npm run dev
  • No manual theme selection or configuration required

Best for:

  • First-time setup
  • Quick starts when you don't have an existing development theme
  • Solo developers who want the simplest workflow

Important Notes:

  • Development themes are temporary and deleted when you run shopify auth logout
  • Each authenticated session gets its own development theme
  • Perfect for getting started quickly without worrying about theme IDs

Example shopify.theme.toml (auto-create mode):

[environments.development]
store = "your-store-name"
# No theme ID - Shopify CLI creates one automatically

Use Existing Theme

What it does:

  • Fetches all themes from your store
  • Lets you select an existing theme (development, unpublished, or live)
  • Adds the theme ID to your shopify.theme.toml

Best for:

  • Teams working on the same development theme
  • When you already have a development theme set up
  • Switching between multiple theme projects
  • Working with an existing unpublished theme

Important Notes:

  • Choose carefully—selecting a live theme requires extra confirmation to prevent accidental overwrites
  • Development themes created by other team members will appear in the list
  • You can select any unpublished theme for safe development

Example shopify.theme.toml (existing theme):

[environments.development]
store = "your-store-name"
theme = "123456789"  # ID of selected theme

Create New Unpublished Theme

What it does:

  • Prompts for a custom theme name (e.g., "VAST Development", "Feature Branch Alpha")
  • Builds your theme assets
  • Pushes to Shopify and creates a new unpublished theme
  • Adds the theme ID to your shopify.theme.toml

Best for:

  • Long-term development themes that persist after logout
  • Creating named themes for specific features or branches
  • Permanent staging environments
  • When you want full control over theme naming

Important Notes:

  • This option runs a full build and push, which may take a minute on first setup
  • The theme persists on your store even after shopify auth logout
  • Great for feature branch workflows where each branch gets its own theme
  • If creation fails, you can fall back to auto-create mode

Example shopify.theme.toml (created theme):

[environments.development]
store = "your-store-name"
theme = "987654321"  # ID of newly created theme

Which Path Should I Choose?

Situation Recommended Path Why
First time installing VAST Auto-create Simplest setup, no theme ID needed
Solo developer, quick start Auto-create Minimal configuration, automatic management
Team development Use existing Share the same development theme across team
Feature branch workflow Create new Each branch gets its own named theme
Need theme to persist after logout Create new Permanent unpublished themes stay on store
Already have a dev theme Use existing Continue using your existing setup

Manual Installation (Alternative)

If you prefer to set up manually or the wizard doesn't work:

1. Install Dependencies

npm install --legacy-peer-deps

Note: The --legacy-peer-deps flag is required due to a peer dependency conflict between Vite 7 and @by-association-only/vite-plugin-shopify-clean (which currently only supports Vite 5-6). The plugin works correctly with Vite 7 despite the version mismatch.

2. Configure Shopify CLI

Create a shopify.theme.toml file in the root directory:

[environments.development]
store = "your-store-name"
theme = "123456789"  # Your theme ID

[environments.staging]
store = "your-store-name"
theme = "987654321"
ignore = ["templates/*", "config/*"]

[environments.production]
store = "your-store-name"
theme = "111222333"
ignore = ["templates/*", "config/*"]

3. Start Development

npm run dev

This runs Vite dev server (port 3000) and Shopify CLI dev server concurrently.

SSL/HTTPS Setup

The theme uses self-signed SSL certificates for local development. If assets aren't loading:

  1. Visit https://127.0.0.1:3000 in your browser
  2. Click "Advanced" and proceed past the security warning
  3. Return to your Shopify dev server at http://127.0.0.1:9292

CORS for Custom Domains

If using a custom domain (not *.myshopify.com), add it to vite.config.js:

server: {
  cors: {
    origin: [
      /^https?:\/\/(?:(?:[^:]+\.)?localhost|127\.0\.0\.1|\[::1\])(?::\d+)?$/,
      /^https:\/\/[^\/]+\.myshopify\.com$/,
      'https://yourcustomdomain.com'  // Add your domain
    ]
  }
}

Deployment Strategies

VAST supports two deployment approaches—choose whichever fits your workflow best, or use both!

Option 1: GitHub Integration (Automatic)

Connect your theme to a GitHub repository for automatic deployment when you push changes.

How it works:

  • Push code to GitHub → Shopify automatically syncs changes to your theme
  • Great for teams, CI/CD workflows, and version control-first development
  • .gitignore is already configured to work with Shopify's GitHub integration

Setup:

  1. Push your theme to a GitHub repository
  2. In Shopify Admin: Online Store → Themes → Add theme → Connect from GitHub
  3. Select your repository and branch
  4. Shopify will automatically deploy on every push

Learn more about Shopify GitHub integration

Option 2: Shopify CLI Push (Manual)

Use CLI commands for direct deployment from your local machine.

How it works:

  • Run deployment commands → Theme pushed directly to Shopify
  • Great for solo developers, manual control, and testing before deploy
  • Uses shopify.theme.toml for environment configuration

Commands:

npm run deploy        # Push to production (interactive)
npm run deploy:dev    # Push to development environment
npm run deploy:staging # Push to staging environment
npm run deploy:new    # Create new unpublished theme

See Build and Deployment for more details.

Using Both

These approaches aren't mutually exclusive! Many developers use:

  • GitHub integration for staging/production (automatic deploys)
  • CLI push for development (quick manual testing)

Next Steps

← Back to Home

Clone this wiki locally