Frontend Dev Guidelines

Frontend Dev Guidelines

Frontend development guidelines for React/TypeScript applications. Modern patterns including Suspense, lazy loading, useSuspenseQuery, file organizati

Category: development Source: mrgoonie/claudekit-skills

What Is Frontend Dev Guidelines?

Frontend Dev Guidelines is a comprehensive set of recommendations and conventions tailored for building modern React and TypeScript applications. It encapsulates up-to-date patterns and tools, such as React Suspense, lazy loading, the useSuspenseQuery hook, robust file organization, Material UI v7 (MUI v7) styling, TanStack Router for routing, and a focus on performance optimization and TypeScript best practices. These guidelines are designed to standardize the development workflow, increase maintainability, and maximize performance for frontend teams working on complex applications.

Why Use Frontend Dev Guidelines?

Modern frontend applications are becoming increasingly complex, with requirements for scalability, performance, and maintainability. Adhering to a clear set of guidelines ensures that teams can:

  • Ship consistent, reliable features across projects.
  • Reduce onboarding time for new developers.
  • Avoid common performance pitfalls and anti-patterns.
  • Leverage the latest advancements in the React and TypeScript ecosystems.
  • Facilitate code reviews and collaboration by enforcing recognizable patterns.
  • Improve user experience by optimizing loading strategies and resource management.

By integrating these guidelines into your workflow, you will streamline development, reduce technical debt, and deliver higher-quality frontend code.

How to Get Started

To adopt the Frontend Dev Guidelines in your project, begin by familiarizing yourself with its core principles and recommended tools. The guidelines are particularly applicable when you are:

  • Creating new React components or pages.
  • Developing features that require data fetching.
  • Setting up routing for your application.
  • Styling components using MUI v7.
  • Organizing project files and directories.
  • Optimizing for frontend performance.
  • Writing type-safe, robust TypeScript code.

Quick Start Checklist for a New Component:

  1. Use the React.FC<Props> pattern for type-safe components.
  2. Apply lazy loading for heavy components using React.lazy.
  3. Wrap components with a custom <SuspenseLoader> to handle loading states.
  4. Fetch data using the useSuspenseQuery hook.
  5. Utilize import aliases for better readability and maintainability.
  6. Organize styles: keep them inline if under 100 lines, otherwise use a separate file.
  7. Use useCallback for event handlers passed to children.
  8. Place the default export at the bottom of the file.
  9. Avoid early returns with loading spinners inside components.

Key Features

1. Suspense-Based Data Fetching

Leverage React’s Suspense in combination with data-fetching hooks (like useSuspenseQuery from TanStack Query) to streamline asynchronous data handling:

const { data } = useSuspenseQuery(['user', userId], fetchUser);

return (
  <SuspenseLoader>
    <UserProfile data={data} />
  </SuspenseLoader>
);

2. Lazy Loading

Improve initial load performance by splitting code and loading components only when needed:

const SettingsPanel = React.lazy(() => import('~features/settings/SettingsPanel'));

return (
  <SuspenseLoader>
    <SettingsPanel />
  </SuspenseLoader>
);

3. Modern File Organization

Adopt a “features” directory structure, grouping related components, hooks, and styles:

src/
  features/
    user/
      UserProfile.tsx
      useUser.ts
      styles.ts

4. MUI v7 Styling

Utilize MUI v7’s powerful styling system for consistent, themeable UI. Keep styles inline for small components, or in separate files for larger ones:

const StyledButton = styled(Button)`
  margin-top: 16px;
`;

5. TanStack Router Integration

Declaratively define routes and layouts using TanStack Router for a flexible, scalable routing solution:

import { RouterProvider } from '@tanstack/router';

<RouterProvider routes={routes} />

6. TypeScript Best Practices

Ensure type safety with explicit prop interfaces, strong typing for hooks, and minimal use of any:

type Props = {
  userId: string;
};

const UserProfile: React.FC<Props> = ({ userId }) => { ... }

Best Practices

  • Component Creation: Always use the React.FC<Props> pattern for new components. This enforces prop type safety and improves code clarity.
  • Performance Optimization: Lazy load heavy components and leverage Suspense boundaries for smoother loading experiences. Avoid rendering loading spinners deep inside components.
  • Data Fetching: Use useSuspenseQuery to co-locate data requirements with components, minimizing boilerplate and ensuring reliable loading states.
  • File Organization: Group related files by feature, not by file type. Use import aliases (@/, ~components, ~features) to simplify imports.
  • Styling: Keep inline styles for components with less than 100 lines of style code. For larger components, extract styles to separate files.
  • Handlers: Use useCallback when passing event handlers to child components to prevent unnecessary re-renders.
  • Exports: Place default exports at the bottom of files for consistency and easier navigation.
  • Routing: Prefer TanStack Router for complex routing needs; keep route configuration centralized.

Important Notes

  • Strict Adherence: Consistency is key. Adhere strictly to these guidelines across all new code and refactors.
  • No Early Returns with Spinners: Avoid returning loading spinners early in the render function. Instead, use Suspense boundaries for loading states.
  • TypeScript Only: These guidelines assume all code is written in TypeScript. Avoid using JavaScript files for components or features.
  • Performance Matters: Regularly profile your application, especially after introducing new components or features.
  • Stay Updated: React, MUI, and TanStack Query/Router are actively evolving. Periodically review and update your practices to align with the latest stable releases.
  • Documentation: Document any deviations from these guidelines and justify them in code comments or pull requests.

By following the Frontend Dev Guidelines, teams can achieve a high level of code quality, maintainability, and performance in modern React/TypeScript applications.