Skip to content

t1k:web:frontend:development

FieldValue
Modulefrontend
Version1.24.11
Efforthigh
Tools—

Keywords: components, frontend, MUI, MUI v9, performance, react, Suspense, TanStack Router, typescript

/t1k:web:frontend:development
[component or feature]

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:

StepAgent
Run bun scripts/typecheck.cjs -p <tsconfig> and report its [t1k:typecheck-result] marker, the [t1k:tsrs] line and the listed diagnosticst1k-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.

Comprehensive guide for modern React development, emphasizing Suspense-based data fetching, lazy loading, proper file organization, and performance optimization.

  • 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

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 useSuspenseQuery for data fetching
  • Import aliases: @/, ~types, ~components, ~features
  • Styles: Inline if <100 lines, separate file if >100 lines
  • Use useCallback for event handlers passed to children
  • Default export at bottom
  • No early returns with loading spinners
  • Use useMuiSnackbar for user notifications

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

AliasResolves ToExample
@/src/import { apiClient } from '@/lib/apiClient'
~typessrc/typesimport type { User } from '~types/user'
~componentssrc/componentsimport { SuspenseLoader } from '~components/SuspenseLoader'
~featuressrc/featuresimport { authApi } from '~features/auth'

Defined in your project’s vite.config.ts (typical location: resolve.alias, around lines 180-185)


// React & Lazy Loading
import React, { useState, useCallback, useMemo } from 'react';
const Heavy = React.lazy(() => import('./Heavy'));
// MUI Components
import { 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 Router
import { createFileRoute } from '@tanstack/react-router';
// Project Components
import { SuspenseLoader } from '~components/SuspenseLoader';
// Hooks
import { useAuth } from '@/hooks/useAuth';
import { useMuiSnackbar } from '@/hooks/useMuiSnackbar';
// Types
import type { Post } from '~types/post';

Full topic guides (state management, routing, API, auth, testing, etc.): see references/topic-guides.md.

Need to…Read this resource
Create a componentcomponent-patterns.md (resources/component-patterns.md)
Fetch datadata-fetching.md (resources/data-fetching.md)
Organize files/foldersfile-organization.md (resources/file-organization.md)
Style componentsstyling-guide.md (resources/styling-guide.md)
Set up routingrouting-guide.md (resources/routing-guide.md)
Handle loading/errorsloading-and-error-states.md (resources/loading-and-error-states.md)
Optimize performanceperformance.md (resources/performance.md)
TypeScript typestypescript-standards.md (resources/typescript-standards.md)
Forms/Auth/DataGridcommon-patterns.md (resources/common-patterns.md)
See full examplescomplete-examples.md (resources/complete-examples.md)

  1. Lazy Load Everything Heavy: Routes, DataGrid, charts, editors
  2. Suspense for Loading: Use SuspenseLoader, not early returns
  3. useSuspenseQuery: Primary data fetching pattern for new code
  4. Features are Organized: api/, components/, hooks/, helpers/ subdirs
  5. Styles Based on Size: <100 inline, >100 separate
  6. Import Aliases: Use @/, ~types, ~components, ~features
  7. No Early Returns: Prevents layout shift
  8. useMuiSnackbar: For all user notifications

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 route

Full component template: see references/component-template.md.

  • 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

  • useEffect cleanup runs on every dep change, not just unmount — leak subscriptions otherwise.