t1k:web:frontend:development

Auto-generated

🔒 Auto-generated from The1Studio/[email protected] — edit the source kit, not this page.

Field	Value
Module	frontend
Version	1.9.0
Effort	high
Tools	—

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

How to invoke

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

---

Frontend Development Guidelines

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

• 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

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 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

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

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: vite.config.ts lines 180-185

---

Common Imports Cheatsheet

// 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';

---

Topic Guides

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

Navigation Guide

Need to…	Read this resource
Create a component	component-patterns.md
Fetch data	data-fetching.md
Organize files/folders	file-organization.md
Style components	styling-guide.md
Set up routing	routing-guide.md
Handle loading/errors	loading-and-error-states.md
Optimize performance	performance.md
TypeScript types	typescript-standards.md
Forms/Auth/DataGrid	common-patterns.md
See full examples	complete-examples.md

---

Core Principles

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

---

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 route

---

Modern Component Template (Quick Copy)

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

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

Gotchas

• Hydration mismatches in React 18+ silently swap HTML — verify SSR output matches CSR; mismatches = SEO + UX hits.
• useEffect cleanup runs on every dep change, not just unmount — leak subscriptions otherwise.
• Bundle splitting with route-based code-splitting only matters if your routes are async — eager-imported routes = one big bundle.
• Image lazy-loading needs loading=lazy AND decoding=async — one alone won’t beat First Input Delay.