Writing React TS Code

Writing React/TypeScript Code

This is the authoritative standard for all React/TypeScript code. Every file you write or modify must conform to these rules. They are not suggestions.

1. TypeScript Strict Configuration

ESLint Flat Config

Use typescript-eslint with strict + type-checked presets, plus additional rules. Some rules use warnInDevModeErrorInProd() — warn during development, error in CI/production.

Key enforced rules (beyond the strict preset):

// Zero tolerance for type escape hatches
'@typescript-eslint/no-explicit-any': 'error',
'@typescript-eslint/no-unsafe-assignment': 'error',
'@typescript-eslint/no-unsafe-call': 'error',
'@typescript-eslint/no-unsafe-member-access': 'error',
'@typescript-eslint/no-unsafe-return': 'error',
'@typescript-eslint/no-unsafe-argument': 'error',
'@typescript-eslint/no-non-null-assertion': 'error',
'@typescript-eslint/ban-ts-comment': 'error',

// Forbid vague types
'@typescript-eslint/no-empty-object-type': 'error',    // {} banned
'@typescript-eslint/no-unsafe-function-type': 'error',  // Function banned
'@typescript-eslint/no-wrapper-object-types': 'error',  // Object/String/Number banned
'@typescript-eslint/no-restricted-types': ['error', {   // object banned
  types: { object: { message: 'Use Record<string, unknown> or a specific interface' } }
}],

// Enforce explicit, predictable code
'@typescript-eslint/strict-boolean-expressions': ['error', {
  allowString: false,
  allowNumber: false,
  allowNullableObject: true,
  allowNullableBoolean: true,
  allowNullableString: false,
  allowNullableNumber: false,
  allowAny: false,
}],
'@typescript-eslint/prefer-nullish-coalescing': 'error',
'@typescript-eslint/prefer-optional-chain': 'error',
'@typescript-eslint/switch-exhaustiveness-check': 'error',
'@typescript-eslint/no-unnecessary-condition': 'error',
'@typescript-eslint/no-unnecessary-type-assertion': 'error',
'@typescript-eslint/consistent-type-assertions': ['error', {
  assertionStyle: 'as',
  objectLiteralTypeAssertions: 'never',
}],
'@typescript-eslint/explicit-function-return-type': ['error', {
  allowExpressions: true,
  allowTypedFunctionExpressions: true,
  allowHigherOrderFunctions: true,
  allowDirectConstAssertionInArrowFunctions: true,
  allowConciseArrowFunctionExpressionsStartingWithVoid: true,
  allowFunctionsWithoutTypeParameters: true,
  allowIIFEs: true,
}],

// Code quality
eqeqeq: 'error',
'prefer-const': 'error',
'no-console': warnInDevModeErrorInProd(),

// React hooks (from next/core-web-vitals + explicit)
'react-hooks/exhaustive-deps': 'error',
'react-hooks/rules-of-hooks': 'error',

// Import organization
'import/order': [warnInDevModeErrorInProd(), {
  'newlines-between': 'always',
  alphabetize: { order: 'asc', caseInsensitive: true },
  groups: ['builtin', 'external', 'internal', ['parent', 'sibling', 'index'], 'type'],
  pathGroups: [{ pattern: '@/**', group: 'internal', position: 'before' }],
}],
'unused-imports/no-unused-imports': warnInDevModeErrorInProd(),

// Custom: process.env banned in src/ (except NODE_ENV) — use env.ts
'local-rules/no-process-env-in-src': ['error', { allow: ['NODE_ENV'] }],

