Última modificación: 11 de septiembre de 2025
La última versión (2025.2) de la plataforma para desarrolladores incorpora un nuevo marco de proyectos e implementación basado en archivos. Este marco contiene la configuración de una aplicación, sus recursos y otro código fuente. Si ya tienes una aplicación pública existente que creaste antes de inscribirte en la nueva beta de la plataforma para desarrolladores, esta guía te explicará cómo migrarla a la última versión del marco de proyectos. Antes de proceder a la migración, revisa las dos secciones siguientes sobre las funciones compatibles y las limitaciones.

​
Funciones y extensiones de la aplicación compatibles

Se incluirán en la migración todas las funciones que admitan los proyectos, incluidas:
  • Configuración de aplicación
  • Webhooks
  • Acciones de workflow personalizadas

​
Antes de comenzar

Si tu proyecto existente tiene una tarjeta con objetos personalizados conectados, confirma que tienes el permiso crm.objects.custom.read en tu aplicación antes de la migración. Para los proyectos construidos antes de la última versión de 2025.2, se podían construir tarjetas de objetos personalizadas solo con el permiso crm.schemas.custom.read necesario. En la última versión (2025.2) de la plataforma para desarrolladores, se requiere crm.objects.custom.read para que tu tarjeta acceda a los datos de objetos personalizados.

​
Limitaciones

Las siguientes funciones aún no son compatibles durante el período actual de la beta privada:
  • La compatibilidad de la integración con GitHub, que desencadena subidas y compilaciones automáticas desde GitHub, aún no está disponible. Si tu proyecto está actualmente vinculado a GitHub, asegúrate de desactivar la integración antes de comenzar la migración. Para desactivar la integración con GitHub y configurar las acciones de GitHub para automatizar CI/CD, consulta las instrucciones de este artículo.
  • Si creaste una página de configuración para tu aplicación, tendrás que refactorizar tu experiencia de configuración utilizando la nueva función de extensiones de IU. Se recomienda que tomes nota de todos los elementos de la interfaz de la versión de producción actual de tu aplicación antes de migrarla a la última versión. Una vez finalizado el proceso de migración, puedes utilizar las nuevas funciones de ampliación de la interfaz de usuario para volver a crear tu página de configuración.
  • La funcionalidad clásica de las tarjetas CRM no es compatible con las aplicaciones que utilizan la última versión de los proyectos para desarrolladores. Tendrás que refactorizar las tarjetas del CRM existentes para que utilicen el esquema de tarjetas de la aplicación.
  • La arquitectura de permisos subyacente de tu aplicación se actualizará para admitir permisos específicos de usuario más granulares. Como parte de esta transición, las nuevas instalaciones de clientes tendrán ahora un usuario de cuenta de servicio asociado creado en su cuenta, que estará vinculado a tu aplicación.
    • Ahora, cada cuenta solo recibirá un token de actualización, independientemente de cuántos usuarios individuales vuelvan a autorizar la aplicación.
    • Los endpoints de OAuth existentes que recuperan metadatos de actualización y token de acceso seguirán devolviendo el usuario que lo instaló como userId, y ahora devolverán un serviceAccountId después de migrar tu aplicación.

​
Migrar tu aplicación

Una vez que hayas revisado las consideraciones de la sección anterior, puedes proceder a migrar tu aplicación. Este proceso conservará las credenciales de autenticación originales, las funciones de la aplicación y las instalaciones de la aplicación. No se requieren cambios en el backend de tu aplicación.
  • Asegúrate de que has instalado la última versión beta de la CLI de HubSpot ejecutando el comando npm i -g @hubspot/cli@next y conéctalo a tu cuenta mediante los comandos hs auth y hs accounts use.
La CLI debe ser de la versión 7.5.4 o posterior. Puedes comprobar qué versión de la CLI tienes ejecutando hs --version.
  • Para iniciar el proceso de migración, utiliza uno de los siguientes comandos en función de la aplicación existente que vayas a migrar:
  • Si estás migrando una aplicación anterior que no es parte de un proyecto, ejecuta el siguiente comando:
hs app migrate
Si estás migrando una aplicación basada en un proyecto, ejecuta el comando hs project migrate.
  • Se te pedirá que elijas la aplicación que quieres migrar. Esto creará un nuevo proyecto en tu sistema de archivos local que contendrá una aplicación, junto con sus características que representan su estado configurado actual.
  • Tras seleccionar la aplicación, se te pedirá que confirmes los componentes que se migrarán. Asegúrate de que comprendes perfectamente el proceso de migración antes de confirmar el paso siguiente.
  • A continuación, se te pedirá que proporciones un nombre de proyecto, una ruta local al nuevo proyecto y los UID necesarios.
Los UID deben utilizarse como un identificador único para todas las funciones de tu aplicación. Una vez que se ha definido un UID para una función concreta, cambiarlo o modificarlo en compilaciones posteriores forzará a la plataforma a reconocerlo como “nuevo” o diferente de las compilaciones anteriores, lo que podría no ser la intención.
Indicaciones para migrar una aplicación existente
  • Una vez confirmes los detalles de tu proyecto, el proceso de migración realizará automáticamente las siguientes acciones como una única operación:
    • Crea un proyecto para tu aplicación en la página Proyectos de tu cuenta, que incluya un componente de aplicación y cualquier función compatible.
    • Convierte las funciones existentes de la aplicación en archivos de código fuente, que podrás actualizar para revisar su configuración en el futuro.
    • Construye e implementa el nuevo proyecto (que se etiquetará como Compilación #1), lo que completa la asociación entre la aplicación y su proyecto. Esto conservará las credenciales de autenticación originales, las características de la aplicación y las instalaciones.
    • Descarga los archivos fuente del nuevo proyecto en el directorio local que especificaste anteriormente cuando se te pida en la terminal.
    • Si se migró un proyecto existente, mueve los archivos del directorio original src/ a archive/ y rellena /src/ con el código fuente del nuevo proyecto.
Página de detalles de la aplicación migrada en la vista de proyectos
La compilación #1 del nuevo proyecto captura el estado de configuración de la aplicación para todas las funciones compatibles como línea de base a la que puedes volver. Si es necesario, puedes revertir con seguridad cualquier cambio futuro en este proyecto (por ejemplo, agregar tarjetas de aplicación basadas en React) volviendo a desplegar la compilación #1.
Tras la migración, las características definidas en el código fuente del proyecto ya no se podrán editar a través de la interfaz de usuario de gestión de aplicaciones dentro de HubSpot, ni utilizando las anteriores API para desarrolladores. Otras funciones (por ejemplo, acciones de workflow personalizadas o eventos de cronología) seguirán manteniéndose mediante sus respectivas API.
  • Una vez completada la migración (como refleja el campo "platformVersion": "2025.2" de tu archivo hsproject.json), ya puedes empezar a desarrollar funciones nuevas o existentes, utilizando la CLI de HubSpot y los archivos de código fuente de tu proyecto.