Setup

Requirements

• PHP 8.3+ with ext-redis (or use predis)
• MySQL 8.0+
• Redis
• Node.js 20+ / npm
• Composer

Quick Start

git clone <repo-url> app.<shop-name>
cd app.<shop-name>
composer install
npm install

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

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

npm run build
php artisan shopify:register-webhooks

There is also a composer setup script that runs install, env setup, migrations, and build in sequence.

Environment Configuration

Required Variables

Variable	Description	Example
SHOPIFY_SHOP_DOMAIN	Shopify store domain	my-shop.myshopify.com
SHOPIFY_CLIENT_ID	Client ID from Dev Dashboard
SHOPIFY_CLIENT_SECRET	Client secret for token exchange and HMAC
APP_URL	Public URL of this deployment	https://app.example.com
DB_DATABASE	Dedicated database for this shop	lamashopi_shopname

Feature Flags

Enable or disable features per deployment:

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

When a feature is disabled, its routes are not registered and its Filament resources are hidden.

Mail (Required for OOS)

MAIL_MAILER=postmark
POSTMARK_API_KEY=your-postmark-key
MAIL_FROM_ADDRESS=noreply@your-domain.com

Klaviyo (Optional)

KLAVIYO_ENABLED=false
KLAVIYO_API_KEY=
KLAVIYO_OOS_ENABLED=false

When KLAVIYO_OOS_ENABLED=true, Klaviyo handles OOS email flows instead of the built-in mailer.

Error Monitoring

FLARE_KEY=your-flare-key

Cache

Redis is required for inventory caching, rate limiting, and access token management:

CACHE_STORE=redis
REDIS_CLIENT=phpredis

Location Slug Mapping (Optional)

Map Shopify location GIDs to URL-friendly slugs:

SHOPIFY_LOCATION_SLUGS={"Amsterdam Warehouse":"amsterdam","Berlin Hub":"berlin"}

Admin Panel Paths

AGENCY_PANEL_PATH=agency
ADMIN_PANEL_PATH=admin

Development

composer run dev

This starts the server, queue worker, log tail, and Vite in a single command.

The app is served by Laravel Herd at https://app-lamashopi.test (or your project's Herd domain).

Running Tests

php artisan test --compact                     # Full suite
php artisan test --compact --filter=Wishlist    # Filtered

Code Formatting

vendor/bin/pint --dirty    # Format changed files
vendor/bin/pint            # Format all files