Relaxed rules for vendored components (src/components/ui/**, src/components/kbar/**): all strict type rules, boolean safety, and vague type rules are turned off. These are generated/vendored code — do not manually enforce rules on them.

tsconfig.json

{
  "compilerOptions": {
    "strict": true,
    "noUncheckedIndexedAccess": true,
    "exactOptionalPropertyTypes": true,
    "noImplicitReturns": true,
    "noFallthroughCasesInSwitch": true,
    "forceConsistentCasingInFileNames": true,
    "paths": { "@/*": ["./src/*"] }
  }
}

2. Type Safety Rules

Forbidden Types

These types destroy type safety. Never use them.

Type Safety Hierarchy

Each level requires justification to reach the next.

React Component Generics

Use constrained generics, not any. The type system only works if you give it information.

// WRONG — kills type checking for the entire array
const items: ReactElement<any>[] = [];

// RIGHT — preserves type checking
const items: ReactElement<Record<string, unknown>>[] = [];

// WRONG — any props accepted
type Props = ComponentProps<any>;

// RIGHT — constrained to a specific element
type Props = ComponentProps<'button'>;

Third-Party Library Type Strategy

When a library has weak or missing types, try these in order. Stop at the first one that works.

1. Official @types packages — pnpm add -D @types/library-name
2. Community typing packages — search npm for types
3. Write own type definitions — declare module 'library-name' { ... } in a .d.ts file
4. Module augmentation for incomplete types:

   // types/library-name.d.ts
   declare module 'library-name' {
     interface ExistingInterface {
       missingProperty: string;
     }
   }
   

5. Runtime assertion pattern with Result:

   function parseLibraryResponse(raw: unknown): Result<LibraryData, ValidationError> {
     const parsed = libraryDataSchema.safeParse(raw);
     if (!parsed.success) {
       return { success: false, error: { message: parsed.error.message } };
     }
     return { success: true, data: parsed.data };
   }
   

6. Last resort — targeted ESLint disable with explanation:

   // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment -- library X exports untyped config, tracked in PROJ-1234
   const config = libraryFunction();
   

3. Result Pattern

Every operation that can fail returns a Result. No exceptions for expected failures.

Core Types

// src/lib/result.ts
export type Result<T, E> =
  | { readonly success: true; readonly data: T }
  | { readonly success: false; readonly error: E };

Layer-Specific Types

// API layer — src/lib/api/api.types.ts
type ApiError = {
  code: ErrorCode;          // 'VALIDATION_ERROR', 'UNAUTHORIZED', etc.
  message: string;
  fields?: FieldErrors;     // Field-specific validation errors
  status?: number;
  details?: unknown;
};
type ApiResult<T> = Result<T, ApiError>;

// Store layer — defined per store
type StoreError = Readonly<{
  message: string;
  details?: unknown;
}>;
type StoreResult<T> = Result<T, StoreError>;

// Store error state for UI display
type StoreErrorState = Readonly<{
  error: StoreError;
  errorMessageForUser: string;
}>;

Mapping Between Layers

Never leak API errors into the UI. Map explicitly at the store boundary.

function mapApiResultToStoreResult<T>(apiResult: ApiResult<T>): StoreResult<T> {
  if (apiResult.success) {
    return { success: true, data: apiResult.data };
  }
  return {
    success: false,
    error: {
      message: apiResult.error.message,
      details: apiResult.error,
    },
  };
}

Always Check Before Access

// WRONG — TypeScript will stop you, but don't even try
const data = result.data;

// RIGHT — narrow first
if (result.success) {
  const data = result.data; // TypeScript knows this is T
} else {
  const error = result.error; // TypeScript knows this is E
}

Decision Table: Result vs Throw

4. Error Handling Strategy

Errors flow through layers. Each layer has a single responsibility.

Layer Architecture

API layer        → catches exceptions   → returns ApiResult<T>
Store layer      → maps ApiResult       → sets StoreError state
Component layer  → reads store state    → renders error UI or data
Form layer       → reads error.fields   → maps to field-level errors
Rendering crash  → React ErrorBoundary  → catches and displays fallback

API Boundary

Catch everything. Return ApiResult<T>. No raw exceptions escape. The template provides apiRequestWrapper in src/lib/api/ which handles fetch, Zod validation, auth token injection, and 401 auto-refresh.

// Simplified pattern — the real apiRequestWrapper handles more (auth, refresh, etc.)
async function apiRequestWrapper<T>(
  request: () => Promise<Response>,
  schema: ZodSchema<T>
): Promise<ApiResult<T>> {
  try {
    const response = await request();

    if (!response.ok) {
      return {
        success: false,
        error: {
          code: 'NETWORK_ERROR',
          message: await response.text(),
          status: response.status,
        },
      };
    }

    const json: unknown = await response.json();
    const parsed = schema.safeParse(json);

    if (!parsed.success) {
      return {
        success: false,
        error: {
          code: 'VALIDATION_ERROR',
          message: `Response validation failed: ${parsed.error.message}`,
          status: response.status,
        },
      };
    }

    return { success: true, data: parsed.data };
  } catch (error: unknown) {
    return {
      success: false,
      error: {
        code: 'NETWORK_ERROR',
        message: error instanceof Error ? error.message : 'Unknown network error',
      },
    };
  }
}

Store Boundary

Map ApiResult to StoreResult. Set StoreErrorState with a user-friendly message. Store actions return StoreResult<T> so callers can react.

// Inside a Zustand store action
fetchProducts: async (): Promise<StoreResult<readonly Product[]>> => {
  set({ loading: true, error: null });
  const apiResult = await productsApi.getAll();
  const result = mapApiResultToStoreResult(apiResult);

  if (!result.success) {
    set({
      loading: false,
      error: {
        error: result.error,
        errorMessageForUser: 'Failed to load products',
      },
    });
    return result;
  }

  set({ products: result.data, loading: false });
  return result;
},

Component Boundary

Components render based on store state. Error boundaries catch rendering crashes. Conditional rendering handles store errors via StoreErrorState.

export function ProductList(): JSX.Element {
  const { products, error, loading } = useProductStore();

  if (loading) {
    return <ProductListSkeleton />;
  }

  if (error !== null) {
    return <ErrorMessage message={error.errorMessageForUser} />;
  }

  return (
    <ul>
      {products.map((product) => (
        <ProductCard key={product.id} product={product} />
      ))}
    </ul>
  );
}

Form Errors

Zod schemas validate. React Hook Form manages state. Server errors map to fields.

const formSchema = z.object({
  email: z.string().email('Invalid email address'),
  name: z.string().min(1, 'Name is required'),
});

type FormData = z.infer<typeof formSchema>;

export function UserForm(): JSX.Element {
  const form = useForm<FormData>({
    resolver: zodResolver(formSchema),
  });

  async function onSubmit(data: FormData): Promise<void> {
    const result = await userApi.create(data);

    if (!result.success) {
      // Map server field errors back to form fields
      if (result.error.fields != null) {
        for (const [field, messages] of Object.entries(result.error.fields)) {
          form.setError(field as keyof FormData, { message: messages.join(', ') });
        }
        return;
      }
      toast.error(result.error.message);
      return;
    }

    toast.success('User created');
  }

  return <form fields */}</form>;
}

