setup-weaverse-project

---
name: setup-weaverse-project
description: "Set up, create, scaffold, or clone a new Weaverse Hydrogen storefront locally from a Weaverse theme. Use CLI-first setup, boot a live demo-store preview before asking for Shopify credentials, then make it the merchant's own with env, GitHub, and Builder preview connection."
---

# Set Up a Weaverse Project — Agent Skill

> Take a user from **nothing** to a **running, connected** Weaverse Hydrogen storefront.
> This is the front door. Every other Weaverse skill assumes the project already exists — this one creates it.

## The One Rule That Fixes Onboarding

**Boot a live preview on the demo store BEFORE asking for any credentials.**

Most users quit onboarding because they hit a wall (GitHub, Shopify tokens, CLI) before they ever see anything work. Weaverse themes ship with working demo store tokens in `.env.example`, so you can show a real, running storefront in ~2 minutes with **zero** credentials. Do that first. Get the "wow." *Then* make it theirs.

Do not make the user create a GitHub repo, link a Shopify store, or paste tokens before they have seen the storefront running. If you do, you have failed the onboarding even if every command succeeds.

## You Drive the CLI — The User Never Types It

The user (merchant or developer) should never have to type a CLI command. **You** run `shopify hydrogen` and `@weaverse/cli` under the hood. The Shopify CLI does real work (env pull, dev server, codegen, deploy) — drive it, do not reimplement it. `npm run dev` itself shells out to `shopify hydrogen dev`, so the CLI is always involved; just keep it invisible to the user.

## Inputs You Need

Ask for as little as possible. Most setup values are generated or discovered.

Required from the setup prompt or user:

- `WEAVERSE_PROJECT_ID` — from Weaverse Builder
- Theme handle — default to `pilot` only when omitted
- Project folder name — default to `my-hydrogen-storefront`

Required later for the real store:

- `PUBLIC_STORE_DOMAIN`
- `PUBLIC_STOREFRONT_API_TOKEN`

Generated by you:

- `SESSION_SECRET` — never ask the user for this; generate a random value

Optional later:

- `PRIVATE_STOREFRONT_API_TOKEN`
- `SHOP_ID`
- customer account vars
- checkout domain
- analytics/reviews vars

---

## Phase 0 — Detect the Environment

Before doing anything, detect and record (do not assume):

```bash
node --version            # need >= 18
git --version
gh --version 2>/dev/null && gh auth status 2>/dev/null   # is GitHub CLI present AND authed?
npx shopify version 2>/dev/null                          # Shopify CLI availability
npx @weaverse/cli@latest create --help 2>/dev/null        # CLI availability + template choices
ls package-lock.json pnpm-lock.yaml yarn.lock 2>/dev/null # infer package manager
```

Branch all later steps off this. If `gh` is missing or not authed, use the manual repo fallback in Phase 5. If Node < 18, stop and tell the user to upgrade.

---

## Phase 1 — Scaffold the Theme with Weaverse CLI

Prefer the Weaverse CLI over `git clone`. It knows the supported templates, downloads the correct source, and writes the initial env file.

```bash
npx @weaverse/cli@latest create \
  --template=<theme-handle> \
  --project-id=<WEAVERSE_PROJECT_ID> \
  --project-name=<project-folder> \
  --no-install \
  -y

cd <project-folder>
git init
```

Rules:

- If the theme handle is missing, default to `pilot`.
- If the CLI rejects a theme (for example an old/nonexistent `blank` handle), show the supported template list and ask the user for the replacement. Do not silently switch themes.
- If `--no-install` is not supported by the installed CLI, let the CLI install dependencies, then continue from the created folder.
- Do not hand-roll a GitHub downloader. Use the CLI first; use clone/degit only if the CLI is unavailable and the theme repo exists.

---

## Phase 2 — THE WOW MOMENT (boot on the demo store)

This is the centerpiece. Get a live preview running with the demo Shopify credentials before asking for Shopify credentials.

First, make sure `.env` is complete **before** the server boots (dev servers read the environment at startup — fixing it later means a restart):

- The CLI-generated `.env` should already contain demo Shopify values plus the user's `WEAVERSE_PROJECT_ID`. If `.env` is missing, copy `.env.example` to `.env`, then set `WEAVERSE_PROJECT_ID` from the setup prompt.
- Never ask the user for `SESSION_SECRET`. If it is missing or still the demo placeholder (e.g. `foobar`), generate one and write it to `.env` now:

```bash
node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
```

