@akqa-denmark/shopify-theme-build 0.1.0

package/README.md

@@ -0,0 +1,258 @@
+# @akqa-denmark/shopify-theme-build
+
+Internal build pipeline for AKQA Denmark Shopify themes. Handles schema generation, locale merging, section group scaffolding, and Vite config for multi-store repositories.
+
+---
+
+## What it does
+
+Shopify themes require a specific set of JSON and Liquid files to be generated from TypeScript schema sources before a build or deploy. This package encapsulates that pipeline so it can be shared across projects without duplicating the build directory.
+
+Specifically, it:
+
+- Injects `{% schema %}` blocks into Liquid files for sections, blocks, and snippets
+- Generates and maintains `theme/config/settings_schema.json` from TS config schemas
+- Generates `theme/sections/{name}-group.json` files for section groups (preserving merchant-managed `sections` and `order` data)
+- Extracts translatable strings from all schema types and merges them into `theme/locales/en.default.schema.json`
+- Provides a Vite config factory (`createViteConfig`) that wires up vite-plugin-shopify, full-reload, tailwind, and a schema watcher plugin — all config-aware
+
+---
+
+## Requirements
+
+- Node >= 22.0.0
+- Vite >= 8.0.0
+
+---
+
+## Installation
+
+```bash
+npm install @akqa-denmark/shopify-theme-build
+```
+
+Peer dependencies (install as needed):
+
+```bash
+npm install --save-dev vite vite-plugin-shopify vite-plugin-full-reload
+npm install --save-dev @tailwindcss/vite  # optional
+```
+
+---
+
+## Setup
+
+### 1. Create `shopify-build.config.ts` at the repo root
+
+```typescript
+import { defineConfig } from '@akqa-denmark/shopify-theme-build';
+
+export default defineConfig({
+  stores: [
+    { slug: 'my-store', name: 'My Store' },
+    { slug: 'base', name: 'Base', foundation: true },
+  ],
+  defaultStore: 'my-store',
+});
+```
+
+`foundation: true` marks a store as non-deployable (excluded from `shopify-build manifest`).
+
+Full config options:
+
+```typescript
+interface BuildConfig {
+  stores: { slug: string; name: string; foundation?: boolean }[];
+  defaultStore: string;
+  storesDirectory?: string;  // default: 'stores'
+  sharedDirectory?: string;  // default: 'shared'
+  build?: {
+    parallel?: boolean;      // default: true
+  };
+  vite?: {
+    port?: number;           // default: 3000
+    bundledDev?: boolean;    // default: false
+  };
+}
+```
+
+### 2. Update `vite.config.ts`
+
+```typescript
+import { createViteConfig } from '@akqa-denmark/shopify-theme-build/vite';
+
+export default createViteConfig();
+```
+
+Pass overrides to merge with the base config:
+
+```typescript
+export default createViteConfig({
+  resolve: {
+    alias: [
+      { find: '@', replacement: new URL('./stores/my-store/src', import.meta.url).pathname },
+      { find: /^@shared\/(.*)/, replacement: new URL('./shared/$1', import.meta.url).pathname },
+    ],
+  },
+});
+```
+
+### 3. Update `package.json` scripts
+
+```json
+{
+  "scripts": {
+    "build:prepare": "shopify-build prepare",
+    "build:full": "shopify-build prepare && vite build"
+  }
+}
+```
+
+To target a specific store, use `--store` or set `CURRENT_STORE`:
+
+```bash
+shopify-build prepare --store my-store
+CURRENT_STORE=my-store shopify-build prepare
+```
+
+---
+
+## Directory conventions
+
+The pipeline expects this structure inside each store directory:
+
+```
+stores/{slug}/
+├── src/
+│   └── schemas/
+│       ├── settings/     → locale data only
+│       ├── configs/      → settings_schema.json entries
+│       ├── sections/     → theme/sections/{name}.liquid schema injection
+│       ├── blocks/       → theme/blocks/{name}.liquid schema injection
+│       ├── section-blocks/ → theme/snippets/{name}.liquid schema injection
+│       └── section-groups/ → theme/sections/{name}-group.json
+└── theme/
+    ├── config/
+    │   └── settings_schema.json  (generated)
+    ├── locales/
+    │   └── en.default.schema.json  (generated)
+    ├── sections/
+    ├── blocks/
+    └── snippets/
+```
+
+---
+
+## CLI
+
+### `shopify-build prepare`
+
+Runs the full schema pipeline for a store.
+
+```bash
+shopify-build prepare
+shopify-build prepare --store georg-jensen
+shopify-build prepare --skip-schemas
+shopify-build prepare --skip-locales
+```
+
+### `shopify-build manifest`
+
+Outputs a JSON manifest of all deployable stores to stdout. Useful for CI matrix generation.
+
+```bash
+shopify-build manifest
+# {
+#   "stores": [
+#     { "slug": "my-store", "name": "My Store", "deployable": true },
+#     { "slug": "base", "name": "Base", "deployable": false }
+#   ]
+# }
+```
+
+---
+
+## API
+
+```typescript
+import { defineConfig, resolveConfig, resolveStore, getStorePaths, orchestrate } from '@akqa-denmark/shopify-theme-build';
+import { createViteConfig } from '@akqa-denmark/shopify-theme-build/vite';
+```
+
+| Export | Description |
+|---|---|
+| `defineConfig(config)` | Type-safe config helper |
+| `resolveConfig(cwd?)` | Loads and validates `shopify-build.config.ts` |
+| `resolveStore(config, explicit?)` | Resolves store from arg, `CURRENT_STORE` env, or `defaultStore` |
+| `getStorePaths(config, store)` | Returns resolved path object for a store |
+| `orchestrate(options)` | Runs the full pipeline programmatically |
+| `createViteConfig(overrides?)` | Returns a Vite `UserConfig` |
+
+---
+
+## Schema file conventions
+
+### Sections and blocks
+
+Export a default object or a function returning an object:
+
+```typescript
+// stores/my-store/src/schemas/sections/hero.ts
+export default {
+  name: 'Hero',
+  settings: [
+    { type: 'text', id: 'heading', label: 'Heading', defaultLabel: 'Heading' },
+  ],
+};
+```
+
+### Configs
+
+Export a named function in the form `{PascalName}Config`:
+
+```typescript
+// stores/my-store/src/schemas/configs/brand.ts
+export function BrandConfig() {
+  return {
+    name: 'Brand',
+    settings: [
+      { type: 'color', id: 'primary_color', label: 'Primary colour' },
+    ],
+  };
+}
+```
+
+`theme-info.ts` is handled separately — the pipeline injects `theme_version` from git tags and `theme_name` from the store's `name` in config.
+
+### Section groups
+
+Export a default object with `type` and `name`. The `sections` and `order` fields are managed by the Shopify theme editor and are preserved from any existing file.
+
+```typescript
+// stores/my-store/src/schemas/section-groups/header.ts
+export default {
+  type: 'header',
+  name: 'Header group',
+};
+```
+
+---
+
+## Version resolution
+
+`theme_version` in `settings_schema.json` is resolved at build time:
+
+1. `RELEASE_TAG` env var (CI deploy — e.g. `v1.18.0` → `1.18.0`)
+2. CI without `RELEASE_TAG` → latest git tag, no suffix
+3. Local dev → latest git tag + `-dev` suffix (e.g. `1.18.0-dev`)
+4. Fallback: `dev`
+
+---
+
+## Development
+
+```bash
+npm run build       # compile to dist/
+npm run dev         # watch mode
+npm run type-check  # tsc --noEmit
+```

