wisewigdocs
GitHubWebsite

Getting started

This guide creates a local, editable five-page site from the repository. The CLI is currently a workspace tool, so run these commands from the WiseWig repository root and scaffold into the repository (for example under examples/). It is not yet a standalone published create-wise-wig package.

Prerequisites

  • Node.js compatible with the repository’s packageManager entry
  • pnpm 10.11.0
  • Chrome only if you want to exercise the local browser-extension sign-in handoff

1. Install and scaffold

pnpm install
pnpm wise-wig create site examples/acme-services --title "Acme Services"
pnpm install

The first install prepares the CLI. The second discovers the new workspace package. The command refuses to overwrite an existing target. Use --dry-run first if you want to inspect its planned files.

The generated site is a copy of the tested Morning Bell reference, not a second template. It includes Home, About, Services, Gallery, and Contact; a primary menu; page SEO metadata; a contact form; media-capable sections; the visual editor; and the local demo repository.

2. Run the generated site

pnpm --filter @wise-wig/acme-services dev

Open http://localhost:4321/. This is the anonymous published view: server-rendered and free of editor metadata.

The local demo keeps state in memory. Restarting the Astro development server resets draft and published content. It is for theme and integration development only, not production authentication or persistence.

3. Enter edit mode locally

For browser-only local entry, set the demo editor cookie as shown in the repository README and open /?__edit=1. Edit mode presents the WiseWig browser workspace with the real Astro page in its responsive canvas.

You can also load apps/extension as an unpacked Chrome extension from chrome://extensions, then open the site and click Edit this site in the extension popup. The extension recognizes the site through a non-secret meta declaration and performs the localhost-only handoff to the same workspace. Its next design pass will make it a persistent launcher and companion; it will not become a separate editing runtime.

For a quick local-only alternative, set this cookie in the browser console, then open /?__edit=1:

document.cookie = "wise_wig_editor=demo-editor; path=/";

The query parameter does not itself authenticate anyone. It remains a compatibility fallback. Production extension entry and /api/auth/start use OAuth/OIDC, a signed revocable session, authoritative site-role checks, and a separate non-authoritative mode cookie.

4. Make the first changes

  1. Click a heading or body directly on the page, type as you would in a document, then move focus and wait for the saved state.
  2. Open Add in the right sidebar. Drag an approved component between page sections, or click/tap it to append. Disabled entries have reached a developer-defined placement or instance limit.
  3. Select a section to open Edit for layout, assets, repeatable items, links, and structural actions that do not belong inline.
  4. Open /admin while signed in to manage pages.
  5. Add a page from Basic, Services, Gallery, or Contact. Give it a stable ID, route slug, title, and optional SEO description.
  6. Use Edit visually to change its component content. Page settings can update the title, slug, navigation label, order, or redirect target.
  7. Use the explicit publish action. Pages, primary navigation, and redirects publish together, so a changed route cannot publish with stale navigation.

For the complete behavior and route rules, read Page lifecycle in the content model and Site management UI.

5. Brand and theme the site

Start with the generated local content seed:

examples/acme-services/src/lib/site-content.ts

Replace its schema-valid text, contact data, navigation labels, and page documents. Style the site with CSS custom properties and component styles in src/styles/global.css. Tailwind can consume the generated theme variables, but it is optional.

To generate a theme foundation:

pnpm wise-wig generate theme acme --cwd examples/acme-services

The generated theme includes explicit registration notes. Current alpha custom components and themes still require manual registration in the typed component/rendering boundaries; see Component interface and Scaffolding CLI.

6. Validate before deployment

pnpm --filter @wise-wig/acme-services check
pnpm --filter @wise-wig/acme-services build
pnpm test
pnpm check
pnpm build

The site-level commands validate the generated Astro app. The repository-wide gates additionally exercise shared contracts, real-workerd Cloudflare boundaries, and Chromium browser flows.

7. Prepare Cloudflare deployment

The reference production topology has two required Workers: the Astro site and tenant workspace. Plugin and public/private MCP Workers are opt-in. From the repository root:

pnpm wise-wig cloudflare plan --profile core --cwd examples/acme-services
pnpm wise-wig cloudflare prepare --profile core --cwd examples/acme-services
pnpm wise-wig doctor --profile core --cwd examples/acme-services

doctor identifies account-specific bindings and secrets that must be configured. It never reads or prints secret values. Follow Cloudflare deployment for provisioning, verified domains, OAuth/OIDC configuration, and the safe deployment order.

WiseWig-hosted sites use the tenant dispatcher instead of a shared workspace binding:

pnpm wise-wig cloudflare prepare --managed-isolated --cwd examples/acme-services
pnpm wise-wig doctor --managed-isolated --cwd examples/acme-services

The managed preparation command fails unless the built Astro Worker is pinned to the trusted dispatcher, and it removes direct access to the shared tenant workspace and plugin sandbox before deployment.

Where to go next