From cb23142b38d14f22b319b58fa2609047552fc07a Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Fri, 13 Feb 2026 04:04:58 +0000
Subject: [PATCH 1/3] Initial plan


From b81d07fcd45f387dfae9699c168ebf018b0ee74e Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Fri, 13 Feb 2026 04:08:09 +0000
Subject: [PATCH 2/3] Add comprehensive .github/copilot-instructions.md file

Co-authored-by: james0r <34731936+james0r@users.noreply.github.com>
---
 .github/copilot-instructions.md | 391 ++++++++++++++++++++++++++++++++
 1 file changed, 391 insertions(+)
 create mode 100644 .github/copilot-instructions.md

diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md
new file mode 100644
index 0000000..848e476
--- /dev/null
+++ b/.github/copilot-instructions.md
@@ -0,0 +1,391 @@
+# Slayed Shopify Starter Theme - Copilot Instructions
+
+## Project Overview
+
+This is a modern Shopify theme starter built with:
+- **Vite** (v5.4.21) for build tooling and development server
+- **Tailwind CSS v4** for styling
+- **Alpine.js v3** for lightweight JavaScript interactivity
+- **TypeScript** for type-safe JavaScript (used in Prodify)
+- **Liquid Ajax Cart v2** for AJAX cart functionality
+- **Shopify CLI** for theme development and deployment
+
+## Repository Structure
+
+```
+/home/runner/work/slayed/slayed/
+├── .github/
+│   └── workflows/          # CI/CD workflows (theme-check, deploy)
+├── assets/                 # Built assets (auto-generated, gitignored)
+├── config/                 # Shopify theme config files
+├── layout/                 # Shopify theme layouts (theme.liquid)
+├── locales/                # Translation files
+├── public/                 # Static assets (copied to assets/ during build)
+├── sections/               # Shopify theme sections
+├── snippets/               # Shopify theme snippets (including vite-tag.liquid)
+├── src/                    # Source files (built by Vite)
+│   ├── css/               # CSS files (base, components, utilities, global)
+│   ├── entrypoints/       # Vite entry points (theme.js, theme.css)
+│   ├── fonts/             # Font files
+│   ├── images/            # Image assets
+│   └── js/
+│       ├── alpine/        # Alpine.js components, stores, directives, magic
+│       ├── prodify/       # TypeScript product variant picker logic
+│       ├── dynamicScript.js
+│       └── helpers.js
+├── templates/              # Shopify theme templates
+├── package.json
+├── vite.config.js
+├── tsconfig.json
+└── README.md
+```
+
+## Key Files and Their Purpose
+
+### Configuration Files
+
+- **vite.config.js** - Vite configuration with Shopify plugin, Tailwind, SSL, CORS settings
+- **tsconfig.json** - TypeScript configuration with path aliases (`@/*` → `src/*`)
+- **package.json** - Dependencies and npm scripts for development, building, and deployment
+- **.theme-check.yml** - Shopify theme linting configuration
+- **.shopifyignore** - Files to ignore during Shopify theme push
+- **.gitignore** - Git ignore patterns (notably: `/assets`, `/snippets/vite.liquid`, `node_modules/`)
+- **shopify.theme.toml** - Shopify CLI environment configuration (NOT committed, create locally)
+
+### Source Code Structure
+
+- **src/entrypoints/theme.js** - Main JavaScript entry point
+  - Imports Liquid Ajax Cart
+  - Registers Alpine.js and its plugins (Collapse, Focus, Morph)
+  - Auto-registers Alpine components from `src/js/alpine/`
+  - Exposes helpers on `window.slayedNamespace`
+  
+- **src/entrypoints/theme.css** - Main CSS entry point
+  - Imports Tailwind CSS v4
+  - Imports custom CSS layers (base, components, utilities, global)
+  - Defines custom theme colors and fonts
+  - Includes custom variants (scrolled, mobile-menu-visible)
+
+- **src/js/alpine/index.js** - Auto-registration system for Alpine.js
+  - Uses Vite's `import.meta.glob()` to auto-import components and stores
+  - Components are in `src/js/alpine/components/*.js`
+  - Stores are in `src/js/alpine/stores/*.js`
+  - Each module exports `{ name, component/store }`
+
+- **src/js/prodify/** - TypeScript variant picker system (Shopify Dawn-inspired)
+  - Custom element logic for handling product variant selection
+  - Used in PDP (Product Detail Page)
+  - Entry point: `index.ts`
+
+### Shopify Theme Files
+
+- **layout/theme.liquid** - Main theme layout
+  - Includes vite-tag snippets for CSS and JS
+  - Renders `vite-tag` for: `theme.css`, `theme.js`, `@/js/prodify/index.ts`
+
+- **snippets/vite-tag.liquid** - Auto-generated by vite-plugin-shopify
+  - Maps source entry points to built asset files
+  - **DO NOT EDIT** - Regenerated on each build
+
+- **sections/** - Shopify theme sections (header, footer, product, cart, etc.)
+- **snippets/** - Reusable Shopify snippets
+- **templates/** - Shopify page templates
+
+## Build Process
+
+### Development
+
+```bash
+npm run dev
+```
+
+This command runs two processes in parallel:
+1. **Vite dev server** (`npm run vite:watch`) - Runs on https://127.0.0.1:3000 with HMR
+2. **Shopify CLI** (`npm run shopify:dev`) - Runs dev server on http://127.0.0.1:9292
+
+**Important Development Notes:**
+- Vite uses **@vitejs/plugin-basic-ssl** for HTTPS with a self-signed certificate
+- If assets don't load due to SSL errors:
+  1. Visit https://127.0.0.1:3000
+  2. Click "Advanced" and proceed past the warning
+  3. Return to http://127.0.0.1:9292
+- CORS is configured for `slayed-starter.myshopify.com` and local origins
+- The Shopify preview bar is hidden in development mode via JavaScript in `theme.js`
+
+### Building
+
+```bash
+npm run build
+```
+
+This runs `vite build` in production mode:
+- Transpiles TypeScript and JavaScript
+- Bundles and minifies assets with content hashing
+- Processes Tailwind CSS
+- Copies files from `public/` to `assets/`
+- Generates `snippets/vite-tag.liquid` with asset mappings
+- Outputs to `assets/` directory
+
+**Expected Build Output:**
+```
+assets/
+├── .vite/manifest.json
+├── theme.[hash].min.css
+├── theme.[hash].min.js
+├── index.[hash].min.js  (Prodify)
+└── [static files from public/]
+```
+
+### Deployment
+
+- **`npm run deploy`** - Interactive deploy to production environment
+- **`npm run deploy:dev`** - Deploy to development environment (uses shopify.theme.toml)
+- **`npm run deploy:staging`** - Deploy to staging environment (uses shopify.theme.toml)
+- **`npm run deploy:new`** - Create new unpublished theme
+
+**Deployment requires:**
+1. Shopify CLI installed globally or via npm
+2. `shopify.theme.toml` file in root (see README.md for format)
+3. Authenticated Shopify CLI session
+
+## Known Issues and Workarounds
+
+### 1. Build Warning: Missing Assets Folder
+
+**Issue:**
+```
+WARNING: No assets folder located at /home/runner/work/slayed/slayed/assets. No clean attempted.
+```
+
+**Explanation:** This is expected on first build. The `assets/` folder is auto-generated by Vite and is gitignored. The warning can be safely ignored.
+
+**Workaround:** Create the assets folder before building:
+```bash
+mkdir -p assets
+npm run build
+```
+
+### 2. NPM Security Vulnerabilities
+
+**Issue:** Running `npm audit` shows 6 moderate severity vulnerabilities:
+- `esbuild` ≤0.24.2 (development server vulnerability)
+- `lodash` 4.0.0 - 4.17.21 (Prototype Pollution)
+
+**Explanation:** These are dependencies of Vite and Shopify CLI tools:
+- The esbuild vulnerability only affects development servers
+- The lodash vulnerability is in the Shopify CLI package
+- Running `npm audit fix --force` would install breaking changes (Vite v7, vite-plugin-shopify v3)
+
+**Workaround:** 
+- Accept these vulnerabilities in development
+- They do not affect production builds
+- Only proceed with fixes if willing to handle breaking changes
+
+### 3. Duplicate Helper Functions
+
+**Issue:** The `src/js/helpers.js` file contains duplicate `debounce` function definitions (lines 26-32 and 70-76).
+
+**Explanation:** This appears to be a copy-paste error and doesn't cause runtime issues since only the last definition is used.
+
+**Workaround:** Can be safely ignored, or remove the duplicate definitions if modifying the file.
+
+### 4. Shopify CLI Not Included in Dependencies
+
+**Issue:** `shopify` command is not available by default after `npm ci/install`.
+
+**Explanation:** The Shopify CLI must be installed globally or the npm scripts use `@shopify/cli` which is a devDependency.
+
+**Workaround:** 
+```bash
+npm install -g @shopify/cli@latest
+```
+Or use the npm scripts which reference the local `@shopify/cli` package.
+
+### 5. SSL/CORS Issues in Development
+
+**Issue:** Assets may not load in Shopify dev server due to SSL or CORS errors.
+
+**Explanation:** Vite uses a self-signed SSL certificate that browsers don't trust by default.
+
+**Workaround:** See Development section above for SSL certificate acceptance steps.
+
+## Common Development Tasks
+
+### Adding a New Alpine.js Component
+
+1. Create a file in `src/js/alpine/components/yourComponent.js`
+2. Export with this structure:
+```javascript
+export default {
+  name: 'yourComponent',
+  component: (params) => ({
+    // Alpine.js component definition
+  })
+}
+```
+3. The component will be auto-registered and available as `x-data="yourComponent"`
+
+### Adding a New Alpine.js Store
+
+1. Create a file in `src/js/alpine/stores/yourStore.js`
+2. Export with this structure:
+```javascript
+export default {
+  name: 'yourStore',
+  store: () => ({
+    // Store properties and methods
+  })
+}
+```
+3. The store will be auto-registered and available as `$store.yourStore`
+
+### Adding Static Assets
+
+Place files in `public/` directory:
+- Files are copied to `assets/` during build
+- Reference in Liquid as: `{{ 'filename.ext' | asset_url }}`
+- No need to import in JavaScript
+
+### Working with Liquid Files
+
+- Liquid files are in: `sections/`, `snippets/`, `templates/`, `layout/`
+- Edit these directly (not compiled by Vite)
+- Shopify CLI watches for changes and hot-reloads
+- Use `{% render 'vite-tag', entry: 'theme.js' %}` to reference Vite-built assets
+
+### Running Theme Check (Linter)
+
+Theme Check is configured in `.theme-check.yml` and runs:
+- Automatically in GitHub Actions on PRs to main
+- Can be run locally with Shopify CLI:
+```bash
+shopify theme check
+```
+
+## Testing
+
+**Note:** This project does not have a test suite. All testing is manual:
+1. Run `npm run build` to ensure build succeeds
+2. Use `npm run dev` to test in Shopify development environment
+3. Manually verify functionality in browser
+
+## Path Aliases
+
+TypeScript/JavaScript path aliases are configured in `tsconfig.json` and `vite.config.js`:
+- `@/*` maps to `src/*`
+- `~/*` maps to `src/*`
+
+Example usage:
+```javascript
+import helpers from '@/js/helpers.js'
+```
+
+## Environment Variables
+
+- **NODE_ENV** - Set by npm scripts (`development` or `production`)
+- Process.env.NODE_ENV is available in JavaScript via Vite
+
+## Vite Plugins Used
+
+1. **tailwindcss()** - Tailwind CSS v4 integration
+2. **basicSsl()** - Self-signed SSL certificate for HTTPS dev server
+3. **cleanup()** - Cleans old assets from assets/ folder
+4. **copyPublicToAssetsPlugin()** - Custom plugin to watch and copy public/ files during dev
+5. **shopify()** - Shopify Vite plugin for theme integration
+6. **pageReload()** - Watches `/tmp/theme.update` for Shopify CLI notifications
+7. **vite-plugin-liquid-tailwind-refresh** - Custom HMR handling for Liquid files
+
+## GitHub Actions Workflows
+
+### theme-check.yml
+- Runs on PRs to main branch
+- Runs Shopify Theme Check linter
+- Skips draft PRs
+
+### deploy-main.yml
+- Runs on push to main branch
+- Builds theme with Vite
+- Deploys to Shopify using secrets:
+  - `SHOPIFY_THEME_ID`
+  - `SHOPIFY_STORE_URL`
+  - `SHOPIFY_API_PASSWORD`
+
+## Best Practices for Code Changes
+
+1. **Don't edit `snippets/vite-tag.liquid`** - It's auto-generated
+2. **Don't commit `assets/` folder** - It's gitignored and built on deploy
+3. **Don't commit `shopify.theme.toml`** - It's gitignored (personal config)
+4. **Use path aliases** - Import with `@/` instead of relative paths
+5. **Follow Alpine.js conventions** - Use the auto-registration pattern
+6. **Test builds before committing** - Run `npm run build` to catch errors
+7. **Keep CSS modular** - Use base.css, components.css, utilities.css layers
+8. **Use Tailwind utility classes** - Custom CSS should be minimal
+
+## Dependencies Version Notes
+
+- **Tailwind CSS v4** - Latest major version (different API than v3)
+- **Alpine.js v3** - With plugins: Collapse, Focus, Morph
+- **Liquid Ajax Cart v2** - Has different API than v1 (see docs)
+- **Vite v5** - Latest stable version
+- **vite-plugin-shopify v4** - For Shopify theme integration
+
+## Debugging Tips
+
+### Build Issues
+```bash
+# Clean and rebuild
+rm -rf assets/ node_modules/
+npm ci
+npm run build
+```
+
+### Dev Server Issues
+```bash
+# Check if ports are available
+lsof -ti:3000  # Vite
+lsof -ti:9292  # Shopify CLI
+
+# Kill processes on ports if needed
+kill -9 $(lsof -ti:3000)
+kill -9 $(lsof -ti:9292)
+```
+
+### Asset Loading Issues
+1. Check `snippets/vite-tag.liquid` has correct asset hashes
+2. Verify `assets/` folder contains built files
+3. Check browser console for 404 or CORS errors
+4. Ensure SSL certificate is accepted (see Development section)
+
+### Alpine.js Issues
+- Check browser console for Alpine errors
+- Verify component/store exports follow the correct structure
+- Ensure Alpine.start() is called (it's in theme.js)
+
+## Additional Resources
+
+- [Shopify Theme Development](https://shopify.dev/docs/themes)
+- [Shopify CLI Commands](https://shopify.dev/docs/themes/tools/cli/commands)
+- [Vite Documentation](https://vitejs.dev/)
+- [Shopify Vite Plugin](https://github.com/barrel/shopify-vite)
+- [Alpine.js Documentation](https://alpinejs.dev/)
+- [Tailwind CSS v4](https://tailwindcss.com/)
+- [Liquid Ajax Cart v2](https://liquid-ajax-cart.js.org/v2/)
+
+## Quick Start for New Contributors
+
+1. Clone repository
+2. Run `npm ci` to install dependencies
+3. Create `shopify.theme.toml` in root (see README.md)
+4. Authenticate with Shopify CLI: `shopify auth login`
+5. Run `npm run dev` to start development
+6. Build with `npm run build` before deploying
+
+## Notes for Coding Agents
+
+- This is a Shopify theme, not a standalone web application
+- Liquid template changes don't require rebuilds
+- JavaScript/CSS changes require Vite rebuild
+- The theme structure follows Shopify conventions
+- Test all changes with `npm run build` before finalizing
+- Be cautious with dependency updates (may cause breaking changes)
+- The build process is fast (~700ms), so rebuild frequently during development

From e5288f3359fcf69844acf8f73a376a7613986a9f Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Fri, 13 Feb 2026 04:09:02 +0000
Subject: [PATCH 3/3] Update copilot-instructions.md with MCP and jsconfig
 details

Co-authored-by: james0r <34731936+james0r@users.noreply.github.com>
---
 .github/copilot-instructions.md | 25 ++++++++++++++++++++++---
 1 file changed, 22 insertions(+), 3 deletions(-)

diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md
index 848e476..e76f70e 100644
--- a/.github/copilot-instructions.md
+++ b/.github/copilot-instructions.md
@@ -46,10 +46,12 @@ This is a modern Shopify theme starter built with:
 
 - **vite.config.js** - Vite configuration with Shopify plugin, Tailwind, SSL, CORS settings
 - **tsconfig.json** - TypeScript configuration with path aliases (`@/*` → `src/*`)
+- **jsconfig.json** - JavaScript configuration with path aliases (mirrors tsconfig.json)
 - **package.json** - Dependencies and npm scripts for development, building, and deployment
-- **.theme-check.yml** - Shopify theme linting configuration
-- **.shopifyignore** - Files to ignore during Shopify theme push
+- **.theme-check.yml** - Shopify theme linting configuration (most checks disabled)
+- **.shopifyignore** - Files to ignore during Shopify theme push (config files, node_modules, etc.)
 - **.gitignore** - Git ignore patterns (notably: `/assets`, `/snippets/vite.liquid`, `node_modules/`)
+- **.mcp.json** - MCP server configuration for Shopify dev tools
 - **shopify.theme.toml** - Shopify CLI environment configuration (NOT committed, create locally)
 
 ### Source Code Structure
@@ -271,7 +273,7 @@ shopify theme check
 
 ## Path Aliases
 
-TypeScript/JavaScript path aliases are configured in `tsconfig.json` and `vite.config.js`:
+TypeScript/JavaScript path aliases are configured in `tsconfig.json`, `jsconfig.json`, and `vite.config.js`:
 - `@/*` maps to `src/*`
 - `~/*` maps to `src/*`
 
@@ -280,6 +282,23 @@ Example usage:
 import helpers from '@/js/helpers.js'
 ```
 
+## MCP (Model Context Protocol) Configuration
+
+The `.mcp.json` file configures the Shopify Dev MCP server:
+```json
+{
+  "mcpServers": {
+    "shopify-dev-mcp": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "@shopify/dev-mcp@latest"]
+    }
+  }
+}
+```
+
+This enables MCP-compatible AI tools to interact with Shopify development tools programmatically.
+
 ## Environment Variables
 
 - **NODE_ENV** - Set by npm scripts (`development` or `production`)