fecode-cli 1.1.3 → 1.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (98) hide show
  1. package/README.md +92 -8
  2. package/dist/index.js +23293 -1
  3. package/dist/{node.browser-BsGbhAIw.js → node.browser-2EgZAKSy.js} +1 -1
  4. package/dist/{node.browser-B5CfqNxN.js → node.browser-B5Gur0wd.js} +1 -1
  5. package/dist/{node.browser-BWLpZywP.js → node.browser-BSlAsiSV.js} +1 -1
  6. package/dist/{node.browser-7pW7d9_e.js → node.browser-CdVAMgSg.js} +1 -1
  7. package/dist/{src-CxriUNOE.js → src-CSWdjU4j.js} +4836 -4522
  8. package/dist/{src-DBoGZaxi.js → src-DY3OmBmT.js} +6670 -4557
  9. package/dist/{src-B_Z8CdqT.js → src-DcYf8vsK.js} +4850 -4526
  10. package/dist/{src-Bhec3XmL.js → src-DkWmcv2Q.js} +6677 -4604
  11. package/package.json +5 -2
  12. package/skills/accessibility/SKILL.md +98 -98
  13. package/skills/css/SKILL.md +90 -90
  14. package/skills/frontend-debugging/SKILL.md +201 -201
  15. package/skills/frontend-design/SKILL.md +358 -358
  16. package/skills/frontend-performance/SKILL.md +89 -89
  17. package/skills/frontend-testing/SKILL.md +87 -87
  18. package/skills/nextjs/SKILL.md +75 -75
  19. package/skills/react/SKILL.md +213 -213
  20. package/skills/responsive-design/SKILL.md +190 -190
  21. package/skills/svelte/SKILL.md +86 -86
  22. package/skills/tailwind/SKILL.md +74 -74
  23. package/skills/ui-review/SKILL.md +245 -245
  24. package/skills/vue/SKILL.md +72 -72
  25. package/dist/App.d.ts +0 -33
  26. package/dist/App.js +0 -2224
  27. package/dist/approvalResolver.d.ts +0 -12
  28. package/dist/approvalResolver.js +0 -112
  29. package/dist/commands.d.ts +0 -11
  30. package/dist/commands.js +0 -33
  31. package/dist/error-qAR8Lv-R.js +0 -57
  32. package/dist/index.d.ts +0 -3
  33. package/dist/node.browser-C9Wg-Fje.js +0 -46
  34. package/dist/node.browser-CADgAblr.js +0 -46
  35. package/dist/node.browser-Cse19Rko.js +0 -47
  36. package/dist/node.browser-Cx8sZi1Z.js +0 -46
  37. package/dist/node.browser-DtPNhPGQ.js +0 -46
  38. package/dist/node.browser-DvjMZMaq.js +0 -46
  39. package/dist/node.browser-EewJmuUw.js +0 -46
  40. package/dist/node.browser-J7voHtuR.js +0 -10
  41. package/dist/src-4fKRO0jn.js +0 -31655
  42. package/dist/src-8kA-5Kbs.js +0 -31591
  43. package/dist/src-C8Oe06wn.js +0 -31580
  44. package/dist/src-D78uLcuc.js +0 -31573
  45. package/dist/src-EyWDnffN.js +0 -31636
  46. package/dist/src-dhvwrHAJ.js +0 -31590
  47. package/dist/ui/AppShell.d.ts +0 -14
  48. package/dist/ui/AppShell.js +0 -25
  49. package/dist/ui/ApprovalPrompt.d.ts +0 -31
  50. package/dist/ui/ApprovalPrompt.js +0 -55
  51. package/dist/ui/BlockedView.d.ts +0 -13
  52. package/dist/ui/BlockedView.js +0 -7
  53. package/dist/ui/CommandPalette.d.ts +0 -8
  54. package/dist/ui/CommandPalette.js +0 -18
  55. package/dist/ui/CurrentStepView.d.ts +0 -16
  56. package/dist/ui/CurrentStepView.js +0 -28
  57. package/dist/ui/DiagnosticsView.d.ts +0 -45
  58. package/dist/ui/DiagnosticsView.js +0 -23
  59. package/dist/ui/ExecutionTimeline.d.ts +0 -15
  60. package/dist/ui/ExecutionTimeline.js +0 -51
  61. package/dist/ui/ExecutionView.d.ts +0 -42
  62. package/dist/ui/ExecutionView.js +0 -20
  63. package/dist/ui/Header.d.ts +0 -15
  64. package/dist/ui/Header.js +0 -47
  65. package/dist/ui/HelpView.d.ts +0 -3
  66. package/dist/ui/HelpView.js +0 -35
  67. package/dist/ui/MessageBubble.d.ts +0 -9
  68. package/dist/ui/MessageBubble.js +0 -58
  69. package/dist/ui/PlanStep.d.ts +0 -16
  70. package/dist/ui/PlanStep.js +0 -71
  71. package/dist/ui/PlanView.d.ts +0 -26
  72. package/dist/ui/PlanView.js +0 -24
  73. package/dist/ui/ProgressBar.d.ts +0 -10
  74. package/dist/ui/ProgressBar.js +0 -14
  75. package/dist/ui/RecoveryView.d.ts +0 -20
  76. package/dist/ui/RecoveryView.js +0 -19
  77. package/dist/ui/ReplanView.d.ts +0 -16
  78. package/dist/ui/ReplanView.js +0 -21
  79. package/dist/ui/ResumeView.d.ts +0 -15
  80. package/dist/ui/ResumeView.js +0 -25
  81. package/dist/ui/RiskNotice.d.ts +0 -10
  82. package/dist/ui/RiskNotice.js +0 -21
  83. package/dist/ui/RunHistoryView.d.ts +0 -15
  84. package/dist/ui/RunHistoryView.js +0 -39
  85. package/dist/ui/StatusBar.d.ts +0 -16
  86. package/dist/ui/StatusBar.js +0 -104
  87. package/dist/ui/TaskInput.d.ts +0 -15
  88. package/dist/ui/TaskInput.js +0 -8
  89. package/dist/ui/ThinkingBlock.d.ts +0 -8
  90. package/dist/ui/ThinkingBlock.js +0 -13
  91. package/dist/ui/ThinkingIndicator.d.ts +0 -7
  92. package/dist/ui/ThinkingIndicator.js +0 -20
  93. package/dist/ui/TurnView.d.ts +0 -13
  94. package/dist/ui/TurnView.js +0 -11
  95. package/dist/ui/WorkspaceStatus.d.ts +0 -20
  96. package/dist/ui/WorkspaceStatus.js +0 -23
  97. package/dist/ui/index.d.ts +0 -26
  98. package/dist/ui/index.js +0 -26
