WoodsCLI

HubSpot CMS dev kit by WoodsPortal — scaffold modules and themes, local preview, module field editing, Vite builds, and HubSpot upload/watch.

npm i -D @woodsportal/hubspot-kit
npx wp --version

The wp CLI wraps @hubspot/cli and adds WoodsPortal tooling: hybrid CDN or monolith builds, the module-config overlay (Ctrl+Shift+Z), optional portal auth scaffold (woodsportal-client-sdk), and a .wphs/ workspace.

Not for HubSpot UI extensions — see woods-portal-ui-card.

Choose your path

| You are… | Start here | |----------|------------| | New HubSpot CMS module (React portal) | Quick start below | | New theme | wp init -t theme-starter → THEMES.md | | Existing module / artifact folder | Existing repository | | Full production portal (reference) | woodsportal-client-frontend |

Scaffold matrix (wp init)

| Template | Router | Auth tier | You get | |----------|--------|-----------|---------| | module-hybrid-cdn | hash (default) | none | React SPA + TanStack routes + starter pages | | module-hybrid-cdn | hash | starter | + email/password login + protected /portal sample | | module-hybrid-cdn | hash | sso | + SSO OAuth callback | | module-hybrid-cdn | hash | full | + MFA (production portals) | | module-monolith | … | … | Same auth tiers, single module.js bundle | | theme-starter | — | — | HubL theme only (no portal auth) |

Bare wp init runs an interactive wizard: project type → name → router → portal auth → CDN mirror (hybrid) → confirm.

Auth tier examples (full commands)

Use module-hybrid-cdn + --router hash for all portal auth tiers. HubSpot upload auth (wp auth) is separate from portal login — run it when you need Design Manager upload/watch.

No portal auth (scaffold.auth: none) — routes and starter pages only; no woodsportal-client-sdk login UI:

npx wp init -t module-hybrid-cdn -n my-module-no-auth --router hash --auth none -y
cd my-module-no-auth
npm install          # or: touch yarn.lock && yarn install
wp setup
wp doctor
wp dev               # http://localhost:3000/#/guide

Starter auth (scaffold.auth: starter) — email + password login, protected /portal sample:

npx wp init -t module-hybrid-cdn -n my-portal-starter --router hash --auth starter -y
cd my-portal-starter
npm install
wp setup
# Edit .env.local — API base URL (required); optional dev portal context:
#   VITE_PUBLIC_REST_API_ENDPOINT=https://api.dev.woodsportal.com
#   VITE_DEV_PORTAL_ID=<portal-id>
wp doctor
wp dev
# Sign in: http://localhost:3000/#/login  →  redirects to /portal

SSO auth (scaffold.auth: sso) — starter login + /login/sso OAuth callback:

npx wp init -t module-hybrid-cdn -n my-portal-sso --router hash --auth sso -y
cd my-portal-sso
npm install
wp setup
# Same .env.local as starter (API URL + optional VITE_DEV_PORTAL_ID)
wp doctor
wp dev
# Password login: /#/login  |  SSO return path: /#/login/sso

Full auth (scaffold.auth: full) — SSO + MFA (/two-fa); recommended for production-shaped portals:

npx wp init -t module-hybrid-cdn -n my-portal-full --router hash --auth full -y
cd my-portal-full
npm install
wp setup
# Same .env.local as starter
wp doctor
wp dev
# Login + MFA: /#/login  →  /#/two-fa when hub requires MFA

| Tier | woodscli.json | Routes added (beyond none) | |------|-----------------|------------------------------| | none | "auth": "none" | /guide only (no /login) | | starter | "auth": "starter" | /login, protected /portal | | sso | "auth": "sso" | + /login/sso | | full | "auth": "full" | + /two-fa, MFA storage |

Monolith template: swap -t module-hybrid-cdn for -t module-monolith (same --auth flags). Details: AUTH-SCAFFOLD.md.

Sidebar navigation (scaffold.nav: sidebar) — collapsible left menu instead of top header links (requires auth ≠ none):

npx wp init -t module-hybrid-cdn -n my-portal-sidebar --router hash --auth starter --nav sidebar -y

Default nav shell is top (scaffold.nav: top). Edit src/config/portal-nav.ts to add menu items — both layouts read the same file.

Navigation by auth tier

| Auth | Nav file | Shell | |------|----------|-------| | none | src/config/starter-nav.ts | StarterNav in root layout | | starter+ | src/config/portal-nav.ts | MainLayout (top or sidebar) |

wp init --nav chooses the layout shell (auth only). wp page add --nav adds a menu link to the nav file for your tier.

Add pages after init:

wp page add settings --protected --nav
wp page add about --public
wp page list
wp page remove about

Upgrade scaffold on existing projects:

wp scaffold auth upgrade --tier sso
wp scaffold nav --mode sidebar

Two auth concepts

