[bug] HubSpot CLI build fails with `npm ci` EUSAGE error and unexpected Node.js version

[lt-tim]

CLI Version

8.1.0

Node.js Version

22.21.1

Operating System

Windows 11 26200.7840

Description

When trying to upload our project to HubSpot, the build fails with errors during the npm ci step.

We have two cards in the project, and both fail with the same EUSAGE error from npm ci. Additionally, the linear_sidebar_card reports a Node.js engine warning for a Node version that I do not have installed locally.

Error Output

--- linear_main_card failed with the following error ---
[ERROR] There were errors building this component:
 - There was an unexpected error building the extension files. Please try again. Contact HubSpot support if the error keeps happening:  Error: Command failed: npm ci --ignore-scripts --no-audit --no-optional --no-fund
npm warn config optional Use `--omit=optional` to exclude optional dependencies, or
npm warn config `--include=optional` to include them.
npm warn config
npm warn config       Default value does install optional deps unless otherwise omitted.
npm warn EBADENGINE Unsupported engine {
npm warn EBADENGINE   package: 'eslint-visitor-keys@5.0.1',
npm warn EBADENGINE   required: { node: '^20.19.0 || ^22.13.0 || >=24' },
npm warn EBADENGINE   current: { node: 'v18.20.8', npm: '10.8.2' }
npm warn EBADENGINE }
npm error code EUSAGE
npm error
npm error `npm ci` can only install packages when your package.json and package-lock.json or npm-shrinkwrap.json are in sync. Please update your lock file with `npm install` before continuing.
npm error
npm error Missing: hubspot-example-extension@0.1.0 from lock file
npm error Missing: @typescript-eslint/eslint-plugin@8.56.1 from lock file
npm error Missing: eslint@9.39.3 from lock file
npm error Missing: @typescript-eslint/parser@8.56.1 from lock file
npm error Missing: jiti@2.6.1 from lock file
npm error Missing: typescript-eslint@8.56.1 from lock file...

--- linear_sidebar_card failed with the following error ---
[ERROR] There were errors building this component:
 - There was an unexpected error building the extension files. Please try again. Contact HubSpot support if the error keeps happening:  Error: Command failed: npm ci --ignore-scripts --no-audit --no-optional --no-fund
npm warn config optional Use `--omit=optional` to exclude optional dependencies, or
npm warn config `--include=optional` to include them.
npm warn config
npm warn config       Default value does install optional deps unless otherwise omitted.
npm warn EBADENGINE Unsupported engine {
npm warn EBADENGINE   package: 'eslint-visitor-keys@5.0.1',
npm warn EBADENGINE   required: { node: '^20.19.0 || ^22.13.0 || >=24' },
npm warn EBADENGINE   current: { node: 'v18.20.8', npm: '10.8.2' }
npm warn EBADENGINE }
npm error code EUSAGE
npm error
npm error `npm ci` can only install packages when your package.json and package-lock.json or npm-shrinkwrap.json are in sync. Please update your lock file with `npm install` before continuing.
npm error
npm error Missing: hubspot-example-extension@0.1.0 from lock file
npm error Missing: @typescript-eslint/eslint-plugin@8.56.1 from lock file
npm error Missing: eslint@9.39.3 from lock file
npm error Missing: @typescript-eslint/parser@8.56.1 from lock file
npm error Missing: jiti@2.6.1 from lock file
npm error Missing: typescript-eslint@8.56.1 from lock file...
--------------------------------------------------

Node Version Warning

The logs indicate the following environment:

node: v18.20.8
npm: 10.8.2

This results in the following warning:

npm warn EBADENGINE Unsupported engine {
  package: 'eslint-visitor-keys@5.0.1',
  required: { node: '^20.19.0 || ^22.13.0 || >=24' },
  current: { node: 'v18.20.8', npm: '10.8.2' }
}

However, I do not have Node 18 installed locally. My installed versions via nvm are:

nvm list

    24.12.0
    24.6.0
  * 22.21.1 (Currently using 64-bit executable)
    22.17.1
    20.19.6

Questions

1. Is the HubSpot CLI running npm ci inside its own environment or container?
2. If so, where is that environment defined or configurable?
3. Is there a way to control which Node version the HubSpot build process uses?

Steps to Reproduce

1. run hs project upload

Expected Behavior

I expected the build and deployment to complete.

Screenshots

No response

Additional Context

I've checked my system env variables for an 2nd node installation but I don't see any.

Package.json:

{
  "name": "hubspot-example-extension",
  "version": "0.1.0",
  "license": "MIT",
  "dependencies": {
    "@hubspot/ui-extensions": "latest",
    "react": "^18.2.0"
  },
  "devDependencies": {
    "@types/react": "^18.3.26",
    "@typescript-eslint/eslint-plugin": "^8.46.4",
    "@typescript-eslint/parser": "^8.46.4",
    "eslint": "^9.0.0",
    "jiti": "^2.6.1",
    "typescript": "^5.3.3",
    "typescript-eslint": "^8.46.4"
  }
}

main-card-hsmeta.json:

{
  "uid": "linear_main_card",
  "type": "card",
  "config": {
    "name": "Linear Main",
    "location": "crm.record.tab",
    "entrypoint": "/app/cards/Main.tsx",
    "objectTypes": [
      "tickets"
    ]
  }
}

sidebar-card-hsmeta.json:

{
  "uid": "linear_sidebar_card",
  "type": "card",
  "config": {
    "name": "Linear Summary",
    "location": "helpdesk.sidebar",
    "entrypoint": "/app/cards/Sidebar.tsx",
    "objectTypes": [
      "tickets"
    ]
  }
}

[joe-yeager]

Thanks for the report @lt-tim - Is this issue still happening for you? If you have a package-lock.json in your project could you try removing it and regenerating it by running npm install?

[joe-yeager]

@lt-tim - The team has a fix in for the issue and it should be resolved. Please let me know if you are experiencing the issue.