zudo-sg Docs

Type to search...

to open search from anywhere

Installation

Clone the repository, install dependencies, and run the styleguide, docs, and demo workspaces.

Start a new styleguide

Use the initializer when you want a new project rather than a checkout of this repository:

pnpm create zudo-sg@latest my-styleguide
cd my-styleguide
pnpm install
pnpm gen-registry
pnpm gen-token-manifest
pnpm dev

The command prints these next steps and creates a private Preact + zfb host with example stories, token CSS, and the engine configuration.

For an existing host, use the manual installation and composition guide in the root site's Adopting the engine.

Requirements

  • Engine hosts and generated starters: Node.js 24. zfb 5 and zudo-doc 9 require it, and the engine's @takazudo/zudo-doc peer is ^9.1.2. The former zudo-doc 6.2.0 / Node.js 22 option was retired with zfb 5.

  • The create-zudo-sg CLI itself still runs on Node.js 22.

  • Repository development/CI: Node.js 24. html-validate 11.16.2 requires ^22.22.0 || >=24.8.0; retained jsdom dependencies additionally require ^22.22.2 || ^24.15.0 || >=26.0.0. These tool minima do not raise the engine consumer floor.

  • pnpm 11.5.2, matching the workspace packageManager field.

  • Git access to the repository.

Clone and install manually

Clone the existing zudo-sg repository and install the workspace dependencies from the root:

git clone https://github.com/Takazudo/zudo-sg.git
cd zudo-sg
pnpm install

This is not a scaffolding flow. You work inside the monorepo because the styleguide host, shared UI package, demo app, and docs site are developed together.

Run the styleguide host

The root package owns the styleguide host at https://zudo-sg.takazudomodular.com/.

pnpm dev
pnpm build
pnpm check

pnpm dev starts the zfb development server for the root styleguide host. pnpm build emits the static dist/ output, and pnpm check typechecks the host plus the workspace packages included by the root command.

Run the documentation site

The /doc package is this project documentation site.

pnpm --filter @zudo-sg/doc dev
pnpm --filter @zudo-sg/doc build
pnpm --filter @zudo-sg/doc check

Use the filtered commands when you are changing docs content or validating the docs site in isolation.

Run the demo app

The demo app is a multi-page corporate demo site that consumes @zudo-sg/demo-ui from the workspace and builds as a static site:

pnpm --filter @zudo-sg/demo dev
pnpm --filter @zudo-sg/demo build
pnpm --filter @zudo-sg/demo typecheck

Workspace map

The directories you will touch most often are:

  • src/: root styleguide host components, config, styles, and catalog data.

  • pages/: host-owned routes such as /, /components/*, and /docs/versions.

  • packages/demo-ui/: shared Preact components, stories, MDX component docs, and UI token CSS.

  • apps/demo/: multi-page corporate demo site (static, no SSR).

  • doc/: this documentation site.

Read Monorepo Layout for the ownership model behind those directories.

Existing consumer highlighting failures

A retained pnpm lock can preserve duplicate Lezer module identities, causing missing TSX/CSS syntax tokens and tags is not iterable plugin errors. Use the engine README's consumer lock recovery from the affected host: diagnose with pnpm dedupe --check, recover with pnpm dedupe --ignore-scripts, verify a frozen install, then rebuild and inspect actual highlighting and Live CSS behavior. This pnpm 11.5.2 recovery is separate from the still-open package-side compatibility requirement in #963.