Danijel Martinek
0e6bbbf8b7
The docs/scaffolding/ directory held two how-to guides (core-package
+ core-ui-component generator references). Both are operationally
identical in shape to docs/guides/scaffolding-a-feature.md — they
just live in a separate top-level docs directory. Consolidating
removes one directory + makes the three scaffolding guides
discoverable as siblings.
Moves (via git mv to preserve history):
docs/scaffolding/core-package-generator.md
-> docs/guides/scaffolding-core-package.md
docs/scaffolding/core-ui-component-generator.md
-> docs/guides/scaffolding-core-ui-component.md
Empty docs/scaffolding/ directory removed.
AGENTS.md (only consumer of the old paths) updated to point at the
new locations.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
63 lines
2.8 KiB
Markdown
63 lines
2.8 KiB
Markdown
# core-ui component generator
|
||
|
||
`pnpm turbo gen core-ui-component` scaffolds an atomic-design component (atom / molecule / organism) into `packages/core-ui/` using the established 4-file pattern.
|
||
|
||
**Prerequisite:** `packages/core-ui/` must exist. If your project started from the slim template, scaffold core-ui first via `pnpm turbo gen core-package ui`.
|
||
|
||
## Usage
|
||
|
||
```bash
|
||
pnpm turbo gen core-ui-component
|
||
# → Tier: (use arrow keys)
|
||
# ❯ atom
|
||
# molecule
|
||
# organism
|
||
# → Component name (PascalCase, e.g. Spinner):
|
||
# › Spinner
|
||
```
|
||
|
||
The generator emits 4 files into `packages/core-ui/src/<tier>s/<kebab-name>/`:
|
||
|
||
| File | Purpose |
|
||
| -------------------------- | ------------------------------------------------------------------------------------- |
|
||
| `<kebab-name>.tsx` | Component implementation (forwardRef + cn + className passthrough) |
|
||
| `<kebab-name>.stories.tsx` | Storybook stories (Meta + StoryObj + one Default story; tier-prefixed title) |
|
||
| `<kebab-name>.test.tsx` | Vitest + Testing Library smoke tests (renders, className passthrough, ref forwarding) |
|
||
| `index.ts` | Barrel that re-exports the component + Props type |
|
||
|
||
The new export is also spliced into `packages/core-ui/src/<tier>s/index.ts` immediately after the `// <gen:<tier>s>` anchor, so the component is reachable from the tier barrel (and transitively from the root `@repo/core-ui` export) without any manual wiring.
|
||
|
||
## Generated scaffold (example: `pnpm turbo gen core-ui-component` → atom → Spinner)
|
||
|
||
```
|
||
packages/core-ui/src/atoms/spinner/
|
||
├── spinner.tsx # forwardRef<HTMLDivElement, SpinnerProps>
|
||
├── spinner.stories.tsx # title: "Atoms/Spinner"
|
||
├── spinner.test.tsx # 3 smoke tests
|
||
└── index.ts # export { Spinner, type SpinnerProps }
|
||
```
|
||
|
||
And in `packages/core-ui/src/atoms/index.ts`:
|
||
|
||
```ts
|
||
// <gen:atoms>
|
||
export { Spinner, type SpinnerProps } from "./spinner/index";
|
||
export { Button, type ButtonProps } from "./button/index";
|
||
// ...
|
||
```
|
||
|
||
## Customizing the scaffold
|
||
|
||
The generated component is a minimal `<div>` passthrough — change the element/type and add variants/sizes to fit. The existing `button.tsx` in `src/atoms/button/` is the canonical reference for a richer component with `variant` and `size` props plus variant lookup tables.
|
||
|
||
## Verification
|
||
|
||
After scaffolding:
|
||
|
||
```bash
|
||
pnpm --filter @repo/core-ui lint typecheck test
|
||
pnpm dev --filter @repo/storybook # view the new component in Storybook
|
||
```
|
||
|
||
The Storybook stories glob (`packages/core-ui/src/**/*.stories.@(ts|tsx)`) picks up the new file automatically — no Storybook config changes needed.
|