← Volver al blog

TypeScript en el frontend: errores comunes y cómo evitarlos

2026-06-10

TypeScript en el frontend: errores comunes y cómo evitarlos

TypeScript se ha convertido en el estándar de facto para el desarrollo frontend moderno. Sin embargo, la transición de JavaScript a TypeScript no siempre es lineal. Muchos equipos caen en trampas que anulan los beneficios del sistema de tipos: falsean seguridad, generan deuda técnica o, peor aún, bloquean builds en momentos críticos.

Este artículo recorre los errores más frecuentes que observo en proyectos React y Next.js, con ejemplos concretos y soluciones aplicables inmediatamente.

1. Abuso de any: el peor enemigo de TypeScript

El problema

El tipo any desactiva el chequeo de tipos. Su uso indiscriminado convierte TypeScript en JavaScript con más caracteres de escritura.

// ❌ Mal: any en una función de utilidad
function procesarDatos(datos: any) {
  return datos.map(d => d.nombre.toUpperCase());
}

// Runtime error si datos no es array
procesarDatos(null); // 💥

En proyectos Next.js, este patrón aparece frecuentemente en getStaticProps, getServerSideProps o al consumir APIs externas.

La solución

Usá unknown para datos que no controlás y validá en runtime con type guards o bibliotecas como Zod:

// ✅ Bien: unknown + type guard
function procesarDatos(datos: unknown): string[] {
  if (!Array.isArray(datos)) {
    throw new Error('Se esperaba un array');
  }

  return datos.every(d => typeof d?.nombre === 'string')
    ? datos.map(d => (d as { nombre: string }).nombre.toUpperCase())
    : [];
}

// ✅ Mejor aún: Zod para validación estructurada
import { z } from 'zod';

const UsuarioSchema = z.object({
  nombre: z.string(),
  edad: z.number().optional(),
});

const UsuariosResponseSchema = z.array(UsuarioSchema);

async function cargarUsuarios() {
  const res = await fetch('/api/usuarios');
  const datos: unknown = await res.json();

  // Validación en runtime con tipos inferidos
  const usuarios = UsuariosResponseSchema.parse(datos);

  // TypeScript conoce el tipo exacto: { nombre: string; edad?: number }[]
  return usuarios.map(u => u.nombre.toUpperCase());
}

Zod genera tipos derivados que se sincronizan automáticamente con la validación. No hay lugar para as forzados ni any ocultos.

2. Type assertions (as) sin validación

El problema

Las assertions le dicen a TypeScript "confiá en mí, sé lo que hago". El problema es que habitualmente no sabemos lo que hacemos.

// ❌ Mal: assertion riesgosa en un componente React
interface Props {
  usuario: { nombre: string; rol: 'admin' | 'usuario' };
}

function PerfilUsuario({ usuario }: Props) {
  const datos = localStorage.getItem('config');
  const config = JSON.parse(datos!) as { tema: string }; // ¿Y si es null?

  return <div className={config.tema}>{usuario.nombre}</div>;
}

La solución

Definí tipos explícitos para datos externos y validá nullability:

// ✅ Bien: tipo explícito y manejo de null
interface Configuracion {
  tema: 'claro' | 'oscuro';
}

function PerfilUsuario({ usuario }: Props) {
  const datos = localStorage.getItem('config');

  if (!datos) return <div>Sin configuración</div>;

  let config: Configuracion;
  try {
    const parseado: unknown = JSON.parse(datos);
    if (
      typeof parseado === 'object' &&
      parseado !== null &&
      'tema' in parseado &&
      ['claro', 'oscuro'].includes((parseado as Record<string, unknown>).tema)
    ) {
      config = parseado as Configuracion;
    } else {
      throw new Error('Configuración inválida');
    }
  } catch {
    return <div>Configuración corrupta</div>;
  }

  return <div className={config.tema}>{usuario.nombre}</div>;
}

Para escenarios más limpios, considerá usar Result types o bibliotecas como neverthrow.

3. Tipado pobre de eventos en React

El problema

Usar any o tipos genéricos para eventos del DOM pierde información valiosa y autocompletado.

// ❌ Mal: evento sin tipar
function FormularioSuscripcion() {
  const handleSubmit = (e: any) => {
    e.preventDefault(); // Funciona, pero sin autocompletado ni seguridad
    const email = e.target.email.value; // any implícito
  };

  return (
    <form onSubmit={handleSubmit}>
      <input name="email" />
    </form>
  );
}

La solución

React exporta tipos específicos para cada tipo de evento DOM:

