跳至正文
OpenAgentSkill
浏览已开放 · 目录记录日期 2026-11-21 · 自动更新和账户服务暂时关闭。
开发与测试

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 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_STOREF

阅读完整来源 ↗