5. Dynamic Data Handling

All data from outside the application boundary is untrusted. Validate immediately.

Zod for Everything External

// API responses — define schema, validate on receipt
const productSchema = z.object({
  id: z.string().uuid(),
  name: z.string(),
  price: z.number().positive(),
});

// JSON.parse always returns unknown — validate immediately
function parseJsonConfig(raw: string): Result<Config, ValidationError> {
  let parsed: unknown;
  try {
    parsed = JSON.parse(raw) as unknown;
  } catch {
    return { success: false, error: { message: 'Invalid JSON' } };
  }

  const result = configSchema.safeParse(parsed);
  if (!result.success) {
    return { success: false, error: { message: result.error.message } };
  }
  return { success: true, data: result.data };
}

The safeParse + handleZodValidationOrThrow Pattern

function handleZodValidationOrThrow<T>(
  result: z.SafeParseReturnType<unknown, T>,
  context: string
): T {
  if (result.success) {
    return result.data;
  }
  // This is a programming error — the data should have been valid
  throw new Error(
    `Zod validation failed in ${context}: ${result.error.message}`
  );
}

// Use when invalid data is a bug (internal config, known-good sources)
const config = handleZodValidationOrThrow(
  configSchema.safeParse(rawConfig),
  'app configuration'
);

What Gets Validated

6. Component Patterns

Standard Component Structure

interface ProductCardProps {
  readonly product: Product;
  readonly onAddToCart: (productId: string) => Promise<void>;
}

export function ProductCard({
  product,
  onAddToCart,
}: ProductCardProps): JSX.Element {
  const [isAdding, setIsAdding] = useState<boolean>(false);

  async function handleAddToCart(): Promise<void> {
    setIsAdding(true);
    try {
      await onAddToCart(product.id);
      toast.success('Added to cart');
    } catch (error: unknown) {
      toast.error('Failed to add to cart');
    } finally {
      setIsAdding(false);
    }
  }

  return (
    <div>
      <h3>{product.name}</h3>
      <p>{formatPrice(product.price)}</p>
      <Button disabled={isAdding}>
        {isAdding ? 'Adding...' : 'Add to Cart'}
      </Button>
    </div>
  );
}

Rules

• Named exports only. No export default. Exception: Next.js page.tsx and layout.tsx files require default exports.
• Explicit return types on all exported functions: JSX.Element, Promise<void>, etc.
• readonly on all props interface properties. Props are immutable input.
• Explicit types for state. useState<boolean>(false), not useState(false).
• Async event handlers return Promise<void> and handle their own errors inside. Never let a rejected promise go unhandled.
• No inline object/array creation in JSX props when it causes unnecessary re-renders. Extract to useMemo or a constant outside the render.

App Router Pattern

Route files are thin wrappers. Logic lives in components and stores.

// src/app/users/page.tsx — thin route file (default export required by Next.js)
export default function UsersPage(): JSX.Element {
  return <UserList />;
}

// src/components/UserList.tsx — all logic here (named export)
export function UserList(): JSX.Element {
  const { users, loading, error, fetchUsers } = useUserStore();
  // loading states, error handling, data rendering
}

7. Naming Conventions

Naming is a navigation system, not a style preference.

8. Import Organization

Imports are grouped and alphabetized. Enforced by ESLint, not by discipline.

// 1. Builtin (node:)
import { readFile } from 'node:fs/promises';