| | HubSpot CLI auth | Portal user auth | |--|------------------|------------------| | Commands | wp auth, wp portal use | wp init --auth starter\|sso\|full | | Config | hubspot.config.yml | woodscli.json → scaffold.auth, scaffold.nav, .env.* API URL | | Purpose | Upload/watch to Design Manager | End users log in via woodsportal-api + SDK |

See HUBSPOT-CLI-SETUP.md and AUTH-SCAFFOLD.md.

What you get

| Capability | Command / artifact | |------------|-------------------| | Scaffold module or theme | wp init (--template, --router, --auth) | | Local SPA + field editor | wp dev (wp local) | | HubSpot file sync | wp watch, wp upload | | Full ship pipeline | wp deploy (build → CDN publish → upload) | | Project health check | wp doctor | | CI / regression gates | wp examples smoke, wp regression smoke |

Prerequisites

| Requirement | Notes | |-------------|--------| | Node.js 20+ | Enforced by wp doctor | | HubSpot CLI | npm i -g @hubspot/cli — upload/watch/deploy | | HubSpot CMS portal | Design Manager; wp auth for upload | | woodscli.json | Created by wp init |

Local preview runs without HubSpot credentials. Portal auth tiers need VITE_PUBLIC_REST_API_ENDPOINT after wp setup.

Quick start (greenfield)

npx wp init -t module-hybrid-cdn -n my-portal --router hash --auth full -y
cd my-portal && npm install

wp setup          # hubspot.config.yml, .env.*, vite shims
wp doctor
wp auth           # HubSpot CMS (upload) — not portal login
wp dev            # http://localhost:3000

Module overlay: Ctrl+Shift+Z / Cmd+Shift+Z — edit Content/Styles fields.

Password-only portal: --auth starter. Details: AUTH-SCAFFOLD.md.

Existing repository

wp setup
wp migrate --yes    # legacy .dev/ or woodsportal.hs.json
wp doctor

Legacy <name>.module/ folders: add woodscli.json manually → MODULES.md.

Day-to-day workflows

Local development

wp dev
wp dev -p 3001

Build and ship

wp build --tier dev
wp deploy --tier dev      # hybrid: build + CDN publish + upload
wp upload --tier prod     # module/theme only

Tiers: dev | stg | prod. See BUILD-MODES.md.

Command reference (init)

| Command | Description | |---------|-------------| | wp init | Interactive scaffold wizard | | wp init -t module-hybrid-cdn -n slug | Hybrid CDN module | | wp init --router hash \| browser \| none | Client routing (modules) | | wp init --auth none \| starter \| sso \| full | Portal auth tier (modules, router ≠ none) | | wp init --nav top \| sidebar | Authenticated nav shell (requires auth ≠ none) | | wp page add [slug] | Scaffold route + page (--public / --protected, --nav / --no-nav) | | wp page list | List scaffolded pages under src/features/pages/ | | wp page remove <slug> | Remove scaffolded page, route, and nav entry | | wp scaffold auth upgrade --tier … | Upgrade portal auth on existing module (starter | sso | full) | | wp scaffold nav --mode … | Re-apply top or sidebar MainLayout shell | | wp init --cdn-github org/repo | Hybrid CDN GitHub mirror (non-interactive) |

Global flags: --project, --ci, --json, --dry-run, -y/--yes.

Full list: CLI-REFERENCE.md

Project layout

my-project/
├── woodscli.json           # projectType, scaffold.router, scaffold.auth, scaffold.nav
├── hubspot.config.yml      # HubSpot CLI (gitignored)
├── wphs.adapter.ts
├── .wphs/                  # module-config overlay state
├── src/
│   ├── routes/             # TanStack file routes (when router ≠ none)
│   ├── features/auth/      # when scaffold.auth ≠ none
│   └── portal/mount-portal.tsx
└── dist/

Documentation

| Doc | Read when… | |-----|------------| | GETTING-STARTED.md | First run walkthrough | | AUTH-SCAFFOLD.md | Portal login tiers, env, boot order | | CLI-REFERENCE.md | All commands and exit codes | | MODULES.md | Hybrid CDN, monolith, overlay | | THEMES.md | Theme starter | | HUBSPOT-CLI-SETUP.md | PAT, wp auth, portals | | CONFIG-REFERENCE.md | woodscli.json fields | | BUILD-MODES.md | CDN vs monolith, tiers | | TROUBLESHOOTING.md | Common failures | | RUNBOOK.md | Ops and release | | CONTRIBUTING.md | PR verify workflow |

Develop the kit

git clone https://github.com/Digital-Woods/digitalwoods.io-woodsportal-hubspot-kit.git
cd digitalwoods.io-woodsportal-hubspot-kit
npm ci
npm run verify

Link in a consumer:

npm i -D @woodsportal/hubspot-kit@file:../digitalwoods.io-woodsportal-hubspot-kit

License

MIT — Digital Woods