@@ -1,89 +1,89 @@
1
- ---
2
- name: frontend-performance
3
- description: Performance optimization, bottleneck diagnosis, and core web vitals.
4
- category: frontend
5
- version: 2.1.0
6
- ---
7
-
8
- ## When to use
9
-
10
- - diagnosing slow performance
11
- - optimizing loading times
12
- - fixing jank or slow interactions
13
-
14
- ## Instructions
15
-
16
- ### Project Detection & Existing Rules
17
- - **Inspect first**: Check `package.json`, build configuration, and existing performance tooling (like Lighthouse CI or bundle analyzers).
18
- - **Respect existing architecture**: Do not introduce new dependencies or rewrite build tools unless required.
19
-
20
- ### Core Mental Model
21
- - Performance is about user-visible outcomes such as loading, responsiveness, interaction latency, rendering, network, and memory.
22
- - Optimization follows: MEASURE → IDENTIFY → CHANGE → VERIFY.
23
- - Do not optimize hypothetical problems.
24
-
25
- ## Rules
26
-
27
- ### Diagnosis & Optimization Process
28
- Before optimizing:
29
- 1. Identify the symptom.
30
- 2. Measure or inspect evidence.
31
- 3. Locate the bottleneck.
32
- 4. Make the smallest meaningful change.
33
- 5. Verify the improvement.
34
-
35
- ### Loading Performance
36
- - **Bundle Size**: Monitor the impact of new dependencies.
37
- - **Code Splitting**: Split code by route or large feature to reduce initial payload.
38
- - **Lazy Loading**: Use lazy loading for offscreen or low-priority components. Do not blindly lazy-load above-the-fold content.
39
- - **Caching**: Ensure static assets are cacheable.
40
-
41
- ### Runtime Performance
42
- - **Unnecessary Work**: Avoid running expensive calculations on every render.
43
- - **Large Lists**: Use virtualization or pagination for massive lists.
44
- - **Layout Thrashing**: Avoid interleaving DOM reads and writes in the same synchronous frame.
45
- - **Event Handlers**: Debounce or throttle high-frequency events (like scroll or resize).
46
-
47
- ### Images
48
- - Specify dimensions (`width` and `height`) to prevent layout shifts.
49
- - Use responsive images (`srcset`, `sizes`).
50
- - Use modern formats (`WebP`, `AVIF`) where appropriate.
51
- - Lazy-load below-the-fold images (`loading="lazy"`).
52
-
53
- ### Fonts
54
- - Limit the number of font files and weights.
55
- - Use `font-display: swap` for better perceived loading.
56
- - Subsetting fonts can drastically reduce file size.
57
-
58
- ### JavaScript
59
- - Avoid unnecessary client-side JavaScript.
60
- - Audit large client-side libraries and prefer lighter alternatives when permitted.
61
-
62
- ### Rendering
63
- - Prevent unnecessary rerenders (framework-neutral principle).
64
- - Minimize expensive DOM updates and long tasks that block the main thread.
65
-
66
- ## Anti-Patterns
67
-
68
- - **Optimizing without measurement**
69
- - *What*: Applying "performance hacks" blindly across the codebase.
70
- - *Why*: It complicates the code without guaranteeing any actual user benefit, and often introduces bugs.
71
- - *Instead*: Measure first, locate the bottleneck, then optimize.
72
- - **Lazy-loading everything**
73
- - *What*: Lazy-loading above-the-fold hero images or the main routing shell.
74
- - *Why*: It delays the loading of critical content, worsening the Largest Contentful Paint (LCP).
75
- - *Instead*: Eagerly load critical assets and only lazy-load what is offscreen.
76
- - **Excessive memoization**
77
- - *What*: Wrapping every single function in memoization hooks.
78
- - *Why*: Memoization costs memory and execution time. If the function is cheap, the overhead of memoizing it is worse than recalculating it.
79
- - *Instead*: Only memoize demonstrably expensive calculations or stable props passed to pure child components.
80
-
81
- ## Workflow
82
-
83
- ### Debugging
84
- - Check network tabs for excessive payload sizes or waterfall blocking.
85
- - Check profiling tools for long tasks or layout thrashing.
86
-
87
- ### Verification
88
- - Use actual project tooling when available (e.g., build output, bundle analysis, profiling, Lighthouse, browser performance tools).
89
- - **Never claim a performance improvement without evidence.** Verify via build sizes or test run metrics.
1
+ ---
2
+ name: frontend-performance
3
+ description: Performance optimization, bottleneck diagnosis, and core web vitals.
4
+ category: frontend
5
+ version: 2.1.0
6
+ ---
7
+
8
+ ## When to use
9
+
10
+ - diagnosing slow performance
11
+ - optimizing loading times
12
+ - fixing jank or slow interactions
13
+
14
+ ## Instructions
15
+
16
+ ### Project Detection & Existing Rules
17
+ - **Inspect first**: Check `package.json`, build configuration, and existing performance tooling (like Lighthouse CI or bundle analyzers).
18
+ - **Respect existing architecture**: Do not introduce new dependencies or rewrite build tools unless required.
19
+
20
+ ### Core Mental Model
21
+ - Performance is about user-visible outcomes such as loading, responsiveness, interaction latency, rendering, network, and memory.
22
+ - Optimization follows: MEASURE → IDENTIFY → CHANGE → VERIFY.
23
+ - Do not optimize hypothetical problems.
24
+
25
+ ## Rules
26
+
27
+ ### Diagnosis & Optimization Process
28
+ Before optimizing:
29
+ 1. Identify the symptom.
30
+ 2. Measure or inspect evidence.
31
+ 3. Locate the bottleneck.
32
+ 4. Make the smallest meaningful change.
33
+ 5. Verify the improvement.
34
+
35
+ ### Loading Performance
36
+ - **Bundle Size**: Monitor the impact of new dependencies.
37
+ - **Code Splitting**: Split code by route or large feature to reduce initial payload.
38
+ - **Lazy Loading**: Use lazy loading for offscreen or low-priority components. Do not blindly lazy-load above-the-fold content.
39
+ - **Caching**: Ensure static assets are cacheable.
40
+
41
+ ### Runtime Performance
42
+ - **Unnecessary Work**: Avoid running expensive calculations on every render.
43
+ - **Large Lists**: Use virtualization or pagination for massive lists.
44
+ - **Layout Thrashing**: Avoid interleaving DOM reads and writes in the same synchronous frame.
45
+ - **Event Handlers**: Debounce or throttle high-frequency events (like scroll or resize).
46
+
47
+ ### Images
48
+ - Specify dimensions (`width` and `height`) to prevent layout shifts.
49
+ - Use responsive images (`srcset`, `sizes`).
50
+ - Use modern formats (`WebP`, `AVIF`) where appropriate.
51
+ - Lazy-load below-the-fold images (`loading="lazy"`).
52
+
53
+ ### Fonts
54
+ - Limit the number of font files and weights.
55
+ - Use `font-display: swap` for better perceived loading.
56
+ - Subsetting fonts can drastically reduce file size.
57
+
58
+ ### JavaScript
59
+ - Avoid unnecessary client-side JavaScript.
60
+ - Audit large client-side libraries and prefer lighter alternatives when permitted.
61
+
62
+ ### Rendering
63
+ - Prevent unnecessary rerenders (framework-neutral principle).
64
+ - Minimize expensive DOM updates and long tasks that block the main thread.
65
+
66
+ ## Anti-Patterns
67
+
68
+ - **Optimizing without measurement**
69
+ - *What*: Applying "performance hacks" blindly across the codebase.
70
+ - *Why*: It complicates the code without guaranteeing any actual user benefit, and often introduces bugs.
71
+ - *Instead*: Measure first, locate the bottleneck, then optimize.
72
+ - **Lazy-loading everything**
73
+ - *What*: Lazy-loading above-the-fold hero images or the main routing shell.
74
+ - *Why*: It delays the loading of critical content, worsening the Largest Contentful Paint (LCP).
75
+ - *Instead*: Eagerly load critical assets and only lazy-load what is offscreen.
76
+ - **Excessive memoization**
77
+ - *What*: Wrapping every single function in memoization hooks.
78
+ - *Why*: Memoization costs memory and execution time. If the function is cheap, the overhead of memoizing it is worse than recalculating it.
79
+ - *Instead*: Only memoize demonstrably expensive calculations or stable props passed to pure child components.
80
+
81
+ ## Workflow
82
+
83
+ ### Debugging
84
+ - Check network tabs for excessive payload sizes or waterfall blocking.
85
+ - Check profiling tools for long tasks or layout thrashing.
86
+
87
+ ### Verification
88
+ - Use actual project tooling when available (e.g., build output, bundle analysis, profiling, Lighthouse, browser performance tools).
89
+ - **Never claim a performance improvement without evidence.** Verify via build sizes or test run metrics.
@@ -1,87 +1,87 @@
1
- ---
2
- name: frontend-testing
3
- description: Frontend testing strategy, component tests, integration tests, and behavioral assertions.
4
- category: testing
5
- version: 2.1.0
6
- ---
7
-
8
- ## When to use
9
-
10
- - writing frontend tests
11
- - fixing failing tests
12
- - implementing testing strategy
13
-
14
- ## Instructions
15
-
16
- ### Project Detection & Existing Rules
17
- - **Inspect package.json & Configuration**: Check existing test scripts, testing libraries (Jest, Vitest, Cypress, Playwright, React Testing Library), and conventions.
18
- - **Follow existing patterns**: Do not introduce another testing framework when one already exists.
19
-
20
- ### Core Mental Model
21
- - Tests should provide confidence about behavior.
22
- - Prefer testing what the user/system observes over testing internal implementation details.
23
-
24
- ## Rules
25
-
26
- ### Testing Layers
27
- - **Unit Tests**: Good for pure functions, utilities, and complex logic isolation.
28
- - **Component Tests**: Good for verifying UI state, props, and user interaction.
29
- - **Integration/E2E Tests**: Good for verifying that the entire system coordinates correctly.
30
- - Do not insist every project needs every layer. Match the project's strategy.
31
-
32
- ### What to Test
33
- Prioritize:
34
- - important user behavior (submitting a form, navigating)
35
- - business logic
36
- - regressions
37
- - edge cases, error states, and loading states
38
-
39
- ### What Not to Test
40
- Avoid tests that only verify:
41
- - internal implementation details (e.g. checking if a specific internal variable is set to true)
42
- - trivial framework behavior (e.g. testing that a React component renders a div)
43
- - exact DOM structure without behavioral significance
44
-
45
- ### Mocking
46
- Before mocking:
47
- - Ask whether the real dependency can safely be used (e.g., testing against the real DOM or an in-memory database).
48
- - Avoid excessive mocking that makes tests pass while hiding genuine integration bugs.
49
-
50
- ### Async UI
51
- Test loading, success, error, retry, and empty states.
52
- - **Do not assert immediately** before asynchronous behavior completes. Use asynchronous finders (`findBy`, `waitFor`).
53
-
54
- ### Forms
55
- Test valid submission, invalid input, validation errors, disabled/loading states, and submission failure.
56
-
57
- ### Accessibility
58
- Where appropriate, include accessible queries (e.g., `getByRole`) and basic accessibility verification to implicitly test a11y alongside behavior.
59
-
60
- ## Anti-Patterns
61
-
62
- - **Brittle selectors**
63
- - *What*: Querying elements by CSS classes (e.g., `.btn-primary-wrapper > div`).
64
- - *Why*: Any minor styling or DOM structure change breaks the test, even if the user behavior is intact.
65
- - *Instead*: Query by accessible roles, labels, or explicit test IDs (`getByRole('button', { name: /submit/i })`).
66
- - **Testing implementation details**
67
- - *What*: Asserting that a component called `setState(true)` internally.
68
- - *Why*: Refactoring the component (e.g., to use `useReducer`) breaks the test even if the UI still works perfectly.
69
- - *Instead*: Assert on the visible UI changes (e.g., expecting a loading spinner to appear).
70
- - **Excessive mocking**
71
- - *What*: Mocking every child component in a tree.
72
- - *Why*: The test passes, but the application might crash in production because the components don't actually integrate correctly.
73
- - *Instead*: Use shallow rendering sparingly. Render the real components unless they trigger expensive or un-mockable side effects.
74
-
75
- ## Workflow
76
-
77
- ### Debugging
78
- When a test fails:
79
- 1. Understand the failure.
80
- 2. Determine whether the application behavior or the test assumptions are wrong.
81
- 3. Inspect relevant code and reproduce the failure.
82
- 4. Make the smallest appropriate fix.
83
- 5. Do not modify tests merely to make failures disappear.
84
-
85
- ### Verification
86
- - Run targeted tests during iteration to get fast feedback.
87
- - Run the broader suite (the project's actual test command) before completion.
1
+ ---
2
+ name: frontend-testing
3
+ description: Frontend testing strategy, component tests, integration tests, and behavioral assertions.
4
+ category: testing
5
+ version: 2.1.0
6
+ ---
7
+
8
+ ## When to use
9
+
10
+ - writing frontend tests
11
+ - fixing failing tests
12
+ - implementing testing strategy
13
+
14
+ ## Instructions
15
+
16
+ ### Project Detection & Existing Rules
17
+ - **Inspect package.json & Configuration**: Check existing test scripts, testing libraries (Jest, Vitest, Cypress, Playwright, React Testing Library), and conventions.
18
+ - **Follow existing patterns**: Do not introduce another testing framework when one already exists.
19
+
20
+ ### Core Mental Model
21
+ - Tests should provide confidence about behavior.
22
+ - Prefer testing what the user/system observes over testing internal implementation details.
23
+
24
+ ## Rules
25
+
26
+ ### Testing Layers
27
+ - **Unit Tests**: Good for pure functions, utilities, and complex logic isolation.
28
+ - **Component Tests**: Good for verifying UI state, props, and user interaction.
29
+ - **Integration/E2E Tests**: Good for verifying that the entire system coordinates correctly.
30
+ - Do not insist every project needs every layer. Match the project's strategy.
31
+
32
+ ### What to Test
33
+ Prioritize:
34
+ - important user behavior (submitting a form, navigating)
35
+ - business logic
36
+ - regressions
37
+ - edge cases, error states, and loading states
38
+
39
+ ### What Not to Test
40
+ Avoid tests that only verify:
41
+ - internal implementation details (e.g. checking if a specific internal variable is set to true)
42
+ - trivial framework behavior (e.g. testing that a React component renders a div)
43
+ - exact DOM structure without behavioral significance
44
+
45
+ ### Mocking
46
+ Before mocking:
47
+ - Ask whether the real dependency can safely be used (e.g., testing against the real DOM or an in-memory database).
48
+ - Avoid excessive mocking that makes tests pass while hiding genuine integration bugs.
49
+
50
+ ### Async UI
51
+ Test loading, success, error, retry, and empty states.
52
+ - **Do not assert immediately** before asynchronous behavior completes. Use asynchronous finders (`findBy`, `waitFor`).
53
+
54
+ ### Forms
55
+ Test valid submission, invalid input, validation errors, disabled/loading states, and submission failure.
56
+
57
+ ### Accessibility
58
+ Where appropriate, include accessible queries (e.g., `getByRole`) and basic accessibility verification to implicitly test a11y alongside behavior.
59
+
60
+ ## Anti-Patterns
61
+
62
+ - **Brittle selectors**
63
+ - *What*: Querying elements by CSS classes (e.g., `.btn-primary-wrapper > div`).
64
+ - *Why*: Any minor styling or DOM structure change breaks the test, even if the user behavior is intact.
65
+ - *Instead*: Query by accessible roles, labels, or explicit test IDs (`getByRole('button', { name: /submit/i })`).
66
+ - **Testing implementation details**
67
+ - *What*: Asserting that a component called `setState(true)` internally.
68
+ - *Why*: Refactoring the component (e.g., to use `useReducer`) breaks the test even if the UI still works perfectly.
69
+ - *Instead*: Assert on the visible UI changes (e.g., expecting a loading spinner to appear).
70
+ - **Excessive mocking**
71
+ - *What*: Mocking every child component in a tree.
72
+ - *Why*: The test passes, but the application might crash in production because the components don't actually integrate correctly.
73
+ - *Instead*: Use shallow rendering sparingly. Render the real components unless they trigger expensive or un-mockable side effects.
74
+
75
+ ## Workflow
76
+
77
+ ### Debugging
78
+ When a test fails:
79
+ 1. Understand the failure.
80
+ 2. Determine whether the application behavior or the test assumptions are wrong.
81
+ 3. Inspect relevant code and reproduce the failure.
82
+ 4. Make the smallest appropriate fix.
83
+ 5. Do not modify tests merely to make failures disappear.
84
+
85
+ ### Verification
86
+ - Run targeted tests during iteration to get fast feedback.
87
+ - Run the broader suite (the project's actual test command) before completion.
@@ -1,75 +1,75 @@
1
- ---
2
- name: nextjs
3
- description: Next.js App Router, Pages Router, Server/Client components, routing, and data fetching.
4
- category: framework
5
- version: 2.1.0
6
- ---
7
-
8
- ## When to use
9
-
10
- - building Next.js pages or components
11
- - authoring Server/Client components
12
- - Next.js routing and data fetching
13
- - Next.js API routes
14
-
15
- ## Instructions
16
-
17
- ### Project Detection & Existing Rules
18
- - **Inspect package.json**: Identify Next.js version (e.g. 13, 14, 15).
19
- - **Determine Router**: Check if the project uses App Router (`app/`) or Pages Router (`pages/`). **Never assume**. Do not force App Router patterns onto a Pages Router project.
20
- - **Follow existing patterns**: Follow existing routing, data fetching, and component conventions unless explicitly requested otherwise.
21
-
22
- ### Core Mental Model
23
- - Server vs Client execution: Understand where code runs (Server Components, Client Components, SSR, SSG).
24
- - Routing is filesystem-based.
25
- - Layouts wrap pages and preserve state across navigations.
26
- - Data fetching happens at the server when possible for performance.
27
-
28
- ### Server / Client Boundary (App Router)
29
- - React Server Components are the default. They run only on the server, have access to backend resources, and send zero JS to the client.
30
- - Client Components (`'use client'`) are needed for browser APIs, client state (`useState`), event handlers (`onClick`), and client-only hooks (`useEffect`).
31
- - **Do not automatically add "use client"** everywhere. Keep Client Components as small as practical and push them down the tree to the leaf interactive elements.
32
-
33
- ### Routing
34
- - **App Router**: Organise by folders (`app/dashboard/page.tsx`). Utilize `layout.tsx`, `loading.tsx`, `error.tsx`, and `not-found.tsx`.
35
- - **Pages Router**: Organise by files (`pages/dashboard.tsx`). Utilize `_app.tsx`, `_document.tsx`.
36
- - Respect dynamic segments and route structure conventions.
37
-
38
- ### Data
39
- - Prefer server-side data loading.
40
- - Use client-side fetching (e.g., SWR, React Query, or `useEffect`) only where appropriate.
41
- - Manage loading and error states gracefully.
42
- - Understand caching considerations (e.g. `fetch` cache options in App Router).
43
- - Do not prescribe a single data library unless already established.
44
-
45
- ### Metadata / Assets
46
- - Use the Next.js Metadata API for head tags and SEO (App Router) or `next/head` (Pages Router).
47
- - Optimize images using `next/image`.
48
- - Optimize fonts using `next/font`.
49
- - Handle static assets correctly from the `public/` folder.
50
-
51
- ### Common Failure Modes
52
- - **Unnecessary client boundaries**: Wrapping an entire page in `'use client'` instead of just the interactive leaf nodes.
53
- - **Server/Client mismatch**: Hydration problems caused by rendering different content on the server vs client (e.g., using `window` directly in render).
54
- - **Incorrect data-fetching assumptions**: Mixing Pages Router data fetching (`getServerSideProps`) in App Router components.
55
- - **Caching surprises**: Next.js App Router aggressively caches `fetch`; beware of stale data.
56
- - **Route structure mistakes**: Placing components in the `pages/` directory instead of standard directories, causing accidental route creation (Pages Router).
57
-
58
- ## Anti-Patterns
59
-
60
- - **Using browser APIs in Server Components**
61
- - *What*: Calling `window.localStorage` inside a Server Component.
62
- - *Why*: Server Components run in Node.js/Edge, where `window` or `document` do not exist, causing crashes.
63
- - *Instead*: Move the logic requiring browser APIs to a Client Component or use a `useEffect` inside a Client Component.
64
-
65
- ## Workflow
66
-
67
- ### Debugging
68
- - Check if an error happens on the Server or Client.
69
- - Inspect network tabs for hydration errors.
70
- - Verify Next.js caching headers and tags if data is stale.
71
-
72
- ### Verification
73
- - Inspect the actual Next.js version.
74
- - Typecheck the codebase (`tsc --noEmit`).
75
- - Run project build and tests.
1
+ ---
2
+ name: nextjs
3
+ description: Next.js App Router, Pages Router, Server/Client components, routing, and data fetching.
4
+ category: framework
5
+ version: 2.1.0
6
+ ---
7
+
8
+ ## When to use
9
+
10
+ - building Next.js pages or components
11
+ - authoring Server/Client components
12
+ - Next.js routing and data fetching
13
+ - Next.js API routes
14
+
15
+ ## Instructions
16
+
17
+ ### Project Detection & Existing Rules
18
+ - **Inspect package.json**: Identify Next.js version (e.g. 13, 14, 15).
19
+ - **Determine Router**: Check if the project uses App Router (`app/`) or Pages Router (`pages/`). **Never assume**. Do not force App Router patterns onto a Pages Router project.
20
+ - **Follow existing patterns**: Follow existing routing, data fetching, and component conventions unless explicitly requested otherwise.
21
+
22
+ ### Core Mental Model
23
+ - Server vs Client execution: Understand where code runs (Server Components, Client Components, SSR, SSG).
24
+ - Routing is filesystem-based.
25
+ - Layouts wrap pages and preserve state across navigations.
26
+ - Data fetching happens at the server when possible for performance.
27
+
28
+ ### Server / Client Boundary (App Router)
29
+ - React Server Components are the default. They run only on the server, have access to backend resources, and send zero JS to the client.
30
+ - Client Components (`'use client'`) are needed for browser APIs, client state (`useState`), event handlers (`onClick`), and client-only hooks (`useEffect`).
31
+ - **Do not automatically add "use client"** everywhere. Keep Client Components as small as practical and push them down the tree to the leaf interactive elements.
32
+
33
+ ### Routing
34
+ - **App Router**: Organise by folders (`app/dashboard/page.tsx`). Utilize `layout.tsx`, `loading.tsx`, `error.tsx`, and `not-found.tsx`.
35
+ - **Pages Router**: Organise by files (`pages/dashboard.tsx`). Utilize `_app.tsx`, `_document.tsx`.
36
+ - Respect dynamic segments and route structure conventions.
37
+
38
+ ### Data
39
+ - Prefer server-side data loading.
40
+ - Use client-side fetching (e.g., SWR, React Query, or `useEffect`) only where appropriate.
41
+ - Manage loading and error states gracefully.
42
+ - Understand caching considerations (e.g. `fetch` cache options in App Router).
43
+ - Do not prescribe a single data library unless already established.
44
+
45
+ ### Metadata / Assets
46
+ - Use the Next.js Metadata API for head tags and SEO (App Router) or `next/head` (Pages Router).
47
+ - Optimize images using `next/image`.
48
+ - Optimize fonts using `next/font`.
49
+ - Handle static assets correctly from the `public/` folder.
50
+
51
+ ### Common Failure Modes
52
+ - **Unnecessary client boundaries**: Wrapping an entire page in `'use client'` instead of just the interactive leaf nodes.
53
+ - **Server/Client mismatch**: Hydration problems caused by rendering different content on the server vs client (e.g., using `window` directly in render).
54
+ - **Incorrect data-fetching assumptions**: Mixing Pages Router data fetching (`getServerSideProps`) in App Router components.
55
+ - **Caching surprises**: Next.js App Router aggressively caches `fetch`; beware of stale data.
56
+ - **Route structure mistakes**: Placing components in the `pages/` directory instead of standard directories, causing accidental route creation (Pages Router).
57
+
58
+ ## Anti-Patterns
59
+
60
+ - **Using browser APIs in Server Components**
61
+ - *What*: Calling `window.localStorage` inside a Server Component.
62
+ - *Why*: Server Components run in Node.js/Edge, where `window` or `document` do not exist, causing crashes.
63
+ - *Instead*: Move the logic requiring browser APIs to a Client Component or use a `useEffect` inside a Client Component.
64
+
65
+ ## Workflow
66
+
67
+ ### Debugging
68
+ - Check if an error happens on the Server or Client.
69
+ - Inspect network tabs for hydration errors.
70
+ - Verify Next.js caching headers and tags if data is stale.
71
+
72
+ ### Verification
73
+ - Inspect the actual Next.js version.
74
+ - Typecheck the codebase (`tsc --noEmit`).
75
+ - Run project build and tests.