Migrate an existing public app to the projects framework

​

Supported app features and extensions

• App configuration
• Webhooks
• Custom workflow actions

​

Before you get started

​

Limitations

• Support for the GitHub integration, which triggers automatic uploads and builds from GitHub, is not yet available. If your project is currently linked to GitHub, make sure you disable the integration before you begin the migration. To disable the GitHub integration and set up GitHub Actions for automating CI/CD, check out the instructions in this article.
• If you created a settings page for your app, you’ll need to refactor your settings experience using the new UI extensions feature. It’s recommended that you note all of the interface elements in the current production version of your app before migrating it to the latest version. After the migration process is complete, you can use the new UI extension features to recreate your settings page.
• The classic CRM card functionality is not supported for apps using the latest version of developer projects. You’ll need to refactor any existing CRM cards to use the app card schema instead.
• Your app’s underlying permission architecture will be updated to support more granular user-specific permissions. As part of this transition, new customer installations will now have an associated service account user created in their account, which is tied to your app.
  • Each account will now only receive one refresh token, regardless of how many individual users reauthorize the app.
  • Existing OAuth endpoints that retrieve refresh and access token metadata will still return the user who installed it as the userId, and will now return a serviceAccountId after your app is migrated.

​

Migrate your app

• Make sure you’ve installed the latest version of the HubSpot CLI by running the command npm i -g @hubspot/cli@latest and connected it to your account using hs auth and hs accounts use commands.

• To kick off the migration process, use one of the following commands based on the existing app you’re migrating:
• If you’re migrating a legacy app that’s not part of a project, run the following command:

hs app migrate

• You’ll be prompted to choose the app you want to migrate. This will create a new project in your local filesystem containing an app, along with its features that represent its currently configured state.
• After selecting the app, you’ll be prompted for confirmation of the components that will be migrated. Make sure you fully understand the migration process before confirming to the next step.
• Next, you’ll be prompted to provide a project name, a local path to the new project, and any required UIDs.

• Once you confirm the details for your project, the migration process will automatically perform the following actions as a single operation:
  • Create a project for your app in your account’s Projects page, which includes an app component and any compatible features.
  • Convert any existing features of the app to source code files, which you can update to revise their configuration in the future.
  • Build and deploy the new project (which will be labelled as Build #1), which completes the association between the app and its project. This will preserve the original auth credentials, app features, and installs.
  • Download the new project source files to the local directory you specified earlier when prompted in the terminal.
  • If an existing project was migrated, move the files from the original src/ directory to archive/ and populate /src/ with the new project source code.

• With the migration complete (as reflected by the "platformVersion": "2025.2" field in your hsproject.json file), you can now begin developing new or existing features, using the HubSpot CLI and your project’s source code files.