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):

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.

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:

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

Then boot:

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

Then verify it actually came up before saying anything succeeded:

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:

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):

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:

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):

   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 — 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:

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

Recommended full check before handoff or production prep:

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