CloudCannon Bookshop
Bookshop is CloudCannon's earlier component system: a component library, a build step that generates the editor's structures, and a live-editing engine that re-renders components in the Visual Editor. Editable regions replace it. This skill covers reading a Bookshop site, keeping one running, and moving it off Bookshop.
When to use
- The site has any signal in § Detecting Bookshop
- Adding or changing a component on a Bookshop site
- Migrating a Bookshop site to editable regions
- Bookshop live editing, structures or builds are misbehaving
When not to use
- The site has no Bookshop signals — use
cloudcannon-visual-editing. MUST NOT add Bookshop to a site that doesn't have it; new component editing is always editable regions. - Bookshop is gone and only regions remain — that is
cloudcannon-visual-editing, including its troubleshooting. - Configuration unrelated to components —
cloudcannon-configuration.
Detecting Bookshop
Any one signal means the site uses Bookshop.
| Signal | Where |
|---|---|
bookshop/bookshop.config.{js,cjs} |
src/ (Astro) or component-library/ (Hugo, Eleventy, Jekyll, Next.js) |
*.bookshop.{yml,yaml,toml,json,js,cjs} beside each component |
component-library/components/ or src/components/ |
@bookshop/* packages |
package.json, in dependencies or devDependencies |
npx @bookshop/generate |
.cloudcannon/postbuild |
_bookshop_name keys |
Front matter, usually under content_blocks; sometimes component code too |
| The SSG's Bookshop plugin, module or integration, and its template calls | Site config and layouts — see the SSG's bookshop.md |
SSG support
Migrate when editable regions can re-render the SSG's components. Otherwise the site stays on Bookshop.
| SSG | Bookshop engine | Path | Docs |
|---|---|---|---|
| Astro | @bookshop/astro-engine |
Migrate — migrating-to-editable-regions.md | astro/overview.md |
| Hugo | @bookshop/hugo-engine |
Migrate — migrating-to-editable-regions.md | hugo/overview.md |
| Eleventy | @bookshop/eleventy-engine |
Migrate — migrating-to-editable-regions.md | eleventy/overview.md |
| Next.js | None — @bookshop/generate writes structures only |
Migrate — migrating-to-editable-regions.md | nextjs/overview.md |
| Jekyll | @bookshop/jekyll-engine |
Stay on Bookshop — maintaining.md. Editable regions have no Jekyll component support yet | — |
Maintain or migrate?
| The user wants… | Do |
|---|---|
| A component added or changed, nothing more | maintaining.md — don't start a migration unasked |
| Off Bookshop, on an SSG marked Migrate | migrating-to-editable-regions.md |
| Off Bookshop, on an SSG marked Stay | Explain it isn't possible yet; offer maintaining.md |
The site moved onto CloudCannon (migrate-to-cloudcannon) |
Migrate, inside that journey's phases — the migration file maps the steps |
| Unclear | Ask. A migration rewrites every component and page layout |
Contents
| File | Covers |
|---|---|
| SKILL.md (this file) | Detection, SSG support, routing |
| bookshop.md | How Bookshop works — library layout, *.bookshop.yml, @bookshop/generate, live editing, bindings |
| maintaining.md | Changing a site that stays on Bookshop |
| migrating-to-editable-regions.md | The step order, structures from *.bookshop.yml, the _bookshop_name rename, removing Bookshop |
| troubleshooting.md | Symptom → cause → fix, on Bookshop sites and partway through a migration |
SSG-specific:
Enter through the SSG's overview.md; it gives the reading order for that SSG's files.
| SSG | Doc | Purpose |
|---|---|---|
| Astro | astro/overview.md | Start here for Astro |
| Hugo | hugo/overview.md | Start here for Hugo |
| Eleventy | eleventy/overview.md | Start here for Eleventy |
| Next.js | nextjs/overview.md | Start here for Next.js |
Other skills:
| Skill | When to read |
|---|---|
| cloudcannon-visual-editing | During a migration — the regions, the census and the completeness checklist |
| cloudcannon-configuration | Writing and validating the _structures that replace generated ones |
| cloudcannon-dev-server | Letting the user try the migrated site in a local editor |
Common mistakes
| Excuse | Reality |
|---|---|
| "It's a Bookshop site, so I'll migrate it" | Only if the user asked and the SSG is marked Migrate. A component change on a Bookshop site is a Bookshop change. |
| "This new component can be an editable-regions one" | On a site staying on Bookshop, new components are Bookshop components — maintaining.md § Adding a component. |