Avanzando hacia una API de JavaScript estable (Nuevos cambios en 0.80)

Traducción Beta No Oficial

Esta página fue traducida por PageTurner AI (beta). No está respaldada oficialmente por el proyecto. ¿Encontraste un error? Reportar problema →

En React Native 0.80, presentamos dos cambios significativos en la API de JavaScript de React Native: la desaprobación de las importaciones profundas y nuestra nueva API estricta de TypeScript. Estos forman parte de un esfuerzo continuo para definir con precisión nuestra API y ofrecer seguridad de tipos confiable a usuarios y frameworks.

Conclusiones rápidas:

• Desaprobación de importaciones profundas: A partir de 0.80, introduciremos advertencias de desaprobación para las importaciones profundas del paquete react-native.

• API estricta de TypeScript (opt-in): Migramos a tipos TypeScript generados desde el código fuente y una nueva línea base de API pública en TypeScript. Estos permiten una precisión de tipos más sólida y preparada para el futuro, y será un cambio de ruptura único. Opta por activarla mediante compilerOptions en el tsconfig.json de tu proyecto.

Trabajaremos con la comunidad para asegurar que estos cambios funcionen para todos, antes de habilitar la API estricta de TypeScript por defecto en una futura versión de React Native.

Qué cambia y por qué

Estamos trabajando para mejorar y estabilizar la API pública de JavaScript de React Native, es decir, lo que obtienes cuando importas 'react-native'.

Históricamente, hemos aproximado esto. React Native está escrito en Flow, pero la comunidad ha migrado en gran medida a TypeScript en el código abierto, que es como se consume y valida la API pública para compatibilidad. Nuestros tipos han sido (amorosamente) contribuidos por la comunidad, y desde entonces se han fusionado y alineado en nuestra base de código. Sin embargo, estos han dependido de mantenimiento manual y sin herramientas automatizadas, lo que introdujo lagunas de precisión.

Además, nuestra API pública de JavaScript ha estado mal definida en términos de límites de módulos; por ejemplo, las importaciones profundas internas 'react-native/Libraries/' eran accesibles por el código de la aplicación, pero podían cambiar con frecuencia al actualizar estos componentes internos.

En la versión 0.80, abordamos estos problemas desaprobando las importaciones profundas e introduciendo una opción de usuario para una nueva línea base de API generada en TypeScript. Llamamos a esto nuestra API estricta de TypeScript. En última instancia, estos son los cimientos para ofrecer una API estable de React Native en el futuro.

Desaprobación de importaciones profundas desde react-native

El cambio principal que implementamos hoy es la desaprobación del uso de importaciones profundas (RFC), con advertencias en ESLint y la consola de JavaScript. Las importaciones profundas de valores y tipos deben actualizarse a la importación raíz de react-native.

// Before - import from subpath
import {Alert} from 'react-native/Libraries/Alert/Alert';

// After - import from `react-native`
import {Alert} from 'react-native';

Este cambio reduce el área de superficie total de nuestra API de JavaScript a un conjunto fijo de exportaciones que podemos controlar y estabilizar en futuras versiones. Nuestro objetivo es eliminar estas rutas de importación en 0.82.

Comentarios sobre la API

Algunas API no se exportan en la raíz y dejarán de estar disponibles sin importaciones profundas. Tenemos un hilo de comentarios abierto y trabajaremos con la comunidad para finalizar las exportaciones en nuestra API pública. ¡Comparte tus comentarios!

No se puede evitar

Ten en cuenta que nuestro objetivo es eliminar las importaciones profundas de la API de React Native en futuras versiones, por lo que estas deberían actualizarse a la importación raíz.

Opting out of warnings

ESLint

Disable the no-deep-imports rule using overrides.

.eslintrc.js

  overrides: [
    {
      files: ['*.js', '*.jsx', '*.ts', '*.tsx'],
      rules: {
        '@react-native/no-deep-imports': 0,
      },
    },
  ]

Console warnings

Pass the disableDeepImportWarnings option to @react-native/babel-preset.

