Fundamentos de TypeScript para React

Receta

Configura un proyecto de React impulsado por TypeScript con un tsconfig.json bien configurado, comprende cómo funcionan los archivos .tsx y aprende las anotaciones de tipo central que todo desarrollador de React necesita.

Ejemplo de Trabajo

// tsconfig.json (Next.js 15 / React 19 recomendado)
{
  "compilerOptions": {
    "target": "ES2022",
    "lib": ["dom", "dom.iterable", "esnext"],
    "allowJs": true,
    "skipLibCheck": true,
    "strict": true,
    "noEmit": true,
    "esModuleInterop": true,
    "module": "esnext",
    "moduleResolution": "bundler",
    "resolveJsonModule": true,
    "isolatedModules": true,
    "jsx": "preserve",
    "incremental": true,
    "plugins": [{ "name": "next" }],
    "paths": {
      "@/*": ["./src/*"]
    }
  },
  "include": ["next-env.d.ts", "**/*.ts", "**/*.tsx", ".next/types/**/*.ts"],
  "exclude": ["node_modules"]
}

// src/components/Greeting.tsx
type GreetingProps = {
  name: string;
  age?: number;
};
 
export function Greeting({ name, age }: GreetingProps) {
  return (
    <div>
      <h1>Hola, {name}</h1>
      {age !== undefined && <p>Edad: {age}</p>}
    </div>
  );
}

// Uso
<Greeting name="Alice" />
<Greeting name="Bob" age={30} />

Análisis Profundo

Cómo Funciona

• TypeScript agrega chequeo de tipos estático sobre JavaScript. El compilador detecta errores de tipo antes de que tu código se ejecute en el navegador.
• Los archivos .tsx son archivos TypeScript que soportan sintaxis JSX. La configuración jsx: "preserve" le indica a TypeScript que deje JSX sin modificar para que el bundler (Next.js, Vite) lo maneje.
• strict: true habilita una familia de chequeos estrictos (strictNullChecks, strictFunctionTypes, noImplicitAny, etc.) que detectan la mayoría de bugs.
• moduleResolution: "bundler" coincide con cómo los bundlers modernos resuelven importaciones, soportando campos exports en package.json e importaciones sin extensión.
• Los alias de ruta como @/* te permiten escribir import { Button } from "@/components/Button" en lugar de rutas relativas frágiles.

Variaciones

Configuración de Vite + React:

{
  "compilerOptions": {
    "target": "ES2022",
    "lib": ["ES2023", "DOM", "DOM.Iterable"],
    "module": "ESNext",
    "moduleResolution": "bundler",
    "jsx": "react-jsx",
    "strict": true,
    "noEmit": true,
    "isolatedModules": true,
    "skipLibCheck": true
  },
  "include": ["src"]
}

Agregar opciones más estrictas incrementalmente:

{
  "compilerOptions": {
    "strict": true,
    "noUncheckedIndexedAccess": true,
    "exactOptionalPropertyTypes": true,
    "noFallthroughCasesInSwitch": true
  }
}

Notas de TypeScript

• Siempre instala tipos de React: npm install -D @types/react @types/react-dom. Con React 19, los tipos se distribuyen con react y @types/react podría no ser necesario dependiendo de tu configuración.
• Usa type para props y formas simples; usa interface cuando necesites declaration merging o extends.
• Prefiere unknown sobre any. Si debes usar any, añade un comentario // eslint-disable y un TODO para solucionarlo después.

Trampas

• Olvidar "strict": true significa que TypeScript no marcará acceso a null o undefined, derrotando gran parte de su valor.
• Configurar jsx a "react" en lugar de "preserve" o "react-jsx" te fuerza a hacer import React from "react" en cada archivo.
• skipLibCheck: true se recomienda para velocidad de compilación pero puede ocultar errores de tipo en tus propios archivos .d.ts.
• Usar any desactiva silenciosamente el chequeo de tipos para todo lo que ese valor toca posteriormente.

Alternativas

Preguntas Frecuentes

{
  "compilerOptions": {
    "paths": {
      "@/*": ["./src/*"]
    }
  }
}

type GreetingProps = {
  name: string;
  age?: number; // opcional
};
 
function Greeting({ name, age = 25 }: GreetingProps) {
  return <p>{name} is {age} years old</p>;
}

Relacionado

• Typing Props
• Strict Mode Patterns
• Declaration Files
• TypeScript Handbook - tsconfig