Decisiones de Refactoring en React y TypeScript

Una lista de los refactors más comunes que valen la pena en código real de React y TypeScript - cada uno con una etiqueta en negrita, una rationale de una sola oración y un ejemplo breve antes/después. Úsalo como una pre-checklist de PR, una referencia de revisión de código, o una auditoría de búsqueda de anti-patrones en un codebase existente.

Cómo usar esta lista

• Recorre cada elemento; si un patrón coincide, abre un PR pequeño y con alcance por decisión.
• Prefiere pequeños refactors pareados con el trabajo de feature que los expone - no reescrituras big-bang.
• Mantén el diff "antes" en la descripción del PR para que los revisores vean el smell que eliminaste.

Decisiones de Refactoring

1. Extrae valores mágicos a constantes nombradas - Reemplaza literales dispersos con una única fuente de verdad para que los ajustes no requieran un grep-and-pray en todo el repo.

   // before
   if (retries < 3) retry();
   // after
   const MAX_RETRIES = 3;
   if (retries < MAX_RETRIES) retry();

2. Reemplaza any con unknown y estrecha - Fuerza a los llamadores a probar la forma antes de usarla, capturando suposiciones malas en el límite en lugar de profundo en la UI.

   // before
   function parse(data: any) { return data.items.map(...); }
   // after
   function parse(data: unknown) {
     if (!isPayload(data)) throw new Error("bad payload");
     return data.items.map(...);
   }

3. Prefiere uniones discriminadas sobre props opcionales - Hace que estados imposibles sean no representables para que TypeScript rechace loading: true con data: Foo en tiempo de compilación.

   // before
   type State = { loading: boolean; data?: Foo; error?: Error };
   // after
   type State =
     | { status: "loading" }
     | { status: "success"; data: Foo }
     | { status: "error"; error: Error };

4. Extrae efectos repetidos en un hook personalizado - Seca la lógica transversal (polling, suscripciones, trampas de foco) y la hace unit-testeable en aislamiento.

   // before
   useEffect(() => {
     const id = setInterval(fetchStatus, 5000);
     return () => clearInterval(id);
   }, []);
   // after
   usePolling(fetchStatus, 5000);

5. Reemplaza prop drilling con context o una store - Elimina props pass-through de componentes que no se preocupan por el valor, para que agregar un nuevo consumidor no toque las capas intermedias.

   // before
   <Page user={user}><Toolbar user={user}><Avatar user={user} /></Toolbar></Page>
   // after
   <UserProvider value={user}><Page><Toolbar><Avatar /></Toolbar></Page></UserProvider>

6. Calcula estado derivado durante el renderizado en lugar de almacenarlo - Elimina toda una clase de bugs "estos dos estados no coinciden" al hacer que la derivación sea la única fuente de verdad.

   // before
   const [items, setItems] = useState<Item[]>([]);
   const [count, setCount] = useState(0); // drifts
   // after
   const [items, setItems] = useState<Item[]>([]);
   const count = items.length;

7. Memoiza computaciones costosas con useMemo - Salta trabajo repetido en renderizados causados por estado no relacionado, convirtiendo un lag de entrada visible en retroalimentación instantánea.

   const sorted = useMemo(() => bigList.sort(compareFn), [bigList]);

8. Envuelve callbacks en useCallback solo cuando se pasan a hijos memoizados - Mantiene los límites React.memo estables para que los descendientes salten re-renderizados en lugar de romper su memoización.

   const onSelect = useCallback((id: string) => setSelected(id), []);
   return <MemoizedList onSelect={onSelect} />;

9. Divide componentes grandes por responsabilidad - Reduce el alcance del re-renderizado y el alcance de revisión para que un cambio en el header no cause un diff en el footer.

   // before: 400-line <Dashboard /> doing header, filters, table, pagination
   // after
   <Dashboard><Header /><Filters /><Table /><Pagination /></Dashboard>

10. Reemplaza useState enredado con useReducer - Centraliza transiciones relacionadas en una función para que los invariantes se puedan aplicar en lugar de dispersos en los handlers.

    const [state, dispatch] = useReducer(cartReducer, initialCart);
    dispatch({ type: "add", item });

