Getting Started

This guide walks through setting up both the theme and companion app for a new shop project.

Prerequisites

• Node.js 20+ and npm
• PHP 8.3+ with ext-redis
• Composer
• MySQL 8.0+
• Redis
• Shopify CLI

1. Clone the Repositories

# Theme
git clone <theme-repo-url> lamashopi
cd lamashopi && npm install

# Companion app
git clone <app-repo-url> app.lamashopi
cd app.lamashopi && composer install && npm install

2. Configure the Companion App

cp .env.example .env
php artisan key:generate

Set the required environment variables in .env:

SHOPIFY_SHOP_DOMAIN=my-shop.myshopify.com
SHOPIFY_CLIENT_ID=your-client-id
SHOPIFY_CLIENT_SECRET=your-client-secret
APP_URL=https://your-domain.com
DB_DATABASE=lamashopi_shopname

Enable the features you need:

SHOPIFY_FEATURE_INVENTORY=true
SHOPIFY_FEATURE_WISHLISTS=true
SHOPIFY_FEATURE_OOS=true
SHOPIFY_FEATURE_STORE_LOCATOR=false
SHOPIFY_FEATURE_BUNDLES=false

See App Setup for the full configuration reference.

3. Set Up the Database

php artisan migrate
php artisan user:create admin@agency.com --role=agency --password=<secure-password>

4. Create the Shopify App

1. Open the Shopify Dev Dashboard
2. Create a new app, then create a version with:
   • Scopes: read_products, read_inventory, read_customers, read_locations
   • App Proxy: prefix apps, subpath lamashopi, URL https://your-domain.com/shopify/proxy
3. Release the version and install on your store
4. Copy the Client ID and Client secret to .env

See Shopify Integration for detailed Dev Dashboard instructions.

5. Register Webhooks

php artisan shopify:register-webhooks
php artisan shopify:list-webhooks  # verify

WARNING

GDPR compliance webhooks (customers/data_request, customers/redact, shop/redact) must be configured manually in the Dev Dashboard version settings. Set the compliance webhook URL to https://your-domain.com/shopify/webhooks/.

6. Build Assets

# Theme
cd lamashopi && npm run build

# App
cd app.lamashopi && npm run build

7. Theme Development

The theme requires two terminal sessions:

# Terminal 1: Vite dev server (asset compilation + hot reload)
npm run dev

# Terminal 2: Shopify CLI (theme preview)
npm run server

See Theme Workflow for details on the development flow.

8. App Development

cd app.lamashopi
composer run dev  # Starts server, queue worker, log tail, and Vite

The app is served by Laravel Herd at https://app-lamashopi.test.

Quick Reference

Task	Command
Theme dev server	npm run dev (in theme directory)
Theme preview	npm run server (Shopify CLI)
App dev server	composer run dev
Run tests	php artisan test --compact
Format PHP	vendor/bin/pint --dirty
Lint theme JS	npm run lint:fix (in theme directory)
Build theme	npm run build (in theme directory)
Build app assets	npm run build (in app directory)