Migrate a CMS project to version 2025.2

If you have an existing project with CMS assets that you built using version 2023.2 or 2025.1, you can migrate it to the latest version (2025.2) using the CLI. Being on the latest version of the developer platform will allow you to package the latest app features with your CMS assets if needed. The method for migrating will depend on whether your project includes serverless functions:

If your project doesn’t include serverless functions, you can migrate using the hs project migrate command.
If your project includes one or more serverless functions, you’ll need to manually migrate the project, as the hs project migrate command doesn’t currently support serverless functions.

Migrate without serverless functions

Follow the steps below to migrate an existing project built on version 2023.2 or 2025.1 to the latest version (2025.2). Migration for projects that don’t contain a serverless function can be done through the hs project migrate command, which will update the project and its component files to use the latest schemas and configuration details. Before starting, it’s important to note that:

This command will permanently upgrade your project to platform version 2025.2, and this action cannot be undone.
The command will create an archived copy of your original theme files to ensure you have a backup.
The command will guide you through the process, and request your input when needed for required fields.

Upload your latest code to HubSpot

Ensure your latest changes are included in the migration by running hs project upload in your local project directory. If auto-deploy is turned off for the project, run hs project deploy.

hs project upload

Run the migrate command

With your latest changes in HubSpot:

Run hs project migrate in the local project directory.
The CLI will first check for eligible project components, then prompt you to proceed with the migration.
The migration script will run, and you’ll see your local files updating in real-time. Once completed, the terminal will display a message confirming that the migration was successful.

Screenshot showing the CLI confirming that the migration command successfully completed

Review your migrated files

Before uploading your updated files to HubSpot, review your project to confirm that the correct updates have been made.

In hsproject.json, the platformVersion should be 2025.2.
The src directory should now contain a new *-hsmeta.json file. The first part of the file name will match the directory containing your theme. Learn more about this file in the project schema reference documentation.
At the root of your project, you should find a new directory named archive, which contains a backup of your original theme files. You may want to move it elsewhere for safekeeping.

Upload to HubSpot

After reviewing your migrated files, run hs project upload to upload these changes to your account. If auto-deploy is turned off for the project, run hs project deploy after the upload completes.To view your updated project in HubSpot, run hs project open. A browser tab will open to the project’s home page, where you can view recent build and deploy logs, and review additional details for your project.

Screenshot of the project dashboard confirming the recent successful build and deploy

Migrate with serverless functions

If your project includes serverless functions, the migration process will be more manual, as the hs project migrate command doesn’t currently support serverless functions.

Update hsproject.json

In your hsproject.json file, update the platformVersion number to 2025.2.

hsproject.json

{
  "name":"MyCMSTheme",
  "platformVersion":"2023.2",  
  "platformVersion":"2025.2", 
  "srcDir":"src"
}

Update project structure

Platform version 2025.2 introduced an additional directory layer for CMS theme development, along with an additional configuration file in that directory.To match the new required project structure:

Add a theme directory in src/, then move your theme directory into it.

projectName/
├── hsproject.json
└── src/
  └── theme/ 
    └── your-original-theme-directory/

Within the new theme/ directory, create a *-hsmeta.json configuration file, which configures the project’s theme component (not the theme itself). You can give this file any name, but it must end with -hsmeta.json. Copy the code below into the new file, then modify it as needed.

  {
    "uid": "my-theme-uid",
    "type": "theme",
    "config": {
      "themePath": "website-theme",
      "secretNames": []
    }
  }

Field	Type	Description
`uid`	String	The unique identifier for the project’s theme component. This is separate from your theme’s display label, which is still configured in the `theme.json` file.
`type`	String	The type of component, which must be `theme` for CMS themes.
`themePath`	String	The relative path of the directory that contains the `theme.json` file (i.e., the name of the theme directory inside `src/theme/`).

Add your serverless function

To migrate your serverless functions, you’ll need to update the app and serverless function schemas, and rename the functions directory.

In the src/app/ folder, rename the app.json file to app-hsmeta.json. Then, update the file contents to match the new schema. The code block below includes tabs to compare the new schema to the old.

Note that the uid value must be unique within the project. For example, your app and your theme *-hsmeta.json files cannot have the same uid. This value should not be changed after uploading your project.

New schema
Old schema

{
  "uid": "serverless-function-app-uid",
  "type":"app",
  "config": {
    "name": "Serverless function app",
     "description": "This app runs a serverless function.",
    "distribution": "private",
    "auth": {
      "type" : "static",
      "requiredScopes": [
        "crm.objects.contacts.read",
        "crm.objects.contacts.write"
      ],
      "optionalScopes": [],
      "conditionallyRequiredScopes": []
    },
    "permittedUrls": {
      "fetch": ["https://api.hubapi.com"],
      "iframe": [],
      "img": []
    },
    "support": {
      "supportEmail": "support@example.com",
      "documentationUrl": "https://example.com/docs",
      "supportUrl": "https://example.com/support",
      "supportPhone": "+18005555555"
    }
  }
}

Next, rename the app.functions directory to functions.

projectName/
├── hsproject.json
└── src/
  └── theme/
  └── app/
    ├── app-hsmeta.json
    └── app.functions/ 
    └── functions/ 

Lastly, similar to the app schema step above, rename the serverless.json file to serverless-hsmeta.json. Then update its contents to match the new schema format, shown below.

New schema
Old schema

{
  "uid": "my-serverless-function",
  "type": "app-function",
  "config": {
    "entrypoint": "app/functions/function.js",
    "secretKeys": [],
    "endpoint": {
        "path": "fetch-quote",
        "methods": ["GET"]
    }
  }
}

Upload your project

With your project updates in place, upload your changes to your account by running hs project upload. If you have auto-deploy turned off for the project, you’ll need to run hs project deploy to then deploy it.After the upload, run hs project open to open the project in HubSpot. In the top right, you’ll see the version number now shows 2025.2.

Screenshot showing the updated version number in HubSpot

​Migrate without serverless functions

​Migrate with serverless functions

Migrate without serverless functions

Migrate with serverless functions