11. Convierte componentes de clase a componentes de función - Desbloquea hooks, bundles más pequeños, y patrones modernos como Suspense y Server Components.

    // before
    class Timer extends React.Component { /* lifecycle methods */ }
    // after
    function Timer() { useEffect(() => { /* ... */ }, []); return <span /> }

12. Usa as const para inferencia literal - Fija valores de string y array a sus tipos literales exactos para que fluyan a través de genéricos en lugar de ampliarse a string.

    // before
    const roles = ["admin", "user"];        // string[]
    // after
    const roles = ["admin", "user"] as const; // readonly ["admin", "user"]

13. Reemplaza enum con una unión de objeto as const - Produce mejor tree-shaking, JSON más amigable, y tipos más claros sin los quirks de runtime de TypeScript enum.

    // before
    enum Status { Open, Closed }
    // after
    const Status = { Open: "open", Closed: "closed" } as const;
    type Status = (typeof Status)[keyof typeof Status];

14. Eleva tipos compartidos a un módulo dedicado - Previene drift de tipos cuando la misma forma se redeclara en tres componentes con campos ligeramente diferentes.

    // src/types/user.ts
    export interface User { id: string; email: string; roles: Role[] }

15. Usa satisfies para validar sin ampliar - Mantiene el tipo inferido estrecho mientras aún verificas que el valor se conforme, para que el autocomplete se mantenga agudo.

    const routes = {
      home: "/",
      admin: "/admin",
    } satisfies Record<string, `/${string}`>;

16. Reemplaza keys de índice de array con IDs estables - Arregla bugs de reorden, pérdida de foco de input, y glitches de animación causados por React reutilizando el nodo DOM incorrecto.

    // before
    items.map((item, i) => <Row key={i} {...item} />)
    // after
    items.map((item) => <Row key={item.id} {...item} />)

17. Reemplaza fetches con useEffect con TanStack Query (o SWR) - Obtén caching, deduplicación, retries, y cancellación de solicitudes gratis, eliminando docenas de líneas de boilerplate de loading/error.

    const { data, isLoading } = useQuery({ queryKey: ["user", id], queryFn: () => fetchUser(id) });

18. Valida datos externos con Zod en el límite - Convierte crashes "undefined is not a function" profundos en la UI en un único y explícito parse failure en el borde.

    const User = z.object({ id: z.string(), email: z.string().email() });
    const user = User.parse(await res.json());

19. Divide un mega-context en contexts dirigidos - Detiene que cada consumidor se re-renderice cuando un slice no relacionado cambia, convirtiendo una app lenta en una snappy.

    <AuthProvider>
      <ThemeProvider>
        <CartProvider>{children}</CartProvider>
      </ThemeProvider>
    </AuthProvider>

20. Coloca state junto al componente que lo posee - Reduce el alcance del razonamiento y hace que la eliminación sea trivial cuando la feature desaparece.

    // before: modal open state in a global store
    // after: useState inside <Modal /> itself
    const [open, setOpen] = useState(false);

21. Reemplaza sopa de boolean-prop con una unión variant - Elimina combinaciones imposibles como primary && danger && outline en el nivel de tipo.

    // before
    <Button primary danger outline />
    // after
    <Button variant="danger-outline" />

22. Extrae lógica de forma en react-hook-form + Zod - Elimina la turbulencia de input controlado, centraliza validación, y hace la forma declarativa en lugar de imperativa.

    const form = useForm<FormValues>({ resolver: zodResolver(Schema) });
    <input {...form.register("email")} />

23. Reemplaza ternarios anidados con early returns - Aplana branching para que el happy path lea de arriba a abajo sin sostener un parse tree en tu cabeza.

    // before
    return loading ? <Spinner /> : error ? <Error /> : data ? <View data={data} /> : null;
    // after
    if (loading) return <Spinner />;
    if (error) return <Error />;
    if (!data) return null;
    return <View data={data} />;

24. Convierte ops DOM imperativas a state declarativo - Se alinea con el modelo mental de React para que los re-renderizados no puedan accidentalmente deshacer una mutación manual de DOM.

    // before
    useEffect(() => { ref.current!.classList.add("open"); }, [open]);
    // after
    <div className={open ? "open" : ""} />

