playbooks

home / skills / levnikolaevich / claude-code-skills / ln-721-frontend-restructure

ln-721-frontend-restructure skill

/ln-721-frontend-restructure

This skill scaffolds new React projects or restructures monoliths into component-based architectures, accelerating frontend modernization.

npx playbooks add skill levnikolaevich/claude-code-skills --skill ln-721-frontend-restructure

Review the files below or copy the command above to add this skill to your agents.

Files (6)
SKILL.md
8.0 KB
---
name: ln-721-frontend-restructure
description: "Frontend structure worker: SCAFFOLD new React project or RESTRUCTURE existing monolith to component-based architecture"
---

> **Paths:** File paths (`shared/`, `references/`, `../ln-*`) are relative to skills repo root. If not found at CWD, locate this SKILL.md directory and go up one level for repo root.

# ln-721-frontend-restructure

**Type:** L3 Worker
**Category:** 7XX Project Bootstrap
**Parent:** ln-720-structure-migrator

Frontend structure worker with two modes: SCAFFOLD (generate minimal React project from template) or RESTRUCTURE (migrate monolith to component-based architecture).

---

## Mode Selection

| Mode | When | Input | Output |
|------|------|-------|--------|
| **SCAFFOLD** | CREATE pipeline — no existing frontend | Target stack config from ln-720 | Minimal React + Vite project (~7 files) |
| **RESTRUCTURE** | TRANSFORM pipeline — existing frontend found | Monolithic React source | Component-based architecture |

---

## Purpose & Scope

| Aspect | Description |
|--------|-------------|
| **Input** | Target stack config (SCAFFOLD) or monolithic React source (RESTRUCTURE) |
| **Output** | Minimal project (SCAFFOLD) or component-based architecture (RESTRUCTURE) |
| **Framework** | React + TypeScript + Vite |

**Scope boundaries:**
- SCAFFOLD: generates minimal starter files, no business logic
- RESTRUCTURE: restructures existing code, does not add new functionality
- Works with React + TypeScript projects
- Applies transformation rules from reference files

---

## Workflow

### SCAFFOLD Mode (CREATE pipeline)

| Phase | Name | Actions | Output |
|-------|------|---------|--------|
| S1 | Generate | Create minimal React + Vite + TypeScript project files | ~7 starter files |
| S2 | Verify | Check file structure, validate configs | Valid project skeleton |

### RESTRUCTURE Mode (TRANSFORM pipeline)

| Phase | Name | Actions | Output |
|-------|------|---------|--------|
| 1 | Analyze | Scan source, detect component types, measure complexity | File inventory, complexity metrics |
| 2 | Plan | Apply split thresholds, calculate file moves, detect conflicts | Migration plan |
| 3 | Execute | Create folders, extract content, update imports | Restructured files |
| 4 | Verify | Run build, check imports, validate structure | Build success report |

---

## SCAFFOLD Mode Phases

### Phase S1: Generate Starter Files

Create minimal React + Vite + TypeScript project.

| File | Purpose |
|------|---------|
| `package.json` | Dependencies: react, react-dom, typescript, vite, @vitejs/plugin-react |
| `vite.config.ts` | Vite config with React plugin, port, proxy settings |
| `tsconfig.json` | Strict TypeScript config with path aliases |
| `index.html` | Entry HTML with root div |
| `src/main.tsx` | React entry point with StrictMode |
| `src/App.tsx` | Root App component with router placeholder |
| `src/index.css` | Base styles (reset, variables, layout) |

### Phase S2: Verify Scaffold

| Check | Method | Expected |
|-------|--------|----------|
| All files created | File existence check | 7 files present |
| package.json valid | JSON parse | No syntax errors |
| tsconfig.json valid | JSON parse | No syntax errors |
| No hardcoded values | Content scan | Project name from config, not hardcoded |

---

## RESTRUCTURE Mode Phases

### Phase 1: Analyze

Scan current frontend structure and classify components.

| Step | Action | Reference |
|------|--------|-----------|
| 1.1 | Scan all `.tsx` and `.ts` files in source | — |
| 1.2 | Measure file complexity (lines, hooks, types) | `transformation_rules.md` |
| 1.3 | Classify components by category | `component_patterns.md` |
| 1.4 | Build import dependency graph | `import_strategy.md` |

**Output:** Component inventory with classifications and metrics.

---

### Phase 2: Plan

Generate migration plan based on analysis.

| Step | Action | Reference |
|------|--------|-----------|
| 2.1 | Apply split thresholds to identify files to restructure | `transformation_rules.md` |
| 2.2 | Calculate target paths for each file | `react_folder_structure.md` |
| 2.3 | Identify import updates needed | `import_strategy.md` |
| 2.4 | Detect potential conflicts (name collisions, circular deps) | — |

**Output:** Migration plan with Before/After mapping.

---

### Phase 3: Execute

Apply transformations in correct order.

| Step | Action | Notes |
|------|--------|-------|
| 3.1 | Create directory structure | All target folders |
| 3.2 | Extract types to `types.ts` | Types have no dependencies |
| 3.3 | Extract constants to `constants.ts` | Constants depend only on types |
| 3.4 | Extract hooks to `hooks.ts` | Hooks depend on types, constants |
| 3.5 | Extract sub-components | Components use all above |
| 3.6 | Create barrel exports (`index.ts`) | For clean imports |
| 3.7 | Update all import paths | Fix references |

