Migrate an existing private app to the projects framework

​

Key limitations

• If your existing private app includes serverless functions with core logic (e.g., the function transforms data that isn’t contained in the backend), you should not migrate it to the new developer platform until a full migration path is released.
  • If needed, you can always build a net-new app on version 2025.2 of the developer platform alongside your existing app.
  • Creating a project-built private app using version 2025.1 of the developer platform with serverless functions is still supported.
• Otherwise, if your serverless functions are only acting as a proxy to your backend, you can proceed with migration by following the guidance in the section below on using hubspot.fetch() after completing the previous steps in this guide.

• The HubSpot CLI migration commands are not supported for existing private apps, as automatic migration is not currently supported.
• Support for the GitHub integration, which triggers automatic uploads and builds from GitHub, is not yet available. If your existing project is currently linked to GitHub, make sure you disable the integration before you begin the migration. To disable the GitHub integration and setup GitHub Actions for automating CI/CD, check out the instructions in this article.

​

Summary of the migration process

• You’ll start by cloning your existing project so the original files can serve as a backup, then you can review each of the associated configuration files to ensure they conform to the new project schema. This will require minor updates to the names and structure of your component configuration files, as well as their respective properties.
• You’ll then update your existing top-level hsproject.json and app.json configuration files.
  • You can then follow each of the subsequent sections to update the configuration for your app components to conform to version 2025.2 of the developer platform, based on the existing features you had set up (e.g., an app card built using UI extensions).
  • Note that, with the exception of the hsproject.json file, all other configuration files follow a predictable naming scheme (*-hsmeta.json where the * is based on the specific directory or component) and all share the same top-level properties:f

{
  "uid": "example-unique-identifier",
  "type": "example-component",
  "config": {
    ...
  }
}

• After you’ve updated all the components of your cloned existing project, you’ll then upload your new project to your HubSpot developer account as part of the last step in this guide.

​

Clone your existing project configuration files

• Make sure you’ve installed the latest version of the HubSpot CLI by running the command npm install -g @hubspot/cli@latest and connected it to your account using hs account auth command. If you haven’t installed the HubSpot CLI yet, run npm install -g @hubspot/cli. You should be on v7.6.0 of the CLI before proceeding.
• Run the command below in your terminal to create a project with the boilerplate template for an app with private distribution and static auth.

hs project create --distribution private --auth static --project-base app

• Follow the prompts to provide a name and local directory to download the boilerplate project into, along with any app features.
• Open the newly created project in your preferred editor. You can then compare the project directory structure and the associated *-hsmeta.json schema files to your existing project to ensure the specifications match when applicable.

​

Changes to hsproject.json config

{
  "name": "My old private app",
  "srcDir": "src",
  "platformVersion": "2025.1"
}

{
  "name": "My new migrated app (Developer platform v2025.2)",
  "srcDir": "src",
  "platformVersion": "2025.2"
}

​

Review and update your app’s top-level schema

{
  "name": "My old private app",
  "description": "This is an example of private app on the old developer platform.",
  "scopes": ["crm.objects.contacts.read", "crm.objects.contacts.write"],
  "uid": "my-old-private-app",
  "public": false,
  "extensions": {
    "crm": {
      "cards": [
        {
          "file": "extensions/example-card.json"
        }
      ]
    }
  },
  "webhooks": {
    "files": "./webhooks/webhooks.json"
  }
}

{
  "uid": "new_developer_platform_app",
  "type": "app",
  "config": {
    "description": "Example of migrated app on the new developer platform.",
    "name": "My new migrated app (Developer platform v2025.2)",
    "distribution": "private",
    "auth": {
      "type": "static",
      "requiredScopes": ["crm.objects.contacts.read", "crm.objects.contacts.write"],
      "optionalScopes": [],
      "conditionallyRequiredScopes": []
    },
    "permittedUrls": {
      "fetch": ["https://api.example.com"],
      "iframe": [],
      "img": []
    },
    "support": {
      "supportEmail": "support@example.com",
      "documentationUrl": "https://example.com/docs",
      "supportUrl": "https://example.com/support",
      "supportPhone": "+18005555555"
    }
  }
}

• The top-level public property has been replaced with distribution and should be set to private. Note that the type sub-property of the auth field should be set to static, which will restrict installation of your app to a single account. Learn more about app distribution and authentication in the app configuration guide.
• Your app’s scopes are now specified as a sub-property of the auth field, and are split out between requiredScopes, conditionallyRequiredScopes, and optionalScopes. Learn more about specifying each of these scope types in the app configuration guide.
• You don’t need to define the top-level extensions property from your previous project, since the property is not present in the new app-hsmeta.json file. Any previously configured UI extensions (e.g., cards on the CRM record page) are managed using the cards/ directory of your project. Within that directory, card configuration details are specified in a *-hsmeta.json file, alongside the component code for your card provided in a .jsx file that’s referenced using the entrypoint property of the *-hsmeta.json file.
• You also don’t need to define over the top-level webhooks property from your previous project in the new app-hsmeta.json file, as webhooks are configured and managed using the webhooks/ directory of your project. Learn more in the migrate webhook subscriptions section below.

