Setup Weaverse Project

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 Only Clicks Browser Flows

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.

The human's job is limited to: approving browser flows, selecting the store in the shop picker, copying credentials, and supplying secrets. Never make them paste commands.

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 6. 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.

One path: install the Hydrogen app and link the storefront

Hydrogen works on Shopify development stores. There is no Headless-app fallback: local linking and credential setup go through the Hydrogen app regardless of plan.

1. Have the user install the Hydrogen app: https://apps.shopify.com/hydrogen. They may need to pick the store, approve the install, and create a Hydrogen storefront project in the app.
2. Link the storefront (you run this):

   npx shopify hydrogen link
   

   If a shop picker appears, ask the user for the exact .myshopify.com domain to select — do not guess from a list of shops.
3. Pull the environment (you run this):

   npx shopify hydrogen env pull
   

   This populates .env with the store's real variables. Preserve WEAVERSE_PROJECT_ID and the generated SESSION_SECRET if the pull overwrites them.
4. Verify before swapping — never replace demo credentials with unverified ones. Check that .env now contains real values, not placeholders:

   grep -E "^(PUBLIC_STORE_DOMAIN|PUBLIC_STOREFRONT_API_TOKEN)=" .env
   

   PUBLIC_STORE_DOMAIN must be the store's actual <store>.myshopify.com domain and PUBLIC_STOREFRONT_API_TOKEN a non-empty Storefront API token. Only then swap (the pull already did); re-run the Phase 2 verify:

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

Real limitation, stated once: public Oxygen / shareable production environments still depend on the store's Shopify plan. Local linking and credential setup do not — they work on development stores through the Hydrogen app. Environment docs: https://shopify.dev/docs/storefronts/headless/hydrogen/environments Getting started: https://shopify.dev/docs/storefronts/headless/hydrogen/getting-started

If env pull is unavailable or fails, have the user copy variables from Shopify Admin → Hydrogen app → Storefront settings → Environments and variables; you write the minimum render vars into .env and verify as above.

Phase 4 — Project Identity (WEAVERSE_PROJECT_ID)

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

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 Weaverse Studio → Project Settings.

Phase 5 — Weaverse API token + MCP (chat-driven live editing)

The Weaverse MCP lets the agent read and edit this project (and other projects on the same shop) directly from chat — including live page/content writes through the mounted Content API.

1. Create the token (human action). The user creates a Weaverse API token in Weaverse Studio → Dashboard → Account/Settings → API Keys (https://studio.weaverse.io). Copy it into your environment as WEAVERSE_API_KEY — never into a tracked file, never into the prompt.
2. Configure the MCP server. Add @weaverse/mcp@latest to the agent's MCP config with the bearer env var exactly:

   WEAVERSE_API_KEY=<token>
   

   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
3. Verify reads. Use the real read tools: list_projects, get_project, list_pages, get_page, get_theme_settings, list_languages, get_openapi_spec. There is no whoami tool.
4. Live writes are default-off — turn them on only with consent. All six write tools require the env var exactly:

   WEAVERSE_ENABLE_LIVE_WRITES=true
   

   With it: update_project, create_page, delete_pages, update_page, assign_template_resources, update_theme_settings. Before enabling, disclose in plain language: with live writes enabled, these tools change live storefront content — update_page edits real page items, create_page/delete_pages create/delete real pages, assign_template_resources adds Shopify resources to ONE existing shared template page (it never repoints an assignment away from another page; if any handle already belongs to a different live page the whole batch is rejected with 409 and nothing is written), update_theme_settings changes theme settings, update_project renames the project. Writes go live immediately through the same cache-invalidation path as a Studio save — there is no separate publish step. After any write, read back the affected resource to confirm.

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

Phase 6 — Create the User's Repo and Push (ask first)

Pushing creates a repository under the user's GitHub account and publishes their code — an external effect they must approve. Never block local setup on it: if approval doesn't come, the storefront is already working locally and setup can still be reported complete.

Always ask before any gh repo create, git commit, or git push — including when gh is already authenticated. Detected gh state only decides how to execute after approval; it is never itself the approval. Ask for and echo back:

• the exact repository name (default <project-folder>),
• the visibility (private unless the user says otherwise),
• confirmation to make the first push.

After approval, if gh is present and authed (Phase 0):

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

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

gh repo view <owner>/<approved-name> --json isEmpty,sshUrl,url

• Empty repo → add it as origin and push.
• Not empty → do not overwrite or force-push. Propose a distinct name such as <project-folder>-pilot or <project-folder>-weaverse and get approval for that name before continuing.

After approval, if gh is missing / not authed: give the user a clickable path and ask them to enable the push:

1. Authenticate the GitHub CLI (https://github.com/login) or 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
   

If the user declines or doesn't answer: say so plainly, leave the work committed only locally (or uncommitted), and continue. Do not retry the push unprompted.

Never commit .env or secrets. Confirm .gitignore covers .env* (the scaffold ships one) and that no token ends up in the commit. If a secret was staged, unstage it and add it to .gitignore before committing.

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

Phase 7 — Connect the Preview to Weaverse Builder

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.

Phase 8 — 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 9 — Install the full skills pack (finish line)

End by installing the complete shopify-hydrogen-skills pack — all skills, all agents, noninteractive — inside the generated storefront project (not anywhere else). The setup request explicitly asks for this, so the install itself is expected:

npx skills@latest add Weaverse/shopify-hydrogen-skills --all

Then inspect what it generated:

git status --short          # review what the pack install generated

Publishing those changes is a separate external effect — ask again. Show the user the file list from git status and what the commit message would be, then wait for approval before running anything below:

git add -A && git commit -m "Add shopify-hydrogen-skills pack"
git push

If the user declines, leave the installed pack in the working tree and say it is uncommitted. Never run this commit/push block unconditionally.

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: install the Hydrogen app → npx shopify hydrogen link → npx shopify hydrogen env pull → verify PUBLIC_STORE_DOMAIN + PUBLIC_STOREFRONT_API_TOKEN are real before trusting them.
6. Ask approval for repo name/visibility/first push, then create repo + push (gh repo create after approval, manual fallback). Never commit .env/secrets.
7. Configure the Weaverse MCP (WEAVERSE_API_KEY; live writes only with consent via WEAVERSE_ENABLE_LIVE_WRITES=true).
8. Connect preview URL in Builder (Manage previews).
9. Verify required checks (200 + typecheck); run build when preparing handoff/production.
10. Install the full pack: npx skills@latest add Weaverse/shopify-hydrogen-skills --all; review git status, then ask approval before committing/pushing it.

Required vars quick reference