package/bin/shopify-build.js

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+import('../dist/cli.js').catch((err) => {
+  console.error('Build output not found. Run `npm run build` first.\n', err.message);
+  process.exit(1);
+});

package/dist/chunk-IHCJ6PUT.js

@@ -0,0 +1,81 @@
+#!/usr/bin/env node
+
+// src/config/resolve.ts
+import { existsSync } from "fs";
+import { resolve, join } from "path";
+var CONFIG_FILE_NAMES = [
+  "shopify-build.config.ts",
+  "shopify-build.config.js",
+  "shopify-build.config.mjs"
+];
+async function resolveConfig(cwd) {
+  const rootDir = cwd || process.cwd();
+  const configPath = findConfigFile(rootDir);
+  if (!configPath) {
+    throw new Error(
+      `No config file found. Create one of: ${CONFIG_FILE_NAMES.join(", ")}`
+    );
+  }
+  const { createJiti } = await import("jiti");
+  const jiti = createJiti(rootDir);
+  const rawModule = await jiti.import(configPath);
+  const raw = rawModule.default || rawModule;
+  if (!raw.stores || raw.stores.length === 0) {
+    throw new Error("Config must define at least one store");
+  }
+  if (!raw.defaultStore) {
+    throw new Error("Config must define a defaultStore");
+  }
+  const defaultExists = raw.stores.some((s) => s.slug === raw.defaultStore);
+  if (!defaultExists) {
+    throw new Error(
+      `defaultStore "${raw.defaultStore}" not found in stores array`
+    );
+  }
+  return {
+    stores: raw.stores,
+    defaultStore: raw.defaultStore,
+    storesDirectory: raw.storesDirectory || "stores",
+    sharedDirectory: raw.sharedDirectory || "shared",
+    rootDir,
+    build: {
+      parallel: raw.build?.parallel ?? true
+    },
+    vite: {
+      port: raw.vite?.port ?? 3e3,
+      bundledDev: raw.vite?.bundledDev ?? false
+    }
+  };
+}
+function findConfigFile(rootDir) {
+  for (const name of CONFIG_FILE_NAMES) {
+    const fullPath = resolve(rootDir, name);
+    if (existsSync(fullPath)) return fullPath;
+  }
+  return null;
+}
+function resolveStore(config, explicit) {
+  const store = explicit || process.env.CURRENT_STORE || config.defaultStore;
+  const exists = config.stores.some((s) => s.slug === store);
+  if (!exists) {
+    const valid = config.stores.map((s) => s.slug).join(", ");
+    throw new Error(`Store "${store}" not found. Valid: ${valid}`);
+  }
+  return store;
+}
+function getStorePaths(config, store) {
+  const storeDir = join(config.rootDir, config.storesDirectory, store);
+  const themeDir = join(storeDir, "theme");
+  const srcDir = join(storeDir, "src");
+  const schemasDir = join(srcDir, "schemas");
+  const entrypointsDir = join(srcDir, "assets/scripts/entrypoints");
+  const localesDir = join(themeDir, "locales");
+  const configDir = join(themeDir, "config");
+  return { storeDir, themeDir, srcDir, schemasDir, entrypointsDir, localesDir, configDir };
+}
+
+export {
+  resolveConfig,
+  resolveStore,
+  getStorePaths
+};