setup-weaverse-project

Name: setup-weaverse-project
Author: Weaverse

83stars25forks

How to install setup-weaverse-project?

weaverse/shopify-hydrogen-skills/setup-weaverse-project

$npx -y skills add Weaverse/shopify-hydrogen-skills --skill setup-weaverse-project

Installs into the current project.

Summary

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.

Files · 1

View on GitHub

SKILL.md

1	# Set Up a Weaverse Project — Agent Skill
2
3	> Take a user from nothing to a running, connected Weaverse Hydrogen storefront.
4	> This is the front door. Every other Weaverse skill assumes the project already exists — this one creates it.
5
6	## The One Rule That Fixes Onboarding
7
8	Boot a live preview on the demo store BEFORE asking for any credentials.
9
10	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.
11
12	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.
13
14	## You Drive the CLI — The User Never Types It
15
16	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.
17
18	## Inputs You Need
19
20	Ask for as little as possible. Most setup values are generated or discovered.
21
22	Required from the setup prompt or user:
23
24	- `WEAVERSE_PROJECT_ID` — from Weaverse Builder
25	- Theme handle — default to `pilot` only when omitted
26	- Project folder name — default to `my-hydrogen-storefront`
27
28	Required later for the real store:
29
30	- `PUBLIC_STORE_DOMAIN`
31	- `PUBLIC_STOREFRONT_API_TOKEN`
32
33	Generated by you:
34
35	- `SESSION_SECRET` — never ask the user for this; generate a random value
36
37	Optional later:
38
39	- `PRIVATE_STOREFRONT_API_TOKEN`
40	- `SHOP_ID`
41	- customer account vars
42	- checkout domain
43	- analytics/reviews vars
44
45	---
46
47	## Phase 0 — Detect the Environment
48
49	Before doing anything, detect and record (do not assume):
50
51	```bash
52	node --version # need >= 18
53	git --version
54	gh --version 2>/dev/null && gh auth status 2>/dev/null # is GitHub CLI present AND authed?
55	npx shopify version 2>/dev/null # Shopify CLI availability
56	npx @weaverse/cli@latest create --help 2>/dev/null # CLI availability + template choices
57	ls package-lock.json pnpm-lock.yaml yarn.lock 2>/dev/null # infer package manager
58	```
59
60	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.
61
62	---
63
64	## Phase 1 — Scaffold the Theme with Weaverse CLI
65
66	Prefer the Weaverse CLI over `git clone`. It knows the supported templates, downloads the correct source, and writes the initial env file.
67
68	```bash
69	npx @weaverse/cli@latest create \
70	--template=<theme-handle> \
71	--project-id=<WEAVERSE_PROJECT_ID> \
72	--project-name=<project-folder> \
73	--no-install \
74	-y
75
76	cd <project-folder>
77	git init
78	```
79
80	Rules:
81
82	- If the theme handle is missing, default to `pilot`.
83	- 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.
84	- If `--no-install` is not supported by the installed CLI, let the CLI install dependencies, then continue from the created folder.
85	- 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.
86
87	---
88
89	## Phase 2 — THE WOW MOMENT (boot on the demo store)
90
91	This is the centerpiece. Get a live preview running with the demo Shopify credentials before asking for Shopify credentials.
92
93	First, make sure `.env` is complete before the server boots (dev servers read the environment at startup — fixing it later means a restart):
94
95	- 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.
96	- 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:
97
98	```bash
99	node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
100	```
101
102	Then boot:
103
104	```bash
105	npm install # or pnpm/yarn per lockfile
106	npm run dev # boots http://localhost:3456
107	```
108
109	Then verify it actually came up before saying anything succeeded:
110
111	```bash
112	curl -sf -o /dev/null -w "%{http_code}" http://localhost:3456 # expect 200
113	```
114
115	Tell the user, in plain language:
116	> "Your storefront is running loca

People who liked this also viewed

6 picks

Type

setup-weaverse-project

83stars25forks

View on GitHub

How to install setup-weaverse-project?

weaverse/shopify-hydrogen-skills/setup-weaverse-project

$npx -y skills add Weaverse/shopify-hydrogen-skills --skill setup-weaverse-project

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# Set Up a Weaverse Project — Agent Skill
2
3	> Take a user from nothing to a running, connected Weaverse Hydrogen storefront.
4	> This is the front door. Every other Weaverse skill assumes the project already exists — this one creates it.
5
6	## The One Rule That Fixes Onboarding
7
8	Boot a live preview on the demo store BEFORE asking for any credentials.
9
10	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.
11
12	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.
13
14	## You Drive the CLI — The User Never Types It
15
16	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.
17
18	## Inputs You Need
19
20	Ask for as little as possible. Most setup values are generated or discovered.
21
22	Required from the setup prompt or user:
23
24	- `WEAVERSE_PROJECT_ID` — from Weaverse Builder
25	- Theme handle — default to `pilot` only when omitted
26	- Project folder name — default to `my-hydrogen-storefront`
27
28	Required later for the real store:
29
30	- `PUBLIC_STORE_DOMAIN`
31	- `PUBLIC_STOREFRONT_API_TOKEN`
32
33	Generated by you:
34
35	- `SESSION_SECRET` — never ask the user for this; generate a random value
36
37	Optional later:
38
39	- `PRIVATE_STOREFRONT_API_TOKEN`
40	- `SHOP_ID`
41	- customer account vars
42	- checkout domain
43	- analytics/reviews vars
44
45	---
46
47	## Phase 0 — Detect the Environment
48
49	Before doing anything, detect and record (do not assume):
50
51	```bash
52	node --version # need >= 18
53	git --version
54	gh --version 2>/dev/null && gh auth status 2>/dev/null # is GitHub CLI present AND authed?
55	npx shopify version 2>/dev/null # Shopify CLI availability
56	npx @weaverse/cli@latest create --help 2>/dev/null # CLI availability + template choices
57	ls package-lock.json pnpm-lock.yaml yarn.lock 2>/dev/null # infer package manager
58	```
59
60	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.
61
62	---
63
64	## Phase 1 — Scaffold the Theme with Weaverse CLI
65
66	Prefer the Weaverse CLI over `git clone`. It knows the supported templates, downloads the correct source, and writes the initial env file.
67
68	```bash
69	npx @weaverse/cli@latest create \
70	--template=<theme-handle> \
71	--project-id=<WEAVERSE_PROJECT_ID> \
72	--project-name=<project-folder> \
73	--no-install \
74	-y
75
76	cd <project-folder>
77	git init
78	```
79
80	Rules:
81
82	- If the theme handle is missing, default to `pilot`.
83	- 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.
84	- If `--no-install` is not supported by the installed CLI, let the CLI install dependencies, then continue from the created folder.
85	- 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.
86
87	---
88
89	## Phase 2 — THE WOW MOMENT (boot on the demo store)
90
91	This is the centerpiece. Get a live preview running with the demo Shopify credentials before asking for Shopify credentials.
92
93	First, make sure `.env` is complete before the server boots (dev servers read the environment at startup — fixing it later means a restart):
94
95	- 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.
96	- 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:
97
98	```bash
99	node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
100	```
101
102	Then boot:
103
104	```bash
105	npm install # or pnpm/yarn per lockfile
106	npm run dev # boots http://localhost:3456
107	```
108
109	Then verify it actually came up before saying anything succeeded:
110
111	```bash
112	curl -sf -o /dev/null -w "%{http_code}" http://localhost:3456 # expect 200
113	```
114
115	Tell the user, in plain language:
116	> "Your storefront is running loca

People who liked this also viewed

6 picks

Type