Then boot:

```bash
npm install                   # or pnpm/yarn per lockfile
npm run dev                   # boots http://localhost:3456
```

Then **verify it actually came up** before saying anything succeeded:

```bash
curl -sf -o /dev/null -w "%{http_code}" http://localhost:3456   # expect 200
```

Tell the user, in plain language:
> "Your storefront is running locally at http://localhost:3456 — this is the Weaverse demo store. Next we'll make it *yours*."

Do not proceed to credentials until the preview is up and verified.

---

## Phase 3 — Make It Theirs (Shopify credentials)

Now swap the demo store for the user's store. The **minimum vars needed to render a Weaverse preview** are:

- `PUBLIC_STORE_DOMAIN` — `their-store.myshopify.com`
- `PUBLIC_STOREFRONT_API_TOKEN` — Storefront API access token
- `WEAVERSE_PROJECT_ID` — see Phase 4 (this is the only var that can't come from Shopify)

`SESSION_SECRET` is still required by Hydrogen, but it is agent-generated. Everything else (`SHOP_ID`, `PUBLIC_CUSTOMER_ACCOUNT_API_CLIENT_ID`, `PUBLIC_CHECKOUT_DOMAIN`, `PUBLIC_STOREFRONT_ID`, analytics, reviews) is **feature-complete extra** — set it *after* first success, never block on it.

### Decision tree: Shopify plan vs development store

Start by asking or inferring which path applies:

- **Store is on a Shopify plan / can use Oxygen later** → guide the user to install the **Hydrogen sales channel** (https://apps.shopify.com/hydrogen), then create one Hydrogen storefront project inside that channel.
- **Development store / not on a Shopify plan** → guide the user to install the **Headless sales channel** (https://apps.shopify.com/headless), then copy the Storefront API values manually.

### Path A — Hydrogen sales channel (preferred for plan stores)

After the user installs the Hydrogen sales channel and creates a Hydrogen storefront project, try the Shopify CLI first:

```bash
npx shopify hydrogen env pull   # works ONLY if the storefront is already linked
```

- **Linked** → `env pull` populates `.env`. Preserve the existing `WEAVERSE_PROJECT_ID` and generated `SESSION_SECRET` if the pull overwrites them.
- **Shop picker appears** → ask the user for the exact `.myshopify.com` domain to select. Do not guess from a list of shops.
- **Not linked / env pull unavailable** → have the user copy variables from **Shopify Admin → Hydrogen sales channel → Storefront Settings → Environments and variables**. You write the minimum render vars into `.env`.

### Path B — Headless sales channel (development/no-plan stores)

For development stores or stores without a Shopify plan, the Hydrogen sales channel may not be available. Guide the user to install the **Headless sales channel** (https://apps.shopify.com/headless), create/copy Storefront API credentials, and give you only the values you cannot generate:

- `PUBLIC_STORE_DOMAIN`
- `PUBLIC_STOREFRONT_API_TOKEN`
- optional: `PRIVATE_STOREFRONT_API_TOKEN`

You write them into `.env`. Re-run the Phase 2 verify after swapping.

Docs: https://weaverse.io/docs/intro/quickstart and https://shopify.dev/docs/storefronts/headless

---

## Phase 4 — Project Identity (`WEAVERSE_PROJECT_ID` + API key)

`WEAVERSE_PROJECT_ID` is the one value that lives only in Weaverse Builder and cannot be derived from Shopify.

**Path A — available today (default):**
The setup prompt generated by Weaverse Builder embeds the project's `WEAVERSE_PROJECT_ID` (and theme name). Read it from the prompt you were given and write it into `.env`. If you were not given one, ask the user to copy it from Builder → Project Settings.

**Path B — local auth handshake (milestone, may not be live yet):**
When available, you can run a local authentication handshake that returns the user's `WEAVERSE_PROJECT_ID`, `WEAVERSE_API_KEY`, and the ability to register a preview URL and use the Content API directly. If the handshake tooling is present, prefer it. If not, fall back to Path A. **Do not assume `WEAVERSE_API_KEY` exists** unless the handshake provided it. Once you have the key, you can also give the agent the Weaverse MCP (Phase 8).

---

## Phase 5 — Create the User's Repo and Push

**Default (if `gh` present and authed from Phase 0):**

```bash
git add -A
git commit -m "Initial commit: Weaverse Hydrogen storefront"
gh repo create <project-folder> --private --source=. --remote=origin --push
```

If the repo name already exists, inspect it before acting:

```bash
gh repo view <owner>/<project-folder> --json isEmpty,sshUrl,url
```

- **Empty repo** → add it as `origin` and push.
- **Not empty** → do not overwrite or force-push. Create a distinct repo name such as `<project-folder>-pilot` or `<project-folder>-weaverse`.

**Fallback (no `gh`):** give numbered manual steps —
1. Create a new empty repo at https://github.com/new (no README).
2. Then run (you fill in their URL):
   ```bash
   git add -A && git commit -m "Initial commit: Weaverse Hydrogen storefront"
   git remote add origin https://github.com/<user>/<repo>.git
   git branch -M main && git push -u origin main
   ```

Never present "agent does it" and "user does it" as the same step — pick the default from Phase 0 detection, state which path you're taking.

---

## Phase 6 — Connect the Preview to Weaverse Builder

- **Today:** guide the user — in Builder, click the URL in the preview address bar and choose **Manage previews** (or Builder → **Project Settings** → **Manage URLs**, Preview URLs section) → add `http://localhost:3456` → save.
- **Milestone (Path B auth):** when the handshake/API is live, register the preview URL automatically via the authenticated endpoint so the user never leaves the agent. Prefer this when available.

---

## Phase 7 — Verify (the success oracle)

**Do not claim setup success without these green checks:**

```bash
curl -sf -o /dev/null -w "%{http_code}" http://localhost:3456   # 200
npm run typecheck                                               # passes
```

Recommended full check before handoff or production prep:

```bash
npm run build
```

Plus confirm the Weaverse preview shows **connected** in Builder when the user can check it. If any required check fails, fix it before reporting done — and report exactly which check failed if you cannot.

---

## Phase 8 — (Optional) Give the agent the Weaverse MCP

Once the project has a `WEAVERSE_API_KEY` (the Phase 4 Path B handshake, or a Content API
key from Builder → Settings → API Keys), offer to add the **Weaverse MCP server** so the
agent can work with *this* project directly — search the Weaverse docs, read the
account's projects, pages (as Portable Text), theme settings, and locales, and edit
page content, theme settings, and project names.

- Ships as `npx -y @weaverse/mcp` over stdio. **Account tools need v2.2.0+**; docs search
  works with no key.
- Once `WEAVERSE_API_KEY` is set, the account tools can **read and write**: update page
  content (`update_page`), delete pages (`delete_pages`), merge theme settings
  (`update_theme_settings`), and rename projects (`update_project`). Writes go live on the
  storefront immediately — read current values first and send only the keys you change.
- Put `WEAVERSE_API_KEY` in the MCP client's `env` block — never in a tracked file.
- The config shape differs per client (Cursor, Claude Code, Codex, opencode, VS Code, pi, …);
  exact per-client snippets are in the docs:
  **https://weaverse.io/docs/developer-tools/weaverse-mcp**

This is a convenience for *future* work — not required to finish setup. Skip it if the user
isn't on an MCP-capable agent.

---

## Full Sequence (cheat sheet)

1. Detect env (node, gh+auth, shopify CLI, package manager).
2. Scaffold with `npx @weaverse/cli@latest create` (default `pilot`) → `git init`.
3. Generate `SESSION_SECRET` if needed.
4. **Boot on demo Shopify store** (install, `npm run dev`, verify 200). ← wow moment.
5. Swap to user's store (Shopify plan → Hydrogen sales channel + `env pull` or manual variables; development/no-plan → Headless sales channel + manual variables).
6. Create repo + push (`gh repo create` default, manual fallback).
7. Connect preview URL (manual paste today / auto-register later).
8. Verify required checks (200 + typecheck) and run build when preparing handoff/production.
9. *(Optional)* Wire up the Weaverse MCP for the user's agent (`npx -y @weaverse/mcp` + `WEAVERSE_API_KEY`) — see Phase 8.

## Required vars quick reference

| Var | Needed to render? | Source |
|-----|-------------------|--------|
| `SESSION_SECRET` | yes | agent-generated random string |
| `PUBLIC_STORE_DOMAIN` | yes | Shopify (Hydrogen or Headless sales channel) |
| `PUBLIC_STOREFRONT_API_TOKEN` | yes | Shopify (Hydrogen or Headless sales channel) |
| `WEAVERSE_PROJECT_ID` | yes | Weaverse Builder (prompt / handshake) |
| `SHOP_ID`, customer-account, checkout, storefront-id, analytics | no (feature-complete) | Shopify / later |