​

Update individual component configuration

​

Migrate CRM cards built with UI extensions

{
  "type": "crm-card",
  "data": {
    "title": "example app card",
    "uid": "example_app_card_private_static",
    "location": "crm.record.tab",
    "module": {
      "file": "example-app-card.jsx"
    },
    "objectTypes": [
      {
        "name": "contacts"
      }
    ]
  }
}

{
  "uid": "example_app_card_private_static",
  "type": "card",
  "config": {
    "name": "example app card",
    "description": "Provides detailed information about a contact or company.",
    "previewImage": {
      "file": "./full-preview.png",
      "altText": "This describes the image"
    },
    "entrypoint": "/app/cards/example-app-card.jsx",
    "location": "crm.record.tab",
    "objectTypes": ["CONTACT"]
  }
}

• The value of the type property has been changed from "crm-card" to "card".
• The uid property has been moved up from a sub-property of the data field and is now specified at the top-level of your config.
• The data property has been changed to config, which includes the following sub-properties:
  • The title property has been renamed to name.
  • A new description property allows you to provide more context around the functionality of your card. The description will appear in your app’s project settings.
  • The module property has been renamed to entrypoint and the value should now be a string that represents the path to your JSX component, relative to the root of your project (e.g., "/app/cards/example-app-card.jsx").
  • The objectTypes property has been simplified and is now an array of strings representing the object types where your card should appear (e.g., ["CONTACT", "COMPANY"]).
  • The location property remains unchanged, and can be set to crm.record.tab, crm.record.sidebar, crm.preview, or helpdesk.sidebar.

​

Migrate webhook subscriptions

{
"settings": {
      "targetUrl": "https://example.com/webhook",
      "maxConcurrentRequests": 10
    },
"subscriptions": {
      "crmObjects": [
        {
          "subscriptionType": "object.creation",
          "objectType": "contact",
          "active": true
        }
      ],
      "legacyCrmObjects": [
        {
          "subscriptionType": "contact.propertyChange",
          "propertyName": "lastname",
          "active": true
        }
      ],
      "hubEvents": [
        {
          "subscriptionType": "contact.privacyDeletion",
          "active": true
        }
      ]
}

{
  "uid": "webhooks",
  "type": "webhooks",
  "config": {
    "settings": {
      "targetUrl": "https://example.com/webhook",
      "maxConcurrentRequests": 10
    },
    "subscriptions": {
      "crmObjects": [
        {
          "subscriptionType": "object.creation",
          "objectType": "contact",
          "active": true
        }
      ],
      "legacyCrmObjects": [
        {
          "subscriptionType": "contact.propertyChange",
          "propertyName": "lastname",
          "active": true
        }
      ],
      "hubEvents": [
        {
          "subscriptionType": "contact.privacyDeletion",
          "active": true
        }
      ]
    }
  }
}

• A required uid property must be defined at the top-level of your *-hsmeta.json file, which should be given a name to differentiate it from other app features (e.g., "migrated_private_app_webhooks").
• A required type property must also be defined at the top-level of your *-hsmeta.json config and must be set to "webhooks".
• The subscriptions and settings properties remain unchanged from webhooks.json but must be moved into the config property that’s defined at the top-level of your *-hsmeta.json file.

​

Upload your project

hs project upload

​

Migrate serverless function handling

• Locate your serverless functions in the project of your existing private app in the src/app/app.functions directory.
• Copy all the relevant logic from your functions. In the example serverless function below, only line 4 would need to be copied over.

exports.main = async (context = {}) => {
  const { text } = context.parameters;

  const response = `This is coming from a serverless function!  You entered: ${text}`;

  return response;
};

• In the third-party hosting platform, paste in the logic from your previous serverless function definition, and ensure that any parameter names align. You’ll need to consult the documentation for defining serverless function on the platform you’re using.
• Copy your access token from your app’s project details page and add it as an environment variable with your third-party hosting platform so it can be referenced in your code.
• Next, you’ll need to update the permittedUrls property of your top-level app-hsmeta.json schema file to include the fetch field. The value of this field should be set to an array that includes the URL of your endpoint hosted in your third-party hosting platform.
• Then, update any references in your app card React code to call the new serverless function URL you set up. You can learn more about using hubspot.fetch() in this guide.

const { response } = await runServerless({
  name: "myFunc",
  parameters: { text: text },
});

const response = await hubspot.fetch("https://my-new-serverless-function.example.app/api/example-function.js", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ text: "hello" }),
});

​

Clean up

• In your HubSpot account, navigate to Development.
• On the Projects page, click the name of your old project.
• Click the Settings tab.
• Under Delete this project, click Delete [project name].
• Review the information in the dialog box to confirm that you’re ready to proceed. Then, enter the name of your project, and click Delete project.

​

Next steps

• Create a settings component
• Define a custom workflow action
• Manage your app in HubSpot