madock can scaffold a Shopify project from any of four SDK/framework presets, each backed by a different container stack:
| Preset | Language | Use case | Stack |
|---|---|---|---|
hydrogen |
Node + TS | Headless storefront (deploys to Shopify Oxygen) | Node 22 only |
app-remix |
Node + TS | Embedded Shopify App for App Store | Node 22 + Prisma/SQLite |
api-php |
PHP | Backend integration via official shopify-api SDK | PHP 8.3 + MariaDB + Redis |
laravel-shopify |
PHP/Laravel | Full Shopify App on Laravel (Kyon147/laravel-shopify) | PHP 8.3 + Node + MariaDB + Redis |
Pick the preset and let madock scaffold + boot containers in one shot:
# In an empty project directory
madock setup -d -i -s --platform shopify --preset hydrogen # Node storefront
madock setup -d -i -s --platform shopify --preset app-remix # Node embedded app
madock setup -d -i -s --platform shopify --preset api-php # PHP backend SDK
madock setup -d -i -s --platform shopify --preset laravel-shopify # PHP/Laravel appWithout --preset the setup wizard pops a picker. Aliases work too: --preset node, --preset storefront → hydrogen; --preset app, --preset remix → app-remix; --preset php, --preset api → api-php; --preset laravel → laravel-shopify.
Scaffolds npm create @shopify/hydrogen@latest (Remix on Vite, TypeScript, Oxygen worker). Install runs npm install and:
- patches
package.jsonto add--hostto thedevscript so the Hydrogen dev server binds0.0.0.0(default is 127.0.0.1) - attempts to add
server.allowedHosts: truetovite.config.ts(Hydrogen wraps Vite via the Oxygen plugin; if the dev server still returnsBlocked request. This host ... is not allowed.add the project host manually — see gotchas below)
Wire it to a real store by setting in .env:
PUBLIC_STORE_DOMAIN=your-store.myshopify.com
PUBLIC_STOREFRONT_API_TOKEN=...
SESSION_SECRET=...Open https://loc.<project>.com — Hydrogen serves the storefront via the nodejs container on port 3000.
Scaffolds npm init @shopify/app@latest (Remix + Prisma + App Bridge). Install runs npm install and npx prisma generate && npx prisma migrate deploy (Prisma uses SQLite locally — no DB container needed).
To start the Partner tunnel + Admin install flow:
madock bash
npx shopify app devThe Shopify CLI prompts for the Partner account + creates an ngrok-style tunnel. The local dev server itself runs on port 3000 inside the nodejs container.
Scaffolds a composer init project pinned to shopify/shopify-api:^6.0 (current stable on Packagist). No framework — just the SDK. Install runs composer install (or composer update if no lock yet). Use case: cron jobs / ETL scripts that sync Shopify orders with an existing PHP backend.
Bootstrap your scripts with:
use Shopify\Context;
Context::initialize(
apiKey: getenv('SHOPIFY_API_KEY'),
apiSecretKey: getenv('SHOPIFY_API_SECRET'),
scopes: ['read_products'],
hostName: 'loc.<project>.com',
sessionStorage: new FileSessionStorage(),
apiVersion: '2024-10',
);Scaffolds composer create-project laravel/laravel + adds kyon147/laravel-shopify. Install:
- rewrites
.env(APP_URL, DB_CONNECTION=mysql, DB_HOST=db, DB credentials from project config) - runs
composer install,composer require kyon147/laravel-shopify php artisan key:generate,migrate,vendor:publish --tag=shopify-config --tag=shopify-routes
Edit config/shopify-app.php (API key/secret/scopes), then visit /authenticate?shop=<your-store>.myshopify.com to wire OAuth.
| Service | hydrogen | app-remix | api-php | laravel-shopify |
|---|---|---|---|---|
| nodejs (Node 22) | ✓ | ✓ | — | — |
| php (PHP 8.3) | — | — | ✓ | ✓ |
| nginx | ✓ | ✓ | ✓ | ✓ |
| MariaDB | — | — | ✓ | ✓ |
| Redis | — | — | ✓ | ✓ |
| Node inside PHP | — | — | — | ✓ (asset pipeline) |
madock service:enable phpmyadmin / pgadmin / rabbitmq / grafana works on PHP-stack presets like for any other PHP platform.
The preset is stored as shopify/preset in config.xml. Change it and re-run madock rebuild to switch stacks (you'll likely want to start in a fresh directory — the scaffolded project layout differs significantly between presets).
madock shopify <command>— runs the Shopify CLI inside the container. Examples:- Hydrogen:
madock bashthennpx shopify hydrogen dev - Remix app:
madock bashthennpx shopify app dev
- Hydrogen:
madock composer <command>— Composer inside the PHP container (api-php / laravel-shopify only).madock install— re-run install. Hydrogen/Remix install is idempotent (npm install + patches are no-op on second run). Laravel install also re-runs migrations safely.madock start/madock stop/madock restart— standard.madock db:export/madock db:import— DB dumps (PHP-stack presets only).
Hydrogen wraps Vite via the Oxygen plugin and overrides the server config. madock attempts to inject server.allowedHosts: true into vite.config.ts, but if Oxygen's wrapper clobbers it, edit vite.config.ts manually:
export default defineConfig({
server: {
host: true,
allowedHosts: ['loc.<project>.com', '.test'],
},
plugins: [hydrogen(), oxygen(), reactRouter()],
// ...
});Restart with madock restart.
npx shopify app dev needs a Shopify Partner account. Sign in once at https://partners.shopify.com, then madock bash + npx shopify app dev to spin up the tunnel.
Kyon147/laravel-shopify ships its own routes; if php artisan vendor:publish --tag=shopify-routes didn't run, do it manually: madock bash + php artisan vendor:publish --tag=shopify-routes.
The default dev script in package.json binds to 127.0.0.1, so nginx can't reach it. madock appends --host to the script during install (shopify hydrogen dev --host is a boolean flag that switches to 0.0.0.0). If you regenerate the project from upstream, re-run madock install to re-apply the patch.
Older madock versions used the shopify/shopify-app-template-php Laravel template (with web/ + web/frontend/ subdirs) as the default. The madock shopify:web / madock shopify:web:frontend shortcuts still target those subdirectories — they're useful only if your project still follows that layout. For fresh projects, the new presets place files at the project root (no web/ subdir):
- If your existing project has
web/composer.json, your config.xml already hascomposer_dir=web+public_dir=web/publicset, and the env writer preserves them. - For fresh installs, defaults are
composer_dir=""+public_dir=public. Override in config.xml if you want the old layout.
madock bashenters the main service container as the project user (nodefor hydrogen/app-remix,www-datafor api-php/laravel-shopify).- For Hydrogen + Remix: don't run
npm installon the host (host Node may differ from container Node 22) — always insidemadock bash.