**Order is critical:** Execute in sequence to avoid broken imports.

---

### Phase 4: Verify

Validate restructured project.

| Check | Command | Expected |
|-------|---------|----------|
| TypeScript compilation | `npx tsc --noEmit` | No errors |
| Build | `npm run build` | Success |
| No orphan files | Manual check | Source location empty |
| Imports resolve | Build success | No module not found errors |

---

## Transformation Summary

| Transformation | Before State | After State |
|----------------|--------------|-------------|
| Component Split | Single file >300 lines | Feature folder with co-located files |
| Type Extraction | Inline interfaces | Separate `types.ts` |
| Constant Extraction | Inline magic values | Separate `constants.ts` |
| Hook Extraction | Inline useState/useEffect | Separate `hooks.ts` or shared hooks |
| UI Component Move | Scattered in features | Centralized in `components/ui/` |
| Layout Component Move | Mixed with features | Centralized in `components/layout/` |

---

## Critical Rules

- **Mode Awareness:** SCAFFOLD creates from template; RESTRUCTURE transforms existing — never mix
- **Single Responsibility:** Handle only frontend structure, no backend changes
- **Idempotent:** Can re-run without duplicate files or corruption
- **Build Verification:** Must verify build passes after changes (RESTRUCTURE: `npm run build`)
- **Preserve Functionality:** No behavioral changes, only structural (RESTRUCTURE mode)
- **Backup Strategy:** Do not delete source files until verification passes (RESTRUCTURE mode)
- **Import Consistency:** Use path aliases for shared, relative for co-located

---

## Definition of Done

**SCAFFOLD mode:**
- [ ] All 7 starter files generated
- [ ] package.json and tsconfig.json valid
- [ ] No hardcoded project names (uses config values)

**RESTRUCTURE mode:**
- [ ] All source files analyzed and classified
- [ ] Migration plan generated with Before/After mapping
- [ ] Directory structure created per template
- [ ] All extractions completed (types, constants, hooks, components)
- [ ] Import paths updated throughout project
- [ ] `npm run build` passes successfully
- [ ] No orphan imports or missing files
- [ ] Barrel exports created for shared folders

---

## Risk Mitigation

| Risk | Detection | Mitigation |
|------|-----------|------------|
| Build failure after restructure | `npm run build` fails | Rollback: restore from source, investigate specific error |
| Missing imports | Module not found errors | Scan all imports before/after, update missed paths |
| Circular dependencies | Build warning or runtime error | Analyze dependency graph, break cycles by extracting shared code |
| Lost functionality | Tests fail or UI broken | Run existing tests before/after transformation |
| Name collisions | Duplicate export names | Rename with feature prefix before moving |

---

## Reference Files

| File | Purpose |
|------|---------|
| `references/transformation_rules.md` | Split thresholds, extraction rules, transformation order |
| `references/component_patterns.md` | Component classification by category |
| `references/import_strategy.md` | Import update rules, path aliases, barrel exports |
| `references/react_folder_structure.md` | Target directory structure template |

---

**Version:** 3.0.0
**Last Updated:** 2026-02-07

Overview

This skill bootstraps or reorganizes React frontends. It offers two modes: SCAFFOLD to generate a minimal React + TypeScript + Vite starter, and RESTRUCTURE to convert a monolithic React codebase into a component-based architecture while preserving behavior.

How this skill works

In SCAFFOLD mode the skill writes a seven-file starter (package.json, vite.config.ts, tsconfig.json, index.html, src/main.tsx, src/App.tsx, src/index.css) using provided stack configuration and then verifies file presence and config validity. In RESTRUCTURE mode it analyzes .ts/.tsx sources, builds an import graph, generates a migration plan, executes ordered extractions (types, constants, hooks, components), updates imports and barrel exports, then verifies build and type checks.

When to use it

  • Starting a new React + TypeScript project and you need a minimal, production-ready skeleton.
  • Migrating a large monolithic React app into feature folders and co-located assets.
  • Automating structural refactors that extract types, constants, hooks and subcomponents.
  • Preparing a codebase for better reuse, path-alias consistency, and cleaner imports.
  • When you require an idempotent tool that verifies builds before removing originals.

Best practices

  • Run the skill in the appropriate pipeline: CREATE for SCAFFOLD, TRANSFORM for RESTRUCTURE — do not mix modes.
  • Back up or branch the repository before executing RESTRUCTURE and keep originals until verification passes.
  • Run existing tests and a full TypeScript compile prior to and after transformation.
  • Follow the prescribed execution order (types → constants → hooks → components → barrels) to avoid broken imports.
  • Use path aliases for shared folders and relative imports for co-located files to maintain import consistency.

Example use cases

  • Generate a lean Vite + React + TypeScript starter for a micro-frontend or PoC.
  • Split a 400+ line component into a feature folder with types.ts, constants.ts, hooks.ts and subcomponents.
  • Standardize UI and layout components into components/ui and components/layout with barrel exports.
  • Resolve circular dependencies by extracting shared types or hooks into separate files.
  • Automate a migration plan that maps Before→After paths and then executes safe, verified moves.

FAQ

Will RESTRUCTURE change application behavior?

No. The skill is designed to preserve functionality; it only moves and extracts code. Verification includes TypeScript checks and a build to detect regressions.

Can I re-run the skill multiple times?

Yes. The process is idempotent: it avoids duplicating files and can be safely re-run after verification or incremental changes.