webdev

Web Development Skill

Guidelines for TypeScript, React, and Next.js development.

Code Organization: Feature-Sliced Design

All frontend code must follow Feature-Sliced Design (FSD) — an architectural methodology that organizes code by business domain rather than technical concerns.

Layers

FSD defines standardized layers, ordered top to bottom. Modules may only import from layers strictly below them. No lateral imports between modules on the same layer.

Slices

Within each layer (except app and shared), code is partitioned into slices by business domain. Each slice is a folder named after its domain concept.

Critical rule: Slices on the same layer cannot import from each other. This enforces low coupling.

features/
├── create-calculator/    # One slice
├── apply-theme/          # Another slice — cannot import from create-calculator
└── configure-formula/    # Another slice — cannot import from siblings

Segments

Each slice contains segments that organize code by technical purpose:

Public API

Every slice must export through an index.ts barrel file at its root. External consumers import only from this public API, never from internal segment files.

// features/create-calculator/index.ts  — public API
export { CreateCalculatorForm } from './ui/CreateCalculatorForm';
export { useCreateCalculator } from './model/useCreateCalculator';
export type { CreateCalculatorParams } from './model/types';

// ✅ Good — import from the slice's public API
import { CreateCalculatorForm } from '@/features/create-calculator';

// ❌ Bad — reaching into internal segments
import { CreateCalculatorForm } from '@/features/create-calculator/ui/CreateCalculatorForm';

Example Project Structure

src/
├── app/                          # App layer: Next.js routing, providers, global styles
│   ├── layout.tsx
│   ├── providers.tsx
│   ├── globals.css
│   ├── dashboard/
│   │   └── page.tsx
│   └── editor/[id]/
│       └── page.tsx
│
├── pages/                        # Pages layer: page-level compositions
│   ├── dashboard/
│   │   ├── ui/
│   │   ├── model/
│   │   └── index.ts
│   └── calculator-editor/
│       ├── ui/
│       ├── model/
│       └── index.ts
│
├── widgets/                      # Widgets layer: self-contained UI blocks
│   ├── calculator-preview/
│   │   ├── ui/
│   │   ├── model/
│   │   └── index.ts
│   └── submission-table/
│       ├── ui/
│       ├── model/
│       └── index.ts
│
├── features/                     # Features layer: user-facing capabilities
│   ├── create-calculator/
│   │   ├── ui/
│   │   ├── model/
│   │   ├── api/
│   │   └── index.ts
│   ├── configure-formula/
│   │   ├── ui/
│   │   ├── model/
│   │   └── index.ts
│   └── apply-theme/
│       ├── ui/
│       ├── model/
│       └── index.ts
│
├── entities/                     # Entities layer: business domain objects
│   ├── calculator/
│   │   ├── ui/
│   │   ├── model/
│   │   ├── api/
│   │   └── index.ts
│   ├── submission/
│   │   ├── ui/
│   │   ├── model/
│   │   ├── api/
│   │   └── index.ts
│   └── user/
│       ├── model/
│       ├── api/
│       └── index.ts
│
└── shared/                       # Shared layer: project-agnostic reusable code
    ├── ui/                       # UI kit (buttons, inputs, modals)
    ├── api/                      # API client, interceptors
    ├── lib/                      # Utilities (formatting, validation)
    └── config/                   # Constants, env config

Import Rules Summary

app       → pages, widgets, features, entities, shared
pages     → widgets, features, entities, shared
widgets   → features, entities, shared
features  → entities, shared
entities  → shared
shared    → (external packages only)

Violations of these import rules indicate an architectural problem. Fix the dependency direction rather than working around it.

TypeScript

ES Modules

Always use ES module syntax (import/export) instead of CommonJS (require/module.exports).

Bad - CommonJS:

const nextJest = require('next/jest');
module.exports = config;

Good - ES Modules:

import nextJest from 'next/jest.js';
export default config;

Important Notes:

