@hubspot/npm-scripts

@hubspot/npm-scripts

A collection of scripts for internal HubSpot npm package development and management.

Tools

Package Linking Tool (hubspot-linking)

The linking tool helps manage symlinked HubSpot packages in your development environment. It provides an interactive way to link and unlink local copies of @hubspot packages.

Usage

It can be used via npx

npx @hubspot/npm-scripts hubspot-linking

Or installed as a part of the project and used in the package.json

{
  "dependencies": {
    "@hubspot/npm-scripts": "latest"
  },
  "scripts": {
    "local-link": "hubspot-linking"
  }
}

Prerequisites

• Run yarn link from inside the local copy of any HubSpot package you want to make available for linking
• The tool looks for packages in ~/.config/yarn/link/@hubspot/

What it does

• Scans your project's node_modules/@hubspot directory for currently linked packages
• Lists all available packages that can be linked (from your yarn link directory)
• Presents a checkbox interface to select which packages to link/unlink
• Automatically handles linking selected packages and unlinking deselected ones
• Runs yarn install --force to ensure dependencies are properly resolved

Release Script Builder (buildReleaseScript)

A utility function that creates a comprehensive npm release script with support for different release tags and semantic versioning.

Usage

Create a release script file (e.g., scripts/release.ts):

import { buildReleaseScript } from '@hubspot/npm-scripts';
import path from 'path';

buildReleaseScript({
  packageJsonLocation: path.resolve('./package.json'),
  buildHandlerOptions: {
    repositoryUrl: 'https://github.com/your-org/your-repo',
    mainBranch: 'main', // optional, defaults to 'master'
    build: async () => {
      // Optional custom build function
      // If not provided, runs 'yarn build'
    },
    postLatestRelease: async () => {
      // Optional function to run after latest releases
    },
  },
});

Then add to your package.json:

{
  "scripts": {
    "release": "tsx ./scripts/release.ts release"
  },
  "publishConfig": {
    "registry": "https://registry.npmjs.org/"
  }
}

Release Commands

# Release a patch version to latest
yarn release -v=patch -t=latest

# Release a minor version to next (beta)
yarn release -v=minor -t=next

# Release an experimental version
yarn release -v=patch -t=experimental

# Dry run (test without publishing)
yarn release -v=patch -t=latest -d

Parameters

• -v, --versionIncrement: SemVer increment type (patch, minor, major, prerelease)
• -t, --tag: Release tag (latest, next, experimental)
• -d, --dryRun: Run without actually publishing

Features

• Branch protection: Ensures releases are made from the correct branch
• Version validation: Checks local version against published versions
• Interactive prompts: Confirms release details and requires 2FA codes
• Automatic tagging: Creates git tags and pushes to repository
• GitHub integration: Opens PR and release pages automatically
• Rollback support: Cleans up on failure

Repo Sync Script Builder (buildRepoSyncScript)

A utility function that creates a script to sync changes from an internal repository to a target repository (e.g., syncing internal packages to public GitHub).

Usage

Create a repo sync script file (e.g., scripts/repo-sync.ts):

import { buildRepoSyncScript } from '@hubspot/npm-scripts';

buildRepoSyncScript({
  buildHandlerOptions: {
    targetRepositoryOrg: 'https://github.com/your-org',
    targetRepositoryName: 'public-repo',
    buildCommitMessage: version =>
      `Sync changes from internal repo for version ${version}`,
    mainBranch: 'main', // optional, defaults to 'master'
    excludePatterns: [
      // optional, custom patterns to exclude from sync
      'internal-only-file.ts',
      'tests',
      'tests/**',
    ],
  },
});

NOTE: The sync script will always ignore the hs-temp-repo-sync and .git directories

Then add to your package.json:

{
  "scripts": {
    "repo-sync": "tsx ./scripts/repo-sync.ts repo-sync"
  }
}

Repo Sync Commands

# Sync changes to target repository
yarn repo-sync -v=1.0.0 --ssh-key=~/.ssh/id_rsa

# Dry run (test without pushing)
yarn repo-sync -v=1.0.0 -d

Parameters

• -v, --version: Version to label the sync branch (required)
• -d, --dryRun: Run without pushing changes
• --ssh-key: Path to SSH key for target repository operations

Features

• Branch protection: Ensures sync happens from the correct branch
• Automatic branching: Creates a sync branch in the target repository
• GitHub integration: Opens PR page automatically after push
• Cleanup support: Removes temporary directories after completion

This script supports a PUBLIC_README.md pattern that allows you to maintain an internal readme file that does not sync to the target repo. The PUBLIC_README.md file will sync into the target repo as README.md.