/frontend-scaffolding

name: frontend-scaffolding
description: Scaffolds React/TypeScript frontend components with MVVM architecture.
user-invocable: false

Frontend Scaffolding Skill

Creates a React/TypeScript frontend component following the MVVM (Model-View-ViewModel) architecture with TanStack ecosystem.

When to Use

Use when creating webapp components. Supports multiple named instances (e.g., `webapp-admin`, `webapp-public`).

What It Creates

components/<webapp-name>/
├── .gitignore
├── components.json
├── eslint.config.js
├── eslint-rules/
│   └── allowed-structure.js
├── package.json
├── tsconfig.json
├── vite.config.ts
└── src/
    ├── index.html
    ├── index.ts
    ├── index.css
    ├── main.tsx              # Entry point
    ├── app.tsx               # Root app component
    ├── vite-env.d.ts
    ├── components/
    │   ├── index.ts
    │   ├── layout/
    │   │   ├── index.ts
    │   │   └── layout.tsx
    │   ├── sidebar/
    │   │   ├── index.ts
    │   │   └── sidebar.tsx
    │   └── ui/
    │       ├── index.ts
    │       ├── button.tsx
    │       └── card.tsx
    ├── hooks/
    │   ├── index.ts
    │   ├── use_app_config.tsx
    │   ├── use_app_router.ts
    │   └── use_query_client.ts
    ├── lib/
    │   ├── index.ts
    │   └── utils.ts
    ├── pages/
    │   ├── index.ts
    │   └── home_page/
    │       ├── index.ts
    │       └── home_page.tsx
    ├── routes/
    │   ├── index.ts
    │   └── routes.tsx
    ├── services/
    │   └── index.ts
    └── types/
        └── index.ts

MVVM Architecture

| Layer | Purpose | Location | |-------|---------|----------| | **V**iew | React components (pages, layout, UI primitives) | `src/pages/`, `src/components/` | | **V**iew**M**odel | State and logic hooks | `src/hooks/` | | **M**odel | API client services | `src/services/` | | Utilities | `cn()`, shared helpers | `src/lib/` | | Routes | TanStack Router route definitions | `src/routes/` | | Types | Shared type definitions | `src/types/` |

Tech Stack

| Technology | Purpose | |------------|---------| | React 19 | UI framework | | TypeScript 5.9 | Type safety | | Vite 7 | Build tool and dev server | | Vitest 4 | Unit testing framework | | ESLint 9 | Linting (flat config) | | Tailwind CSS 4 | Utility-first CSS (CSS-based config) | | TanStack Router | Type-safe routing | | TanStack Query | Server state management | | TanStack Table | Headless table primitives | | TanStack Form | Type-safe form management | | Radix UI / Shadcn | Accessible component primitives | | class-variance-authority, clsx, tailwind-merge | Style composition utilities |

Multiple Instances

Supports multiple named frontend instances:

| Input | Directory Created | |-------|-------------------| | `{type: webapp, name: main}` | `components/webapps/main/` | | `{type: webapp, name: admin}` | `components/webapps/admin/` | | `{type: webapp, name: public}` | `components/webapps/public/` |

Template Variables

| Variable | Description | |----------|-------------| | `{{PROJECT_NAME}}` | Project name | | `{{CONTRACT_PACKAGE}}` | Workspace package name for API contract types (e.g., `@my-project/api-types`) | | `{{CONFIG_PACKAGE}}` | Workspace package name for webapp configuration types (e.g., `@my-project/config`) |

Usage

Called programmatically by the scaffolding script:

import { scaffoldFrontend } from './frontend-scaffolding';

scaffoldFrontend({
  targetDir: '/path/to/project',
  componentName: 'admin',         // Creates webapp-admin/
  projectName: 'my-app',
});

Templates Location

All templates are colocated in this skill's `templates/` directory:

skills/components/frontend/frontend-scaffolding/templates/
├── .gitignore
├── components.json
├── eslint.config.js
├── eslint-rules/
│   └── allowed-structure.js
├── package.json
├── tsconfig.json
├── vite.config.ts
└── src/
    ├── index.html
    ├── index.ts
    ├── index.css
    ├── main.tsx
    ├── app.tsx
    ├── vite-env.d.ts
    ├── components/
    │   ├── index.ts
    │   ├── layout/
    │   ├── sidebar/
    │   └── ui/
    ├── hooks/
    ├── lib/
    ├── pages/
    ├── routes/
    ├── services/
    └── types/

Config Schema

When scaffolding a webapp component, the following config section is added to `components/config/`:

Minimal Config (envs/default/config.yaml)

webapp-{name}:
  apiBaseUrl: /api

TypeScript Type (types/webapp.ts)

export type WebappConfig = Readonly<{
  apiBaseUrl: string;
}>;

JSON Schema (schemas/config.schema.json)

{
  "webapp-{name}": {
    "type": "object",
    "properties": {
      "apiBaseUrl": { "type": "string", "default": "/api" }
    },
    "required": ["apiBaseUrl"]
  }
}

Optional Extensions

Features may extend the config as needed:

webapp-{name}:
  apiBaseUrl: /api
  features:
    darkMode: true
    analytics: false

---

Scaffold Spec

To scaffold a frontend component, build a spec and invoke the engine:

<plugin-root>/fullstack-typescript/system/system-run.sh scaffolding apply --spec spec.json

Variables

| Variable | Source | |----------|--------| | `PROJECT_NAME` | From `sdd-settings.yaml` project name | | `CONTRACT_PACKAGE` | Workspace package name for API contract types | | `CONFIG_PACKAGE` | Workspace package name for webapp configuration types |

Operations

{
  "target_dir": "<project-root>",
  "base_dir": "<plugin-root>/skills",
  "variables": { "PROJECT_NAME": "<project-name>", "CONTRACT_PACKAGE": "<contract-package>", "CONFIG_PACKAGE": "<config-package>" },
  "operations": [
    {
      "type": "template_dir",
      "source": "components/frontend/frontend-scaffolding/templates",
      "dest": "components/webapps/<webapp-name>"
    },
    {
      "type": "package_json_scripts",
      "scripts": {
        "<webapp-name>:dev": "npm run dev -w @<project-name>/<webapp-name>",
        "<webapp-name>:build": "npm run build -w @<project-name>/<webapp-nam