114 lines
7.4 KiB
Markdown
114 lines
7.4 KiB
Markdown
# CODEBUDDY.md
|
|
|
|
This file provides guidance to CodeBuddy Code when working with code in this repository.
|
|
|
|
## Overview
|
|
|
|
G3Soft frontend infrastructure — a pnpm monorepo holding a self-built **Vue 3 component library** plus a **Docus documentation site**.
|
|
|
|
- `packages/ui` (`@g3soft/ui`) — component library, published to a private npm registry. One directory per component under `src/<name>/`.
|
|
- `packages/tokens` (`@g3soft/tokens`) — design tokens as plain CSS (`--g3-*` variables), shared by the library and the docs site.
|
|
- `docs` (`@g3soft/docs`) — Docus/Nuxt docs site. `private: true`, never published.
|
|
- `scripts/gen-api.mjs` — generates component API data from source.
|
|
|
|
Requires Node >= 20.19 and pnpm 11 (see `packageManager` in root `package.json`).
|
|
|
|
## Commands
|
|
|
|
```bash
|
|
pnpm install
|
|
|
|
pnpm dev # start docs site (http://localhost:3000); live-reloads packages/ui via alias
|
|
pnpm build # build all packages under packages/** (component lib -> dist)
|
|
pnpm build:docs # build docs static site -> docs/.output/public
|
|
pnpm preview:docs # preview the built docs site
|
|
|
|
pnpm gen:api # regenerate docs/data/api/*.json from component source (REQUIRED after changing props/events/slots)
|
|
```
|
|
|
|
Deploying docs to a subpath:
|
|
|
|
```bash
|
|
NUXT_APP_BASE_URL=/docs/ pnpm build:docs
|
|
```
|
|
|
|
Releasing the component library (changesets):
|
|
|
|
```bash
|
|
pnpm changeset # record the change
|
|
pnpm version # bump versions + generate CHANGELOG
|
|
pnpm release # build + publish to the private registry
|
|
```
|
|
|
|
`packages/ui` runs `publint` via `prepublishOnly` to validate package structure (`exports`/`files` consistency).
|
|
|
|
**Testing:** there is no test runner configured in this repo (no vitest/jest, no test files). Do not assume `pnpm test` exists.
|
|
|
|
### Running a single component's checks
|
|
|
|
There is no per-component test/lint script. The closest equivalent is `pnpm --filter @g3soft/ui build` (runs `vite build`, which type-checks declarations via `vite-plugin-dts`), and `pnpm gen:api` to verify the docgen extraction still parses a component.
|
|
|
|
## Architecture
|
|
|
|
### Two independent pipelines
|
|
|
|
The docs site and the component library are deliberately decoupled:
|
|
|
|
| | Docs site | Component package |
|
|
|---|---|---|
|
|
| Published | No (`private: true`) | Yes (private npm registry) |
|
|
| Versioning | None | changesets (`ignore: ["@g3soft/docs"]`) |
|
|
| Build | `pnpm build:docs` | `pnpm build` |
|
|
| Output | `docs/.output/public` (static) | `packages/ui/dist` (ESM + d.ts) |
|
|
| Dep boundary | Docus/Nuxt/Tailwind live only in the `docs` package | only `vue` (peer) + `@g3soft/tokens` |
|
|
|
|
Nuxt-related deps appear **only** in `docs/package.json`; the library's dependency tree has none of it. changesets' `ignore` keeps the docs site out of version tags.
|
|
|
|
### Component library build (`packages/ui`)
|
|
|
|
`vite.config.ts` builds ESM + type declarations. Critical points:
|
|
- `vue` is marked `external` — never bundle Vue, or consumers get duplicate instances.
|
|
- `preserveModules` keeps the `src` structure so consumers can tree-shake.
|
|
- `vite-plugin-dts` with `rollupTypes` emits a single `dist/index.d.ts`, matched by `exports.types`.
|
|
- `src/index.ts` is the public entry: it re-exports every component plus its types, and exports the optional `G3UI` install plugin for whole-library registration.
|
|
|
|
### Docs site (`docs`)
|
|
|
|
- `extends: ['docus']` — all navigation/search/theme comes from the Docus Nuxt Layer.
|
|
- `vite.resolve.alias` points `@g3soft/ui` and `@g3soft/tokens` **directly at `packages/*/src`**, so the docs site can develop against the library without building it. Editing `packages/ui` hot-reloads the docs immediately.
|
|
- `site.url` is required (sitemap, llms.txt, OG images) — missing it breaks prerender with a 500.
|
|
- Deploy base path comes from `NUXT_APP_BASE_URL` (Nuxt's env override for `app.baseURL`), never hardcoded.
|
|
- `docs/app/components/content/` holds components usable directly inside Markdown: `Demo.vue` (renders a runnable example + source) and `ApiTable.vue` (renders the generated API tables).
|
|
|
|
### API generation pipeline
|
|
|
|
`scripts/gen-api.mjs` uses `vue-docgen-api` to parse every `.vue` under `packages/ui/src`, extracts props/events/slots and their JSDoc comments, and writes `docs/data/api/<dirName>.json`. `ApiTable.vue` reads those JSON files by component name.
|
|
|
|
Consequence: **API tables are generated from source and must never be hand-written.** The component directory name is the doc key (`src/button/Button.vue` → `button`). After any change to a component's props/events/slots, run `pnpm gen:api`.
|
|
|
|
### Design tokens (`packages/tokens`)
|
|
|
|
- `src/index.css` imports `tokens.css` (light/default) and `dark.css`. Consumed as `import '@g3soft/tokens'`.
|
|
- Dark theme activates via `html[data-g3-theme='dark']` (`document.documentElement.dataset.g3Theme = 'dark'`).
|
|
- Re-theming/customer customization = overriding same-named `--g3-*` variables, no component changes.
|
|
|
|
### Windows: dev-server port selection
|
|
|
|
`docs/package.json` runs `node scripts/dev.mjs` for `dev` (not `nuxt dev` directly). On Windows, Node sets `SO_REUSEADDR`, so **two processes can bind the same `host:port`**. Nuxt's built-in "is the port free?" check works by *trying to bind* a probe socket — which therefore succeeds even when another service already listens on 3000, so `pnpm dev` silently lands on 3000 (no 3000→3001 fallback). `scripts/dev.mjs` sidesteps this by testing the port with a real TCP *connection* (`connect` to `127.0.0.1`/`::1`) and walking upward from `DOCS_PORT`/`PORT`/3000 until it finds a free one, then passing `--port`. `devServer.host: ''` (empty string — deliberately not `'0.0.0.0'`) makes listhen listen on all interfaces *and* print a usable `Local: http://localhost:<port>/` plus the LAN `Network:` URL; with `'0.0.0.0'` the Local line would be an unopenable `http://0.0.0.0:<port>/`.
|
|
|
|
## Conventions (must follow)
|
|
|
|
- **No `scoped` in component `<style>`.** Isolate with the `g3-` prefix + BEM naming so consumers can override.
|
|
- **Never hardcode colors or sizes** — always reference `--g3-*` variables, and give every variable a fallback value (e.g. `var(--g3-color-primary, #1677ff)`) so components render correctly even when `@g3soft/tokens` is not loaded.
|
|
- **Component API docs are generated, not authored** — changes to props/events/slots require `pnpm gen:api`.
|
|
- **Examples** live at `docs/examples/<component>/<example>.vue` and are referenced in Markdown as `::demo{name="<component>/<example>"}`. API tables use `<ApiTable name="<component>" />`.
|
|
- New components get a `src/<name>/` directory (component `.vue`, `types.ts`, `index.ts`) and must be re-exported from `src/index.ts`.
|
|
|
|
## Version constraints (do not relax)
|
|
|
|
`pnpm-workspace.yaml` documents these deliberately — read it before touching dependency versions:
|
|
|
|
- **`nuxt` is pinned to exactly `4.4.8` in `docs/package.json`.** Do not widen to `^4.4.8` or upgrade to 4.5+. Nuxt 4.5+ pulls Vite 8 (Rolldown), which cannot resolve Nitro's `file:///D:/...` virtual modules on Windows, breaking `#nitro-internal-virtual/*` and causing every page to 500 (`Either manifest or precomputed data must be provided`). 4.4.8 → Vite 7 (Rollup) and matches Docus's official starter.
|
|
- **`pnpm 11` uses the `allowBuilds` map form** in `pnpm-workspace.yaml` — the v10 `onlyBuiltDependencies` array form is inert. `better-sqlite3` (Docus FTS5 search native module), `vue-demi`, and `esbuild` must stay allowed.
|
|
- `vue` and `typescript` versions are centralized in the workspace `catalog:`; each package references `"vue": "catalog:"` to avoid version drift.
|