babel.config.js

module.exports = {
  presets: [
    ['module:@react-native/babel-preset', {disableDeepImportWarnings: true}]
  ],
};

Restart your app with --reset-cache to clear the Metro cache.

npx @react-native-community/cli start --reset-cache

Opting out of warnings (Expo)

ESLint

Disable the no-deep-imports rule using overrides.

.eslintrc.js

overrides: [
  {
    files: ['*.js', '*.jsx', '*.ts', '*.tsx'],
    rules: {
      '@react-native/no-deep-imports': 0,
    },
  },
];

Console warnings

Pass the disableDeepImportWarnings option to babel-preset-expo.

babel.config.js

module.exports = function (api) {
  api.cache(true);
  return {
    presets: [['babel-preset-expo', {disableDeepImportWarnings: true}]],
  };
};

Restart your app with --clear to clear the Metro cache.

npx expo start --clear

API estricta de TypeScript (opt-in)

La API estricta de TypeScript es un nuevo conjunto de tipos TypeScript en el paquete react-native, a los que puedes optar mediante tu tsconfig.json. Estamos enviando estos junto con nuestros tipos TS existentes, lo que significa que puedes elegir migrar cuando estés listo.

Los nuevos tipos:

1. Se generan directamente desde nuestro código fuente — mejorando cobertura y precisión, por lo que puedes esperar garantías de compatibilidad más sólidas.

2. Restringida al archivo índice de react-native — definiendo de manera más estricta nuestra API pública, lo que significa que no romperemos la API al realizar cambios en archivos internos.

Cuando la comunidad esté lista, la API Estricta de TypeScript se convertirá en nuestra API predeterminada en el futuro, sincronizada con la eliminación de importaciones profundas. Esto significa que es una buena idea comenzar a optar por ella ahora, ya que te preparará para la futura API estable de JavaScript de React Native.

tsconfig.json

{
  "extends": "@react-native/typescript-config",
  "compilerOptions": {
    ...
    "customConditions": ["react-native-strict-api"]
  }
}

Detalles técnicos

Esto indicará a TypeScript que resuelva los tipos de react-native desde nuestro nuevo directorio types_generated/, en lugar del anterior directorio types/ (mantenido manualmente). No es necesario reiniciar TypeScript ni tu editor.

Cambio importante: Las importaciones profundas no están permitidas

Como se mencionó anteriormente, los tipos bajo la API Estricta de TypeScript ahora solo se pueden resolver desde la ruta de importación principal 'react-native', haciendo cumplir la encapsulación de paquetes, según nuestra deprecación anterior.

// Before - import from subpath
import {Alert} from 'react-native/Libraries/Alert/Alert';

// After - MUST import from `react-native`
import {Alert} from 'react-native';

Beneficio clave

Hemos delimitado nuestra API pública a las exportaciones del archivo index.js de React Native, el cual mantenemos cuidadosamente. Esto significa que los cambios en archivos internos de nuestra base de código ya no serán cambios importantes.

Cambio importante: Algunos nombres de tipos/estructuras han cambiado

Los tipos ahora se generan desde el código fuente, en lugar de mantenerse manualmente. Al hacer esto:

• Hemos alineado las diferencias que se habían acumulado de los tipos contribuidos por la comunidad, y también aumentamos la cobertura de tipos de nuestro código fuente.

• Hemos actualizado intencionalmente algunos nombres y estructuras de tipos donde había oportunidad de simplificar o reducir ambigüedades.

Beneficio clave

Al generarse los tipos directamente del código fuente de React Native, puedes confiar en que el verificador de tipos es siempre preciso para cada versión de react-native.

Ejemplo: Símbolos exportados más estrictos

La API Linking ahora es una única interface, en lugar de dos exportaciones. Esto se aplica a varias otras APIs (ver documentación).

// Before
import {Linking, LinkingStatic} from 'react-native';

function foo(linking: LinkingStatic) {}
foo(Linking);

// After
import {Linking} from 'react-native';

function foo(linking: Linking) {}
foo(Linking);

