Claude Code + Shopify: Zero to Hero

# CLAUDE.md — Shopify Theme Project

Starter instructions for Claude Code working on a Shopify theme.
Drop this file at the root of your theme repo. Claude Code will load it automatically.

## Stack

- Claude Code as the primary agent (terminal)
- Shopify AI Toolkit plugin: `/plugin marketplace add Shopify/shopify-ai-toolkit` then `/plugin install shopify-plugin@shopify-ai-toolkit`
- Shopify CLI for theme deploys
- Liquid, JSON templates, scoped `{% stylesheet %}` blocks

## Environment

Credentials live in `.env` (gitignored). Variables:

- `SHOPIFY_STORE` = `yourstore.myshopify.com`
- `SHOPIFY_ADMIN_API_TOKEN` = Admin API access token (starts with `shpat_`)

Never paste the token inline. Always source the env file:

```bash
set -a && source .env && set +a
```

If you are recording your screen, anything that appears in terminal output is public. Use variable interpolation, not literal values.

## Deploy

Push individual files to a specific theme. Always scope with `--only` and always pass `--nodelete` so Shopify CLI does not run a cleanup pass on unrelated remote files:

```bash
set -a && source .env && set +a && shopify theme push \
  --store="$SHOPIFY_STORE" \
  --password="$SHOPIFY_ADMIN_API_TOKEN" \
  --theme=<theme-id> \
  --only=sections/<file>.liquid \
  --only=templates/<file>.json \
  --nodelete
```

For the live theme, add `--allow-live`.

## JSON templates

Shopify auto-generates a `/* ... */` banner at the top of JSON template files. Do not remove it. Shopify CLI and the theme editor accept these files as-is. Standard `json.loads()` fails on them — strip the first comment if you need to validate locally.

## Section + block settings

Reference uploaded images using the `shopify://shop_images/<filename>` scheme, not the CDN URL. The filename is whatever you uploaded to Shopify Files.

## Uploading images to Shopify Files (GraphQL, 3 steps)

1. `stagedUploadsCreate` mutation returns a signed Google Cloud Storage target with form parameters.
2. `POST` the bytes to that URL as multipart form data, including every parameter Shopify returned plus `file=@localpath`. Expect HTTP 201.
3. `fileCreate` mutation with `originalSource` set to the staged `resourceUrl` registers the file. Poll `node(id)` until `fileStatus` becomes `READY`.

## Theme check

```bash
shopify theme check --path . --fail-level error
```

If your repo has pre-existing errors you cannot fix, grep the output for the file you just touched to confirm you did not introduce new offenses:

```bash
shopify theme check --path . --fail-level error 2>&1 | grep -A 3 "<your-file>"
```

## Color schemes

Defined in `config/settings_schema.json` and `config/settings_data.json`. Reference them as `scheme-1`, `scheme-2`, etc. in section settings. Use scoped `{% stylesheet %}` blocks in sections and rely on the theme color-scheme classes rather than hardcoding colors.

## Section schema convention

```json
{
  "name": "Your Section",
  "tag": "section",
  "class": "section-your-kebab",
  "settings": [ ... ],
  "presets": [{ "name": "Your Section" }]
}
```

Presets make the section available in the theme editor's "Add section" menu.

## Security rules

- Never commit `.env`, `.env.*`, or any file with tokens
- Never inline credentials in bash commands or commits
- Never paste API keys into curl commands or environment update commands
- If a credential appears in your command, stop and find an alternative approach

## Pre-push scan

Run this before every push:

```bash
git log --all -p | grep -iE "(password|secret|token|shpat_|shpss_|sk-)"
```

Anything found: stop, rotate the credential, clean history, then push.

## Writing style for code comments

- Concise, why-not-what
- No decorative comment blocks
- Do not explain what well-named code already says