// ✅ Bien: eventos tipados correctamente
import { FormEvent, ChangeEvent, useState } from 'react';

function FormularioSuscripcion() {
  const [email, setEmail] = useState('');

  const handleSubmit = (e: FormEvent<HTMLFormElement>) => {
    e.preventDefault();

    // TypeScript conoce e.currentTarget como HTMLFormElement
    const formData = new FormData(e.currentTarget);
    const emailValue = formData.get('email') as string;

    console.log('Suscribir:', emailValue);
  };

  const handleChange = (e: ChangeEvent<HTMLInputElement>) => {
    // e.target es HTMLInputElement con todas sus propiedades
    setEmail(e.target.value);
  };

  return (
    <form onSubmit={handleSubmit}>
      <input
        name="email"
        type="email"
        value={email}
        onChange={handleChange}
        required
      />
      <button type="submit">Suscribirse</button>
    </form>
  );
}

React tipa eventos con un generic para el elemento específico: MouseEvent<HTMLButtonElement>, KeyboardEvent<HTMLInputElement>, etc. Aprovechalo.

4. No aprovechar el inference de useState

El problema

Tipar estados de forma redundante o demasiado permisiva genera uniones complejas o perdemos precisión.

// ❌ Mal: tipado excesivamente amplio
const [usuario, setUsuario] = useState<any>(null);
const [cargando, setCargando] = useState<boolean>(false); // Redundante
const [datos, setDatos] = useState<Array<object>>([]); // object es casi any

La solución

// ✅ Bien: interfaces explícitas, inference cuando aplica
interface Usuario {
  id: number;
  nombre: string;
  email: string;
}

// Inferencia automática de boolean, no hace falta anotar
const [cargando, setCargando] = useState(false);

// Tipo explícito para null inicial
const [usuario, setUsuario] = useState<Usuario | null>(null);

// Array tipado, no genérico object
const [usuarios, setUsuarios] = useState<Usuario[]>([]);

// Uso seguro con narrowing
if (usuario) {
  console.log(usuario.nombre); // string, sin optional chaining necesario
}

Regla práctica: si el valor inicial permite inferir el tipo completo, no anotés. Si hay null o uniones, anotá explícitamente.

5. Componentes con props mal definidas

El problema

Props opcionales mal manejadas, children sin tipar, o forwarding de props que pierde información.

// ❌ Mal: props con demasiados opcionales y sin children tipado
interface CardProps {
  titulo?: string;
  contenido?: string;
  onClick?: Function; // ¡Evita Function!
  style?: any;
}

La solución

// ✅ Bien: Props con intención clara, extends de HTMLAttributes
import { ReactNode, ButtonHTMLAttributes, forwardRef } from 'react';

// Componente con children y props específicas
interface CardProps {
  titulo: string;
  contenido: string;
  children?: ReactNode; // Acepta cualquier nodo React válido
  accionSecundaria?: ReactNode;
}

function Card({ titulo, contenido, children, accionSecundaria }: CardProps) {
  return (
    <article className="card">
      <h2>{titulo}</h2>
      <p>{contenido}</p>
      <div className="card-body">{children}</div>
      {accionSecundaria && (
        <footer>{accionSecundaria}</footer>
      )}
    </article>
  );
}

// ✅ Forwarding de props nativas con preservación de tipos
interface BotonProps extends ButtonHTMLAttributes<HTMLButtonElement> {
  variant?: 'primario' | 'secundario' | 'peligro';
  isLoading?: boolean;
}

const Boton = forwardRef<HTMLButtonElement, BotonProps>(
  ({ variant = 'primario', isLoading, children, disabled, ...rest }, ref) => {
    return (
      <button
        ref={ref}
        className={`btn btn-${variant}`}
        disabled={disabled || isLoading}
        {...rest} // Todas las props de button nativo funcionan con tipado
      >
        {isLoading ? 'Cargando...' : children}
      </button>
    );
  }
);

Boton.displayName = 'Boton';

forwardRef con sus generics preserva la referencia al elemento DOM y mantiene el autocomplete de todas las props nativas. No lo evités por pereza de tipar.

6. Types vs Interfaces: confusión y inconsistencia

El problema

Mezclar ambas sin criterio, o usar type cuando interface ofrece ventajas concretas en el ecosistema React.

// ❌ Mal: type para todo, sin aprovechar merging ni performance
type Props = {
  // ...
};

type Response = Record<string, any>; // Obscurece la estructura

La solución

Seguí convenciones claras:

