Skip to main content
Multiple migration options are available to upgrade your legacy app to version 2025.2 of the developer platform, based on the type of your legacy app, whether the app was already using the projects framework, as well as the existing functionality your app is leveraging.

Developer Platform Basics

The sections below provide guidance on auditing your app’s configuration, along with how to use that information to determine the best option available to migrate your app to the latest version of the developer platform.

​
Audit your existing app configuration

Your potential migration path depends on several factors:
  • Which version of the projects framework your app is on (if any)
  • Whether your app is private or public
  • Whether your app is using serverless functions
  • The number of HubSpot accounts your app is installed in (if applicable)

​
Check your legacy app type and project framework version

If you’re not sure whether your legacy app is public or private, you can check its type in your development settings:
  • In your HubSpot account, navigate to Development.
  • In the left sidebar menu, click Legacy apps.
  • Locate your app in the list, using the search bar or the Filter by app type dropdown menu to filter apps in the list.
  • Confirm your app’s Type and whether it’s already on the projects framework.
Confirm legacy app in your HubSpot account for migration purposes
If your app is using the projects framework, you can also identify the version of the framework your app is using by checking the platformVersion field in your project’s hsproject.json file. 
{
  "name": "my_project",
  "srcDir": "src",
  "platformVersion": "2025.2"
}
  • If you’re already on version 2025.2, your app is on the current version and no migration is necessary.
  • If you’re on version 2025.1, you need to migrate your app by August 1, 2026.
If your app doesn’t have a hsproject.json file, it’s not on the projects framework and you can use the hs app migrate command, subject to a few considerations outlined in the diagram below.

​
Confirm serverless function usage

If your legacy app is on the projects framework and you’re leveraging serverless functions, some restrictions currently apply to the migration process. To check whether your app is actively using serverless functions, confirm both of the following:
  • The src/app/app.functions/ directory exists within your project.
  • At least one entry exists in the appFunctions property in your hsproject.json file.
my-project-folder
hsproject.json
src
app
app.json
app.functions
example-function.js
package.json
serverless.json

​
Check public app installs

If your legacy app isn’t on the projects framework, you can migrate using the hs app migrate command, subject to whether your app is public and the number of active installs. To check your public app’s number of active installs:
  • In your HubSpot account, navigate to Development.
  • In the left sidebar menu, click App listings.
  • Locate your app, then check the Installs column for the number of installs.
Confirm number of legacy public app installs for migration purposes
  • If your public app is already listed on the marketplace, you can proceed with migration without any prerequisite actions required.
  • If your public app isn’t listed on the marketplace, but it’s installed in at least 10 different HubSpot accounts, you’ll need to list your app on the marketplace first, then proceed with migration.

​
Review your app migration options

After confirming your app configuration details from the sections above, consult the paths detailed in the tabs below based on whether your app is already on the projects framework:

​
Next steps

After you’ve reviewed your migration path options above, you can proceed with migration by following one of the resources below:
Last modified on February 20, 2026