25. Usa optional chaining y nullish coalescing - Reemplaza guard pyramids con una sola expresión que aún maneja explícitamente los casos null/undefined.

    // before
    const name = user && user.profile && user.profile.name ? user.profile.name : "guest";
    // after
    const name = user?.profile?.name ?? "guest";

26. Mueve UI estática a un Server Component - Envía menos JavaScript al cliente y mantiene data-fetching cerca de la fuente sin una roundtrip de hidratación.

    // app/page.tsx (Server Component by default in App Router)
    export default async function Page() {
      const posts = await db.posts.findMany();
      return <PostList posts={posts} />;
    }

27. Lazy-carga rutas y widgets pesados - Mantiene el bundle inicial pequeño para que la primera pintura interactiva no espere en una librería de gráficos que el usuario puede nunca abrir.

    const Chart = lazy(() => import("./Chart"));
    <Suspense fallback={<Spinner />}><Chart /></Suspense>

28. Reemplaza React.FC con un tipo de prop explícito - Te da control sobre el contrato children y coincide con el consenso comunitario actual sobre tipado de componentes.

    // before
    const Card: React.FC<{ title: string }> = ({ title, children }) => <div>{title}{children}</div>;
    // after
    function Card({ title, children }: { title: string; children?: React.ReactNode }) {
      return <div>{title}{children}</div>;
    }

29. Envuelve subárboles riesgosos en un error boundary - Aísla el radio de blast para que un gráfico roto no derribe todo el dashboard.

    <ErrorBoundary fallback={<ChartError />}>
      <Chart />
    </ErrorBoundary>

30. Suelta banderas de loading pareando Suspense con una librería de datos - Elimina ramas isLoading a favor de un único fallback boundary, permitiendo a los componentes asumir que los datos están presentes.

    <Suspense fallback={<Skeleton />}>
      <UserProfile id={id} />   {/* reads data via `use` or a suspending query */}
    </Suspense>

Aplicando la lista en orden

• Tier de tipos (2, 3, 12-15, 28): ganancias baratas en tiempo de compilación - coloca estas primero; desbloquean refactors más seguros aguas abajo.
• Tier de render-correctness (6, 10, 16, 23, 24): elimina clases de bugs, no solo ruido - prioriza en cualquier componente que haya registrado regresiones.
• Tier de rendimiento (7-9, 19, 26, 27, 30): solo después de una medición real - no especules; perfilacea primero.
• Tier de datos (17, 18, 30): usualmente la ganancia más grande de un solo PR en codebases legacy - apunta a una área a la vez.
• Tier de estructura (1, 4, 5, 11, 20, 21, 22, 25, 29): se coloca junto con el trabajo de feature; resiste la tentación de agruparlas en un mega-refactor PR.

Gotchas

• Refactoring sin tests - Las extracciones puras de render son seguras; los movimientos de lógica no. Arreglo: coloca un test de characterización antes de tocar comportamiento.
• Memoización prematura - useMemo/useCallback en todas partes agrega ruido sin ganancias medibles. Arreglo: solo memoiza después de un profiler trace o cuando un downstream React.memo depende de estabilidad referencial.
• Mega-PR refactors - Un "cleanup PR" con 40 archivos es unreviewable y conflict-prone. Arreglo: una decisión por PR, stacked si es necesario.
• Refactor para features futuras - Formar código para una feature que puede nunca enviarse es sunk cost. Arreglo: refactor el minuto antes de que la feature aterrice, no semanas antes.
• Type-only refactors persiguiendo 100% strictness - Reemplazar cada any de una sola vez crea diffs enormes sin cambio de comportamiento. Arreglo: habilita banderas strict incrementalmente y corrige drift en el límite del módulo.

Alternativas

FAQs

Relacionado

• React Architecture Decision Checklist - Decisiones de nivel de stack que preceden refactors de nivel de código.
• React Architecture Gotchas & Common Mistakes - Anti-patrones arquitectónicos que esta lista te ayuda a refactor out.
• TypeScript + React - Dives más profundos en los patrones de tipado referenciados arriba.
• React Fundamentals Best Practices - Reglas de nivel de componente a las que se alinean los refactors aquí.