chore: migrate from Lerna to NX Release with Version Plans by Copilot · Pull Request #3254 · Codecademy/gamut

Copilot · 2026-01-28T18:14:21Z

Overview

Note: there are typescript type changes due to the TS upgrade in this PR, you can see them by looking at the diff urls in the alpha release comment. I made a mono PR here to test those changes.

Migrated package publishing from Lerna to NX Release with file-based versioning (Version Plans). Production releases use version plans configured in nx.json. Alpha releases use a custom NX library (gamut-release) with the NX Release programmatic API to apply prerelease versioning without git operations.

Configuration (nx.json):

Enabled Version Plans for production releases (versionPlans: true)
Configured independent versioning (projectsRelationship: "independent")
Excluded styleguide and macros packages from releases (internal-only)
Configured GitHub release creation for changelogs
Enabled source file analysis and auto project dependency updates

Alpha Release System (tools/gamut-release):

Created dedicated NX library for alpha publishing using programmatic API
Implements releaseVersion() and releasePublish() from nx/release
Features:
- Applies prerelease specifier with custom preid (e.g., alpha.abc123)
- Disables git operations (gitCommit: false, gitTag: false, stageChanges: false)
- Publishes with custom alpha tag to npm
- Generates JSON manifest of published packages with previous versions
- Uses commander for CLI argument parsing
- Uses Node.js experimental TypeScript support (--experimental-strip-types)

Workflows:

publish-production.yml: Uses nx release -y with version plans from nx.json
publish-alpha.yml: Uses nx run gamut-release:alpha --preid=alpha.{SHA} --manifest
- Enhanced PR comments with markdown table showing package, version, npm links, and diff links

Dependency Cleanup:

Removed lerna, conventional-changelog-cli, conventional-changelog-conventionalcommits
Removed lerna.json
Updated yarn.lock (reduced by ~3000 lines)

Version Plan Format:

---
gamut: minor
gamut-styles: patch
---

Add new Button variant and fix spacing issues

- Added a new "ghost" variant to the Button component
- Fixed margin spacing in the Card component

Additional Changes:

TypeScript upgraded to 5.9+ with necessary type fixes in variance/createTheme
Added ESLint rule to allow void expressions as statements
Updated README with comprehensive version plans documentation

PR Checklist

Related to designs: N/A
Related to JIRA ticket: N/A
I have run this code to verify it works
This PR includes unit tests for the code change (N/A - infrastructure change)
This PR includes testing instructions tests for the code change
The alpha package of this PR is passing end-to-end tests in all relevant Codecademy repositories

Testing Instructions

Test alpha script locally:

# Dry run to verify versioning logic
npx nx run gamut-release:alpha --preid=alpha.test123 --dryRun --manifest

# Should version all packages as prerelease with correct dependencies
# Creates alpha-publish-manifest.json with package information

Test production release (dry run):

# Create a test version plan
echo -e "---\ngamut: patch\n---\n\nTest" > .nx/version-plans/test.md

# Verify it works
npx nx release --dry-run

# Clean up
rm .nx/version-plans/test.md

In CI:

✅ Alpha builds publish on PR open/sync with tag alpha.{SHORT_SHA} (verified in comment above)
Production releases will publish on merge to main using version plans

PR Links and Envs

N/A - Infrastructure change, no application changes

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

CLAassistant · 2026-01-28T18:14:28Z

All committers have signed the CLA.

codecov · 2026-01-28T18:39:07Z

⚠️ JUnit XML file not found

The CLI was unable to find any JUnit XML files to upload.
For more help, visit our troubleshooting guide.

nx-cloud · 2026-01-28T19:05:46Z

View your CI Pipeline Execution ↗ for commit 86f8119

☁️ Nx Cloud last updated this comment at 2026-03-26 18:25:24 UTC

jakemhiller · 2026-03-20T16:14:06Z

+// This is effectively a duplicate of the `MockGamutProvider` in `gamut-tests`
+// Because gamut-tests depends on gamut-styles, it creates a circular dependency.


explanation for this duplication :/

jakemhiller · 2026-03-20T16:14:40Z

  "homepage": "https://github.com/Codecademy/gamut#readme",
  "license": "MIT",
  "main": "lib",