// ✅ Interfaces para estructuras que pueden extenderse
interface ApiResponse<T> {
  datos: T;
  meta: {
    pagina: number;
    totalPaginas: number;
  };
}

interface UsuarioResponse extends ApiResponse<Usuario[]> {
  incluyePerfilExtendido: boolean;
}

// ✅ Types para unions y derived types
type EstadoCarga = 'idle' | 'cargando' | 'exito' | 'error';

type UsuarioConPermisos = Usuario & {
  permisos: string[];
};

// ✅ Type helper para inferir el éxito de una promesa
type TipoApiUsuario = Awaited<ReturnType<typeof cargarUsuario>>;

Las interfaces permiten declaration merging, útil para extender módulos de terceros. Además, el error en interfaces es localizable más rápido en equipos grandes.

7. Ignorar el strict mode de TypeScript

El problema

Mantener strict: false en tsconfig.json por "comodidad" deja pasar errores que el compilador detectaría.

// ❌ tsconfig.json permisivo
{
  "compilerOptions": {
    "strict": false,
    "noImplicitAny": false,
    "strictNullChecks": false
  }
}

La solución

// ✅ tsconfig.json para proyectos React/Next.js
{
  "compilerOptions": {
    "target": "ES2020",
    "lib": ["ES2020", "DOM", "DOM.Iterable"],
    "jsx": "preserve",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "resolveJsonModule": true,
    "strict": true,
    "noUnusedLocals": true,
    "noUnusedParameters": true,
    "noFallthroughCasesInSwitch": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "declaration": true,
    "declarationMap": true,
    "sourceMap": true,
    "baseUrl": ".",
    "paths": {
      "@/*": ["./src/*"],
      "@/components/*": ["./src/components/*"]
    }
  },
  "include": ["src/**/*", "*.ts", "*.tsx"],
  "exclude": ["node_modules", ".next", "dist"]
}

Activá strict desde el inicio del proyecto. Migrar un codebase existente es técnica y políticamente costoso.

8. Next.js: mal tipado de data fetching

El problema

En Next.js App Router y Pages Router, los datos de servidor frecuentemente se pasan sin tipar o con any implícito.

// ❌ Mal: Page sin tipar params ni searchParams
export default async function PaginaUsuario({ params }) {
  const { id } = params; // any
  const usuario = await obtenerUsuario(id);

  return <Perfil usuario={usuario} />;
}

La solución

// ✅ App Router: tipado explícito de segmentos dinámicos
import { notFound } from 'next/navigation';

interface PageProps {
  params: Promise<{ id: string }>;
  searchParams: Promise<{ [key: string]: string | string[] | undefined }>;
}

export default async function PaginaUsuario({ params }: PageProps) {
  const { id } = await params;

  // Validación de formato
  if (!/^\d+$/.test(id)) {
    notFound();
  }

  const usuario = await obtenerUsuario(parseInt(id, 10));

  if (!usuario) {
    notFound();
  }

  return <Perfil usuario={usuario} />;
}

// ✅ Pages Router: tipado de GetServerSideProps
import { GetServerSideProps, InferGetServerSidePropsType } from 'next';

interface ServerProps {
  usuarios: Usuario[];
  timestamp: number;
}

export const getServerSideProps: GetServerSideProps<ServerProps> = async () => {
  const usuarios = await prisma.usuario.findMany();

  return {
    props: {
      usuarios,
      timestamp: Date.now(),
    },
  };
};

// Tipo inferido del return de getServerSideProps
export default function PaginaUsuarios({
  usuarios,
  timestamp,
}: InferGetServerSidePropsType<typeof getServerSideProps>) {
  return (
    <main>
      <p>Datos de: {new Date(timestamp).toLocaleString()}</p>
      <ListaUsuarios usuarios={usuarios} />
    </main>
  );
}

Next.js provee tipos oficiales para cada patrón de data fetching. Usalos: InferGetStaticPropsType, InferGetServerSidePropsType, AppRouterInstance, etc.

Conclusión

TypeScript aporta valor cuando se usa con disciplina, no cuando se satisface al compilador con atajos. Los errores que vimos comparten una raíz común: preferir velocidad aparente sobre seguridad real.

Revisá tu codebase actual: buscá any, as sin validación, y strict: false. Cada instancia que eliminás es un bug de producción que nunca sucederá.

Las herramientas modernas —Zod, los tipos de React 18+, el App Router de Next.js— hacen que escribir TypeScript correcto sea más fácil que justificar los atajos. La inversión inicial se paga con intereses en el debugueo y el onboarding de nuevos desarrolladores.