setup-weaverse-project
Set up a new Weaverse Hydrogen storefront locally from a Weaverse theme. Boot a live demo-store preview before asking for any credentials, then make it the merchant's own: install the Hydrogen app, link the store, pull the Storefront credentials, push the repo to GitHub, configure the Weaverse MCP for live page edits, and install the full shopify-hydrogen-skills pack.
Weaverse · 已有 AI 审核记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add Weaverse/shopify-hydrogen-skills --skill setup-weaverse-project技能说明
name: setup-weaverse-project description: "Set up a new Weaverse Hydrogen storefront locally from a Weaverse theme. Boot a live demo-store preview before asking for any credentials, then make it the merchant's own: install the Hydrogen app, link the store, pull the Storefront credentials, push the repo to GitHub, configure the Weaverse MCP for live page edits, and install the full shopify-hydrogen-skills pack."
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
pilotonly when omitted - Project folder name — default to
my-hydrogen-storefront
Required later for the real store:
PUBLIC_STORE_DOMAINPUBLIC_STOREFRONT_API_TOKEN
Generated by you:
SESSION_SECRET— never ask the user for this; generate a random value
Optional later:
PRIVATE_STOREFRONT_API_TOKENSHOP_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
blankhandle), show the supported template list and ask the user for the replacement. Do not silently switch themes. - If
--no-installis 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
.envshould already contain demo Shopify values plus the user'sWEAVERSE_PROJECT_ID. If.envis missing, copy.env.exampleto.env, then setWEAVERSE_PROJECT_IDfrom 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.envnow:
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.comPUBLIC_STOREFRONT_API_TOKEN— Storefront API access tokenWEAVERSE_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_STOREF