• When importing from npm packages in ESM mode, you may need to include the .js extension (e.g., 'next/jest.js')
• Use import type for TypeScript types to enable type-only imports
• Use named exports for utilities, default exports for components/configs

Never Use any Types

The any type defeats the purpose of TypeScript and should be avoided. Use proper type assertions or type guards instead.

Bad:

const result = convertFormat(input, options as any, output as any);

Good:

import type { ParseOptions, FormatOptions } from "./types";

const inputOptions: ParseOptions = { format: format as DateTimeFormat, customFormat };
const outputOptions: FormatOptions = { format: format as DateTimeFormat };
const result = convertFormat(input, inputOptions, outputOptions);

When you need type assertions:

• Use specific type assertions: value as string, value as DateTimeFormat
• Import and use the actual types from their definitions
• Document why the assertion is safe with a comment if non-obvious

Alternatives to any:

• unknown - for truly unknown types (forces type checking before use)
• Union types - string | number | boolean
• Generic types - <T> with constraints
• Type guards - if (typeof x === 'string')

Component Props Typing

Use interfaces or types for component props:

interface MessageProps {
  /** The message content to display */
  content: string;
  /** Whether the message is from the current user */
  isOwn: boolean;
  /** Timestamp when the message was sent */
  timestamp: Date;
  /** Optional callback when message is clicked */
  onClick?: (messageId: string) => void;
}

function Message({ content, isOwn, timestamp, onClick }: MessageProps) {
  return (
    <div onClick={() => onClick?.(content)}>
      <p>{content}</p>
      <time>{timestamp.toISOString()}</time>
    </div>
  );
}

Hook Typing Patterns

useState - Let TypeScript infer when possible:

// Inferred as boolean
const [isOpen, setIsOpen] = useState(false);

// Union types need explicit typing
type Status = "idle" | "loading" | "success" | "error";
const [status, setStatus] = useState<Status>("idle");

// Discriminated unions for complex state
type RequestState =
  | { status: 'idle' }
  | { status: 'loading' }
  | { status: 'success'; data: Message[] }
  | { status: 'error'; error: Error };
const [state, setState] = useState<RequestState>({ status: 'idle' });

useReducer - Type actions as discriminated unions:

interface State {
  messages: Message[];
  status: Status;
}

type Action =
  | { type: "messages_loaded"; messages: Message[] }
  | { type: "message_added"; message: Message }
  | { type: "message_deleted"; messageId: string }
  | { type: "status_changed"; status: Status };

function reducer(state: State, action: Action): State {
  switch (action.type) {
    case "messages_loaded":
      return { ...state, messages: action.messages, status: "success" };
    case "message_added":
      return { ...state, messages: [...state.messages, action.message] };
    case "message_deleted":
      return {
        ...state,
        messages: state.messages.filter(m => m.id !== action.messageId)
      };
    case "status_changed":
      return { ...state, status: action.status };
  }
}

useContext - Handle nullable contexts:

type User = { id: string; name: string; role: string };
const UserContext = createContext<User | null>(null);

function useUser() {
  const user = useContext(UserContext);
  if (!user) {
    throw new Error("useUser must be used within UserProvider");
  }
  return user;
}

Event handlers:

function handleChange(event: React.ChangeEvent<HTMLInputElement>) {
  setValue(event.currentTarget.value);
}

function handleSubmit(event: React.FormEvent<HTMLFormElement>) {
  event.preventDefault();
  // ...
}

function handleClick(event: React.MouseEvent<HTMLButtonElement>) {
  // ...
}

Common React types:

interface ComponentProps {
  children: React.ReactNode;        // Any valid React child
  style?: React.CSSProperties;      // Inline styles
  className?: string;
  onClick?: React.MouseEventHandler<HTMLButtonElement>;
}

React State Management

State Structure Principles

1. Group related state

// ❌ Bad - separate state that updates together
const [x, setX] = useState(0);
const [y, setY] = useState(0);

// ✅ Good - group 

---

*Content truncated.*