-  "publishConfig": {


macros is only used in the styleguide, but we were publishing it. it caused some publishing issues so i disabled that.

we should mark this as deprecated

jakemhiller · 2026-03-20T16:15:21Z

  > {
    const flatColors = flattenScale(colors);
    const { variables, tokens } = serializeTokens(
-      flatColors,


wanted to upgrade typescript for the release script, so i had to make this one type change

jakemhiller · 2026-03-20T16:33:58Z

@copilot update the PR description to reflect the current changes

- Introduced a new testUtils.tsx file to encapsulate the setupRtl function with a mock GamutProvider. - Updated AssetProvider.test.tsx and GamutProvider.test.tsx to use the new setupRtl from testUtils, improving test consistency.

- Introduced a new "verify" command in project.json to run TypeScript checks without emitting output. - Updated the createTheme function to cast flattened color scales to a more compatible type for TypeScript 5.9+, ensuring better type safety.

- Created a new version plan to address internal TypeScript upgrade issues and circular dependencies in nx related to gamut-tests. - Specified patch levels for gamut-styles and variance.

- Updated the alpha release script to destructure the `preid` from parsed arguments for improved readability. - Added an ESLint directive to disable console warnings in the script.

- Introduced a new ESLint rule to permit the use of void expressions as statements, enhancing code flexibility and adherence to coding standards.

- Introduced a new `alpha-publish-manifest.json` file to track published package versions. - Enhanced the alpha release script to support manifest generation, allowing users to specify a custom path or use the default. - Added the `commander` package for improved command-line argument parsing in the release script.

…ting - Modified the alpha publish workflow to generate a publish manifest and list published package versions using a GitHub script. - Replaced the previous shell script with a more robust JavaScript implementation that checks for the existence of the manifest and formats the output as a markdown table. - Added the `--manifest` flag to the release command to enable manifest generation.

- Updated the alpha publish workflow to generate a markdown table that includes a "Diff" column for package version comparisons. - Added links to the npm package and version pages, as well as a diff link for previous versions when available, improving visibility of changes in published packages.

- Updated the publish manifest entry to include a `previousVersion` field, allowing for better tracking of package version changes. - Modified the alpha publish workflow to generate a markdown table that now includes a "Diff" column with links to compare versions, improving visibility of changes in published packages.

…te files - Added entries for new alpha publish artifacts in .gitignore. - Updated README to reflect changes in the publishing process, including the use of version plans and CI checks. - Removed the alpha-publish-manifest.json file and automerge workflow as they are no longer needed. - Cleaned up unused workflow files and adjusted VSCode settings.

- Modified the markdown table in the alpha publish workflow to include an "npm" column with links to the npm package versions. - Adjusted the table header to reflect the new structure, improving clarity and accessibility of package version information.

- Added the @commander-js/extra-typings package to package.json and yarn.lock for improved type definitions. - Updated the import statement in main.ts to use the new typings package, enhancing type safety in the command-line interface implementation.

…ted instructions - Removed the CHANGELOG-DESCRIPTION comment tags to simplify the template. - Added a checklist item for version plan updates to ensure clarity on versioning. - Updated instructions regarding breaking changes to reference the repo README for better guidance.

… code style - Modified the markdown table in the alpha publish workflow to display package names and versions in code format, enhancing readability and clarity in the published output.

codecademydev · 2026-03-26T18:26:13Z

📬 Published Alpha Packages:

Package	Version	npm	Diff
`@codecademy/gamut`	`68.2.2-alpha.8940e8.0`	npm	diff
`@codecademy/gamut-icons`	`9.57.2-alpha.8940e8.0`	npm	diff
`@codecademy/gamut-illustrations`	`0.58.9-alpha.8940e8.0`	npm	diff
`@codecademy/gamut-kit`	`0.6.592-alpha.8940e8.0`	npm	diff
`@codecademy/gamut-patterns`	`0.10.28-alpha.8940e8.0`	npm	diff
`@codecademy/gamut-styles`	`17.13.1-alpha.8940e8.0`	npm	diff
`@codecademy/gamut-tests`	`5.3.3-alpha.8940e8.0`	npm	diff
`@codecademy/variance`	`0.26.1-alpha.8940e8.0`	npm	diff
`eslint-plugin-gamut`	`2.4.3-alpha.8940e8.0`	npm	diff

github-actions · 2026-03-26T18:27:46Z

🚀 Styleguide deploy preview ready!

Preview URL: https://69c57a9c8eed63090584a2ed--gamut-preview.netlify.app
Deploy Logs: https://app.netlify.com/projects/gamut-preview/deploys/69c57a9c8eed63090584a2ed

Copilot AI assigned Copilot and jakemhiller Jan 28, 2026

Copilot started work on behalf of jakemhiller January 28, 2026 18:14 View session

Copilot AI changed the title ~~[WIP] Update repo to use NX release for package publishing~~ chore: migrate from Lerna to NX Release with Version Plans Jan 28, 2026

Copilot AI requested a review from jakemhiller January 28, 2026 18:35

Copilot finished work on behalf of jakemhiller January 28, 2026 18:35

Copilot started work on behalf of jakemhiller January 28, 2026 18:44 View session

jakemhiller force-pushed the copilot/update-to-nx-release branch from 0bf6120 to a521830 Compare January 28, 2026 19:04

Copilot finished work on behalf of jakemhiller January 28, 2026 19:43

jakemhiller force-pushed the copilot/update-to-nx-release branch from a521830 to 85ce914 Compare January 28, 2026 19:48

This comment was marked as outdated.

Sign in to view

Copilot started work on behalf of jakemhiller January 28, 2026 19:51 View session

This comment was marked as outdated.

Sign in to view

Copilot finished work on behalf of jakemhiller January 28, 2026 20:01

Copilot started work on behalf of jakemhiller January 29, 2026 21:04 View session

Copilot AI changed the title ~~chore: migrate from Lerna to NX Release with Version Plans~~ chore: migrate to NX Release with programmatic API for alpha builds Jan 29, 2026

Copilot finished work on behalf of jakemhiller January 29, 2026 21:11

jakemhiller force-pushed the copilot/update-to-nx-release branch from ccaa986 to 3606fad Compare January 30, 2026 14:53

jakemhiller force-pushed the copilot/update-to-nx-release branch 4 times, most recently from 3d2892d to 26c082e Compare March 20, 2026 16:01

jakemhiller reviewed Mar 20, 2026

View reviewed changes

Copilot started work on behalf of jakemhiller March 20, 2026 16:34 View session

jakemhiller added 22 commits March 26, 2026 10:13

lockfile

0d21ee9

move script to an nx lib, exclude styleguide

8c71ce3

add release plan check

ceef9e5

include nx-set-shas

71185b4

Add version plan for resolving TypeScript upgrade issues

4633424

- Created a new version plan to address internal TypeScript upgrade issues and circular dependencies in nx related to gamut-tests. - Specified patch levels for gamut-styles and variance.

Refactor alpha release script to destructure parsed arguments

9a64e42

- Updated the alpha release script to destructure the `preid` from parsed arguments for improved readability. - Added an ESLint directive to disable console warnings in the script.

Add ESLint rule to allow void expressions as statements

c4364de

- Introduced a new ESLint rule to permit the use of void expressions as statements, enhancing code flexibility and adherence to coding standards.

remove dryRun

423b484

macros package doesn't need to be published

af58322

use file instead of output

73619a6

Update alpha publish workflow to format package names and versions in…

cda2460

… code style - Modified the markdown table in the alpha publish workflow to display package names and versions in code format, enhancing readability and clarity in the published output.

jsdoc

2c0a97a

jakemhiller force-pushed the copilot/update-to-nx-release branch from bb17f2d to 2c0a97a Compare March 26, 2026 14:13

dreamwasp approved these changes Mar 26, 2026

View reviewed changes

jakemhiller added 2 commits March 26, 2026 11:16

prep changelogs for new format

3b1d508

fix version plan

86f8119

jakemhiller merged commit b84e07f into main Mar 26, 2026
17 checks passed

jakemhiller deleted the copilot/update-to-nx-release branch March 26, 2026 18:25

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

chore: migrate from Lerna to NX Release with Version Plans#3254

chore: migrate from Lerna to NX Release with Version Plans#3254
jakemhiller merged 38 commits intomainfrom
copilot/update-to-nx-release

Copilot AI commented Jan 28, 2026 •

edited by jakemhiller

Loading

Uh oh!

CLAassistant commented Jan 28, 2026 •

edited

Loading

Uh oh!

codecov bot commented Jan 28, 2026 •

edited

Loading

Uh oh!

nx-cloud bot commented Jan 28, 2026 •

edited

Loading

Uh oh!

This comment was marked as outdated.

This comment was marked as outdated.

jakemhiller Mar 20, 2026

Uh oh!

jakemhiller Mar 20, 2026

Uh oh!

jakemhiller Mar 23, 2026

Uh oh!

jakemhiller Mar 20, 2026

Uh oh!

jakemhiller commented Mar 20, 2026

Uh oh!

Uh oh!

codecademydev commented Mar 26, 2026

Uh oh!

github-actions bot commented Mar 26, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

		// This is effectively a duplicate of the `MockGamutProvider` in `gamut-tests`
		// Because gamut-tests depends on gamut-styles, it creates a circular dependency.

Conversation

Copilot AI commented Jan 28, 2026 • edited by jakemhiller Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Overview

PR Checklist

Testing Instructions

PR Links and Envs

Uh oh!

CLAassistant commented Jan 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

codecov bot commented Jan 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

⚠️ JUnit XML file not found

Uh oh!

nx-cloud bot commented Jan 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

This comment was marked as outdated.

This comment was marked as outdated.

jakemhiller Mar 20, 2026

Choose a reason for hiding this comment

Uh oh!

jakemhiller Mar 20, 2026

Choose a reason for hiding this comment

Uh oh!

jakemhiller Mar 23, 2026

Choose a reason for hiding this comment

Uh oh!

jakemhiller Mar 20, 2026

Choose a reason for hiding this comment

Uh oh!

jakemhiller commented Mar 20, 2026

Uh oh!

Uh oh!

codecademydev commented Mar 26, 2026

Uh oh!

github-actions bot commented Mar 26, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

Copilot AI commented Jan 28, 2026 •

edited by jakemhiller

Loading

CLAassistant commented Jan 28, 2026 •

edited

Loading

codecov bot commented Jan 28, 2026 •

edited

Loading

nx-cloud bot commented Jan 28, 2026 •

edited

Loading