t1k:web:frontend:development
| Field | Value |
|---|---|
| Module | frontend |
| Version | 1.24.11 |
| Effort | high |
| Tools | — |
Keywords: components, frontend, MUI, MUI v9, performance, react, Suspense, TanStack Router, typescript
How to invoke
Section titled “How to invoke”/t1k:web:frontend:development[component or feature]Frontend Development Guidelines
Section titled “Frontend Development Guidelines”Executed by
Section titled “Executed by”Component design, data-fetching patterns and every diagnosis or fix of a type error stay on a
reasoning tier (routing SSOT: rules/orchestration-rules.md § “Task-Type → Agent Routing”). Only
the bundled scripts/typecheck.cjs run is mechanical:
| Step | Agent |
|---|---|
Run bun scripts/typecheck.cjs -p <tsconfig> and report its [t1k:typecheck-result] marker, the [t1k:tsrs] line and the listed diagnostics | t1k-tester — runs the check and reports the output |
Stays reasoning-tier: fixing the errors the gate lists, and any change to typecheck.tsrs (the
escape hatch back to tsc needs a written reason in the repo). TSRS is the typecheck gate: a clean
tsrs run is a green typecheck, a red one fails it, and nobody re-runs tsc to overturn it. The
emit build still runs tsc, so a green typecheck is never a build.
Purpose
Section titled “Purpose”Comprehensive guide for modern React development, emphasizing Suspense-based data fetching, lazy loading, proper file organization, and performance optimization.
When to Use This Skill
Section titled “When to Use This Skill”- Creating new components or pages
- Building new features
- Fetching data with TanStack Query
- Setting up routing with TanStack Router
- Styling components with MUI v9
- Performance optimization
- Organizing frontend code
- TypeScript best practices
Quick Start
Section titled “Quick Start”New Component Checklist
Section titled “New Component Checklist”Creating a component? Follow this checklist:
- Use
React.FC<Props>pattern with TypeScript - Lazy load if heavy component:
React.lazy(() => import()) - Wrap in
<SuspenseLoader>for loading states - Use
useSuspenseQueryfor data fetching - Import aliases:
@/,~types,~components,~features - Styles: Inline if <100 lines, separate file if >100 lines
- Use
useCallbackfor event handlers passed to children - Default export at bottom
- No early returns with loading spinners
- Use
useMuiSnackbarfor user notifications
New Feature Checklist
Section titled “New Feature Checklist”Creating a feature? Set up this structure:
- Create
features/{feature-name}/directory - Create subdirectories:
api/,components/,hooks/,helpers/,types/ - Create API service file:
api/{feature}Api.ts - Set up TypeScript types in
types/ - Create route in
routes/{feature-name}/index.tsx - Lazy load feature components
- Use Suspense boundaries
- Export public API from feature
index.ts
Import Aliases Quick Reference
Section titled “Import Aliases Quick Reference”| Alias | Resolves To | Example |
|---|---|---|
@/ | src/ | import { apiClient } from '@/lib/apiClient' |
~types | src/types | import type { User } from '~types/user' |
~components | src/components | import { SuspenseLoader } from '~components/SuspenseLoader' |
~features | src/features | import { authApi } from '~features/auth' |
Defined in your project’s vite.config.ts (typical location: resolve.alias, around lines 180-185)
Common Imports Cheatsheet
Section titled “Common Imports Cheatsheet”// React & Lazy Loadingimport React, { useState, useCallback, useMemo } from 'react';const Heavy = React.lazy(() => import('./Heavy'));
// MUI Componentsimport { Box, Paper, Typography, Button, Grid } from '@mui/material';import type { SxProps, Theme } from '@mui/material';
// TanStack Query (Suspense)import { useSuspenseQuery, useQueryClient } from '@tanstack/react-query';
// TanStack Routerimport { createFileRoute } from '@tanstack/react-router';
// Project Componentsimport { SuspenseLoader } from '~components/SuspenseLoader';
// Hooksimport { useAuth } from '@/hooks/useAuth';import { useMuiSnackbar } from '@/hooks/useMuiSnackbar';
// Typesimport type { Post } from '~types/post';Topic Guides
Section titled “Topic Guides”Full topic guides (state management, routing, API, auth, testing, etc.): see references/topic-guides.md.
Navigation Guide
Section titled “Navigation Guide”| Need to… | Read this resource |
|---|---|
| Create a component | component-patterns.md (resources/component-patterns.md) |
| Fetch data | data-fetching.md (resources/data-fetching.md) |
| Organize files/folders | file-organization.md (resources/file-organization.md) |
| Style components | styling-guide.md (resources/styling-guide.md) |
| Set up routing | routing-guide.md (resources/routing-guide.md) |
| Handle loading/errors | loading-and-error-states.md (resources/loading-and-error-states.md) |
| Optimize performance | performance.md (resources/performance.md) |
| TypeScript types | typescript-standards.md (resources/typescript-standards.md) |
| Forms/Auth/DataGrid | common-patterns.md (resources/common-patterns.md) |
| See full examples | complete-examples.md (resources/complete-examples.md) |
Core Principles
Section titled “Core Principles”- Lazy Load Everything Heavy: Routes, DataGrid, charts, editors
- Suspense for Loading: Use SuspenseLoader, not early returns
- useSuspenseQuery: Primary data fetching pattern for new code
- Features are Organized: api/, components/, hooks/, helpers/ subdirs
- Styles Based on Size: <100 inline, >100 separate
- Import Aliases: Use @/, ~types, ~components, ~features
- No Early Returns: Prevents layout shift
- useMuiSnackbar: For all user notifications
Quick Reference: File Structure
Section titled “Quick Reference: File Structure”src/ features/ my-feature/ api/ myFeatureApi.ts # API service components/ MyFeature.tsx # Main component SubComponent.tsx # Related components hooks/ useMyFeature.ts # Custom hooks useSuspenseMyFeature.ts # Suspense hooks helpers/ myFeatureHelpers.ts # Utilities types/ index.ts # TypeScript types index.ts # Public exports
components/ SuspenseLoader/ SuspenseLoader.tsx # Reusable loader CustomAppBar/ CustomAppBar.tsx # Reusable app bar
routes/ my-route/ index.tsx # Route component create/ index.tsx # Nested routeModern Component Template (Quick Copy)
Section titled “Modern Component Template (Quick Copy)”Full component template: see references/component-template.md.
Related Skills
Section titled “Related Skills”- error-tracking: Error tracking with Sentry (applies to frontend too)
- backend-dev-guidelines: Backend API patterns that frontend consumes
Skill Status: Modular structure with progressive loading for optimal context management
Hard rules
Section titled “Hard rules”useEffectcleanup runs on every dep change, not just unmount — leak subscriptions otherwise.