// 2. External packages
import { z } from 'zod';
import { create } from 'zustand';

// 3. Internal (@/ alias)
import { apiRequestWrapper } from '@/lib/api/api-client';
import { productSchema } from '@/schemas/product-schema';

// 4. Parent/sibling/index (grouped together)
import { formatPrice } from '../utils/format-price';
import { ProductImage } from './ProductImage';

// 5. Type imports (always last)
import type { Product } from '@/types/product-types';

Path alias: @/* maps to ./src/*. Never use deep relative paths like ../../../lib/utils. Use the alias.

9. Environment Variables

All Access Through t3-env

// src/env.ts
import { createEnv } from '@t3-oss/env-nextjs';
import { z } from 'zod';

export const env = createEnv({
  server: {
    DATABASE_URL: z.string().url(),
    API_SECRET: z.string().min(1),
  },
  client: {
    NEXT_PUBLIC_API_URL: z.string().url(),
  },
  runtimeEnv: {
    DATABASE_URL: process.env.DATABASE_URL,
    API_SECRET: process.env.API_SECRET,
    NEXT_PUBLIC_API_URL: process.env.NEXT_PUBLIC_API_URL,
  },
});

Rules

• process.env is banned in src/ by a custom ESLint rule (scripts/eslint/rules/no-process-env-in-src). The only exception is NODE_ENV. All other access goes through env.ts.
• Build fails if any required variable is missing or fails Zod validation. No silent fallback to undefined.
• Server vs client: Only NEXT_PUBLIC_ prefixed variables are available in browser code. Server variables stay on the server.
• Always import from @/env:

  // WRONG — ESLint error
  const url = process.env.NEXT_PUBLIC_API_URL;
  
  // RIGHT — typed, validated, guaranteed to exist
  import { env } from '@/env';
  const url = env.NEXT_PUBLIC_API_URL;
  

10. Code Style

Prettier Configuration

{
  "tabWidth": 2,
  "singleQuote": true,
  "trailingComma": "none",
  "plugins": ["prettier-plugin-tailwindcss"]
}

Rules

• prefer-const everywhere. Use let only when reassignment is necessary.
• === enforced via eqeqeq ESLint rule. == is banned.
• ?? over || for nullish defaults. || coerces empty strings and 0 to falsy.
• ?. over && chains for optional property access.
• Explicit return types on all exported functions and any function longer than a few lines. TypeScript may infer for simple local one-liners.
• Early returns for error/edge cases. Keep the happy path unindented and linear.

// WRONG — deeply nested
function process(input: string | null): Result<Data, ProcessError> {
  if (input !== null) {
    if (input.length > 0) {
      // actual logic buried in nesting
    }
  }
}

// RIGHT — early returns, flat structure
function process(input: string | null): Result<Data, ProcessError> {
  if (input === null) {
    return { success: false, error: { message: 'Input is null' } };
  }
  if (input.length === 0) {
    return { success: false, error: { message: 'Input is empty' } };
  }

  // actual logic at top-level indentation
  return { success: true, data: transform(input) };
}

Boolean Expressions

strict-boolean-expressions is enabled. No truthy checks on strings or numbers. Nullable booleans are allowed.

// WRONG — fails strict-boolean-expressions
if (name) { ... }
if (count) { ... }
if (items.length) { ... }

// RIGHT — explicit comparisons
if (name !== '') { ... }
if (count > 0) { ... }
if (items.length > 0) { ... }
if (value !== null && value !== undefined) { ... }

// OK — nullable booleans are allowed (allowNullableBoolean: true)
if (isEnabled) { ... }  // where isEnabled: boolean | null

Console Usage

• no-console uses warnInDevModeErrorInProd() — warns in development, errors in CI/production builds.
• Never commit console.log calls except for startup/shutdown messages in server code.

11. Security

These are non-negotiable. Violations are bugs, not style issues.

12. API Code Generation

Zod schemas for API responses are auto-generated from OpenAPI/Swagger specs. Do not write them by hand.

• Generate: pnpm api:gen <feature> reads the Swagger spec and outputs Zod schemas into api/generated/ directories
• Use in API clients: Import generated schemas and pass to apiRequestWrapper for runtime validation
• Single source of truth: Backend OpenAPI spec defines the contract; generated Zod schemas enforce it at runtime

Feature Directory Structure

src/mfes/{domain}/
  app.tsx                  # Main React component
  index.ts                 # single-spa lifecycles export
  stores/
    {domain}-store.ts      # Zustand store with Result pattern
  api/
    {domain}-api.ts        # API client using apiRequestWrapper
    generated/             # Auto-generated Zod schemas (pnpm api:gen)
  components/              # Domain-specific components (optional)