gq-site
Shared tooling for GETQUICK sites, published to public npm as
@getquick/site: one gq
CLI, configured by each site's own gq.ops.json.
The blueprint generates and synchronizes managed files, provisions Ploi and Cloudflare, runs local CMS and workspace checks, and handles releases, database backups and live-to-local sync. Secrets are injected per command through Sigillo; generation and sync need no network access or secrets.
Quick start
For site setup, use the blueprint's Node pin (currently 24.21.0) and the pnpm
version in the site's packageManager. The CLI alone supports Node 22.12.0+;
that minimum is not enough for the site's full development toolchain. This
repository's contributor requirements are in Development.
Generate a content site
pnpm dlx @getquick/site new acme --project acme --variant content
cd acme
# Activate the Node pin in .mise.toml or .nvmrc before installing.
pnpm install
pnpm exec gq sync --check
The target directory must be empty. gq new creates the CMS and Frontend
app skeletons and prints the provisioning steps without running them. A
content site's Frontend is Astro or TanStack Start, its choice: in a terminal
gq new asks, and --framework astro|tanstack picks one (TanStack Start when
omitted outside a terminal). See Frontend frameworks.
See Generate and sync a site for ownership, adoption,
and handling sync conflicts, then Local development
or Provisioning and deployment.
Use an existing site
Pin an exact version in the site's root devDependencies; no registry login
is needed:
pnpm add --save-dev --save-exact @getquick/site
pnpm exec gq --help
Configure gq.ops.json before running site
commands. A manifest without schemaVersion, or release settings in a
shop-devtools.config.mjs, is migrated by gq sync --manifest: see the
manifest reference and the
release reference.
Redeploy one package
To ship a new build of one GETQUICK Composer package (such as GQ Design's
main, required as "dev-main as 0.5.99") to a Site's CMS without a tagged
release, run from a clean tree of the Site:
pnpm release:package getquick/gq-design
# = gq sigillo run staging -- gq release package getquick/gq-design
It updates that package in apps/cms/composer.lock with the registry login,
syncs the current version, commits, and deploys the commit with
gq ploi release. Push the commit afterwards. See
release package and
a Site on a branch.
Documentation
- Site guides: Generate and sync · Local development · Secrets · Provisioning and deployment · Offboarding · Agent skills
- Reference: Manifest and environment ·
Commands ·
Release and version behavior ·
Programmatic
run()interface - Contributors: Development and publishing
- Design and records: Documentation map
These guides and references ship with the npm package. The Ploi API inventory is a dated research snapshot, not the current command reference.
Current status
Phases 1–3 of the rollout (extraction, content-site generation, and adoption
by an existing content site) have passed. Managed-file changes originate here;
a site takes them by bumping its pin and running gq sync. gq new --variant commerce
generates a commerce site with the storefront Runtime mounted, whose install needs a
GitHub Packages token
(ADR 0017);
gq site check is its readiness gate
(ADR 0021),
and commerce adoption and fleet rollout are gated work.
See the rollout record
for evidence and remaining gates, and
ADR 0001
for the blueprint decision.