Ejemplo: Tipos corregidos/más completos

Las definiciones de tipos manuales anteriores dejaban espacio para lagunas tipográficas. Con la generación Flow → TypeScript, estas ya no existen (y en el código fuente, se benefician de la validación adicional de Flow para código multiplataforma).

import {Dimensions} from 'react-native';

// Before - Type error
// After - number | undefined
const {densityDpi} = Dimensions.get();

Otros cambios importantes

Consulta nuestra guía detallada en la documentación que enumera todos los cambios importantes de tipos y cómo actualizar tu código.

Implementación gradual

Reconocemos que cualquier cambio importante en React Native requiere tiempo para que los desarrolladores actualicen sus aplicaciones.

Ahora — Lanzamiento opcional (0.80)

La opción "react-native-strict-api" es estable en la versión 0.80.

• Esta es una migración única. Nuestro objetivo es que aplicaciones y bibliotecas opten por participar a su ritmo durante los próximos lanzamientos.

• En cualquier modo, nada cambiará para tu aplicación en tiempo de ejecución — esto solo afecta el análisis de TypeScript.

• Además, recibiremos comentarios sobre APIs faltantes a través de nuestro hilo de feedback dedicado.

Recomendado

La API estricta de TypeScript se convertirá en nuestra API predeterminada en el futuro.

Si tienes tiempo, vale la pena probar la opción ahora en tu tsconfig.json, para preparar tu aplicación o biblioteca para el futuro. Esto evaluará inmediatamente si hay errores de tipos introducidos en tu aplicación bajo la API estricta. Puede que no haya ninguno(!) — en cuyo caso, estás listo.

Futuro — API estricta de TypeScript por defecto

En el futuro, requeriremos que todas las bases de código usen nuestra API Estricta y eliminaremos los tipos heredados.

El cronograma se basará en comentarios comunitarios. Durante al menos los próximos dos lanzamientos de React Native, la API Estricta seguirá siendo opcional.

Preguntas frecuentes (FAQs)

I'm using subpath imports today. What should I do?

Please migrate to the root 'react-native' import path.

• Subpath imports (e.g. 'react-native/Libraries/Alert/Alert') are becoming private APIs. Without preventing access to implementation files inside React Native, we can’t offer a stable JavaScript API.
• We want our deprecation warnings to motivate community feedback, which can be raised via our centralized discussion thread, if you believe we are not exposing code paths that are crucial for your app. Where justified, we may promote APIs to the index export.

I'm a library maintainer. How does this change impact me?

Both apps and libraries can opt in at their own pace, since tsconfig.json will only affect the immediate codebase.

• Typically, node_modules is excluded from validation by the TypeScript server in a React Native project. Therefore, your package's exported type definitions are the source of truth.

💡 We want feedback! As with changed subpath imports, if you encounter any integration issues with the Strict API, please let us know on GitHub.

Does this guarantee a final API for React Native yet?

Sadly, not yet. In 0.80, we've made a tooling investment so that React Native's existing JS API baseline can be accurately consumed via TypeScript — enabling future stable changes. We're formalizing the existing API you know and love.

In the future, we will take action to finalise the APIs we currently offer in core — across each language surface. API changes will be communicated via RFCs/announcements, and typically a deprecation cycle.

Why isn't React Native written in TypeScript?

React Native is core infrastructure at Meta. We test every merged change across our Family of Apps, before they hit general open source availability.

At this scale and sensitivity, correctness matters. The bottom line is that Flow offers us greater performance and greater strictness than TypeScript, including specific multi-platform support for React Native.

Agradecimientos

Estos cambios fueron posibles gracias a Iwo Plaza, Jakub Piasecki, Dawid Małecki, Alex Hunt y Riccardo Cipolleschi.

También agradecemos a Pieter Vanderwerff, Rubén Norte y Rob Hogan por su ayuda adicional y aportes.

Learn more

Watch the talk!We shared a deep dive into our motivations and the work behind the Strict TypeScript API at App.js 2025.

View on YouTube