Wode

Wode is Wener's TypeScript monorepo for React console surfaces, reusable UI primitives, service and API tooling, AI/MCP integrations, and protobuf contracts.

The name comes from Wener nODE & DEMO. The repository is organized as a pnpm workspace and uses Just for reusable task recipes and Vite, Vitest, Oxfmt, and Oxlint for development workflows.

Repository layout

Legacy experiments and the former standalone web/playground applications are not part of the tracked workspace. New demos belong in the component stories or in an application route with an explicit owner.

Requirements

• Node.js >=24.11.0
• pnpm 12.4.2
• Just 1.38.0 or newer
• Buf CLI for protobuf formatting, linting, and generation
• Chromium for the package Storybook interaction tests

The required package-manager and runtime versions are declared in the root package.json. Install pnpm with Corepack or through your preferred system package manager, then install dependencies:

corepack enable
pnpm install

For the package Storybook interaction tests, install Chromium once on the development machine:

pnpm -C packages/ui exec playwright install --with-deps chromium

Common commands

Run commands from the repository root unless a command includes -C.

Vite and Vitest own the repository's test workflow. New test files should import test APIs from vitest and run through pnpm exec vitest run or the package script that wraps it.

The root justfile imports reusable domain recipes from just/*.just. Recipes that operate in the caller's package use [no-cd], so the same file can be reused without duplicating a Makefile in every package:

cd packages/wener-common
just -f ../../just/package.just package-fmt
just -f ../../just/package.just package-typecheck
just -f ../../just/packages/wener-common.just build

Package-specific build and publish behavior belongs in just/packages/*.just; workspace-wide orchestration belongs in just/workspace.just, just/ci.just, and the domain files for Proto, components, and server entrypoints.

UI package

packages/ui owns the reusable, application-agnostic UI surface. It exposes independent subpaths such as @wener/ui/button, @wener/ui/dialog, @wener/ui/input, and the generic composed families under @wener/ui/components/*. It uses Base UI for stateful behavior and Tailwind CSS/DaisyUI-compatible classes for presentation. Its verification commands are:

pnpm -C packages/ui test
pnpm -C packages/ui typecheck
pnpm -C packages/ui build

Applications consuming @wener/ui must include the package source in their Tailwind scan and own their theme and font configuration. Application-specific routes, authentication, persistence, network calls, and server state stay outside the primitive package.

Server image operations require an explicit entrypoint and are never part of just ci:

just server-list
just server-image wener-apis-server
just server-deploy wener-apis-server

The last command requires Docker credentials and a matching apps/server/builds/<entrypoint>/Dockerfile; it is intentionally separate from validation and package builds.

Protobuf workflow

proto/ is the canonical protobuf source directory. Buf configuration is kept at the repository root in buf.yaml and buf.gen.yaml. The shared recipes live under just/; package-specific entrypoints can use just -f just/servers.just ... when they need to preserve their working directory.

just buf-fmt
just buf-lint
just buf-gen

Generation updates the checked-in clients under packages/common/src/protos. CI runs generation and verifies that the generated tree is clean, so generated changes must be committed together with their source or configuration change.

CI and branches

The GitHub Actions Build workflow runs on main, develop, and pull requests targeting those branches. It installs the declared pnpm, Node.js, and Just versions, runs just ci, runs the package UI tests, and builds the package Storybook. The default public branch is main; develop is the protected integration branch.

Pull requests provide their target commit as WODE_TEST_BASE. The CI test wrapper uses Vite+ related testing for ordinary source and Storybook changes, skips documentation-only changes, and falls back to full coverage for dependency, configuration, generated, deleted, or ambiguous inputs. Pushes and manual runs keep the full test baseline.

Before opening a pull request, run at least:

git diff --check
just ci
pnpm -C packages/ui test
pnpm -C packages/ui build-storybook:static

The root task entrypoint is just; there is no second root Makefile to keep in sync. Keep protobuf output deterministic, use Vite+ commands for new formatting and tests, and keep reusable UI contracts separate from application-specific behavior.

License

Wode is released under the MIT License.