build: setup monorepo npm workspace for dependent packages #2478

zimeg · 2026-01-26T23:00:56Z

Summary

This PR sets up workspaces for improved package management.

Requirements

I've read and understood the Contributing Guidelines and have done my best effort to follow them.
I've read and agree to the Code of Conduct.

codecov · 2026-01-26T23:01:38Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 93.09%. Comparing base (a1112e3) to head (a2205af).
⚠️ Report is 1 commits behind head on main.
✅ All tests successful. No failed tests found.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #2478      +/-   ##
==========================================
- Coverage   93.09%   93.09%   -0.01%     
==========================================
  Files          40       40              
  Lines       11240    11239       -1     
  Branches      713      713              
==========================================
- Hits        10464    10463       -1     
  Misses        764      764              
  Partials       12       12

Flag	Coverage Δ
cli-hooks	`95.23% <ø> (ø)`
cli-test	`94.79% <ø> (ø)`
oauth	`77.39% <ø> (ø)`
socket-mode	`61.87% <ø> (ø)`
web-api	`98.11% <ø> (-0.01%)`	⬇️
webhook	`96.66% <ø> (ø)`

Flags with carried forward coverage won't be shown. Click here to find out more.

🚀 New features to boost your workflow:

📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

https://docs.npmjs.com/cli/v6/commands/npm-pack

zimeg

📬 A few messages for the kind reviewers!

zimeg · 2026-01-29T04:46:59Z

.github/workflows/ci-build.yml

+      - name: Build packages
+        run: |
+          # Build packages without internal dependencies
+          npm run build --workspace=@slack/cli-hooks
+          npm run build --workspace=@slack/cli-test
+
+          # Build base dependencies
+          npm run build --workspace=@slack/logger
+          npm run build --workspace=@slack/types
+
+          # Build packages requiring base dependencies
+          npm run build --workspace=@slack/web-api
+          npm run build --workspace=@slack/webhook
+
+          # Build packages that depend on the Web API
+          npm run build --workspace=@slack/oauth
+          npm run build --workspace=@slack/rtm-api
+          npm run build --workspace=@slack/socket-mode


🗣️ note: #2482 is an example of changing dependencies between packages being resolved as expected!

In that example, changes to @slack/types are required in @slack/web-api which cause tests on matching commit f2ac218 to fail in an unchanged branch. We might hope to include these changes as part of related PRs for confident CI without updates across prereleases 🫡

This is also so much easier to read and maintain!

zimeg · 2026-01-29T04:49:43Z

.github/maintainers_guide.md


 The script places the reference markdown files in `/docs/english/reference/package-name`.

 ### 🚀 Releases


🔮 note: These steps are verbose now but I'm hoping to fast follow this change with some enhancement to the release process! For now these steps still package as expected, testing with the following:

$ npm pack --workspace=@slack/web-api --dry-run

zimeg · 2026-01-29T04:50:33Z

.github/maintainers_guide.md

📠 note: Apologies for noise in these changes, but a lot of formatting happened I fear.

zimeg · 2026-01-29T04:57:39Z

packages/oauth/package.json

    "url": "https://github.com/slackapi/node-slack-sdk/issues"
  },
  "scripts": {
-    "prepare": "npm run build",


🗣️ note: The prepare script is replaced with prepack in all packages!

This helps prevent installation and build errors between packages on an initial install. Otherwise, packages are built when dependencies are installed with the prepare script, and the oauth package requires web-api is built but these are packaged in alphabetical order. Overrides for this aren't obvious to me...

AFAICT this isn't a breaking change since the prepack script is run still when packages are installed from Git. FWIW I cannot figure out how to install packages in a monorepo with that method in both cases either 🤖

zimeg · 2026-01-29T05:01:00Z

package.json

+  "scripts": {
+    "lint": "npx @biomejs/biome check packages",
+    "lint:fix": "npx @biomejs/biome check --write packages"
+  },


🪵 note: Linting becomes a global task with impressive speeds of biome - less than 1 second for all packages.

This is a noticed change to the maintenance tasks I think, but --workspace commands are preferred for package scripts overall, which are run from the root:

$ npm run test --workspace=@slack/webhook

🌲 note: I'm so open to adding more scripts here too, but hope to keep this PR scoped to minimal improvements of workspaces to start:

Automatic dependent and deduplicated package resolution in development

Shared linting scripts

Test fixes and simplified linking related to dependencies

Let's keep this PR minimal and scoped, but we can always add more to scripts in future work!

I think a root-level npm test script would be nice to match our npm run lint. Future work!

@mwbrooks Nice callout! A shared test script sounds so amazing for testing changes that span packages 🧪 ✨

srtaalej

looking forward to using this ⭐ 🤩

mwbrooks

✅ Praise goes to @zimeg and this pull request!

Significantly simplifies the CI workflow
Centralized linting and reduced biome duplication
Dependabot tracks the root-level npm dependency

packages/cli-test/biome.json

mwbrooks · 2026-01-29T19:20:55Z

.github/workflows/ci-build.yml

+      - name: Build packages
+        run: |
+          # Build packages without internal dependencies
+          npm run build --workspace=@slack/cli-hooks
+          npm run build --workspace=@slack/cli-test
+
+          # Build base dependencies
+          npm run build --workspace=@slack/logger
+          npm run build --workspace=@slack/types
+
+          # Build packages requiring base dependencies
+          npm run build --workspace=@slack/web-api
+          npm run build --workspace=@slack/webhook
+
+          # Build packages that depend on the Web API
+          npm run build --workspace=@slack/oauth
+          npm run build --workspace=@slack/rtm-api
+          npm run build --workspace=@slack/socket-mode


This is also so much easier to read and maintain!

mwbrooks · 2026-01-29T19:21:59Z

.github/maintainers_guide.md

+
 Labels are used to run issues through an organized workflow. Here are the basic definitions:

-* `bug`: A confirmed bug report. A bug is considered confirmed when reproduction steps have been documented and the


praise: Nice find!

@mwbrooks Thanks for taking notice! The leading * can be confusing with later bold formatting and the linter I use replaces this kind!

🔗 https://github.com/artempyanykh/marksman

mwbrooks · 2026-01-29T19:25:45Z

biome.json

    "useIgnoreFile": true
-  }
+  },
+  "overrides": [


mwbrooks · 2026-01-29T19:26:41Z

package.json

+  "scripts": {
+    "lint": "npx @biomejs/biome check packages",
+    "lint:fix": "npx @biomejs/biome check --write packages"
+  },


Let's keep this PR minimal and scoped, but we can always add more to scripts in future work!

I think a root-level npm test script would be nice to match our npm run lint. Future work!

mwbrooks · 2026-01-29T19:32:03Z

.github/maintainers_guide.md


 ```sh
-npm install path/to/node-slack-sdk/packages/slack-web-api-*.tgz
+npm install path/to/node-slack-sdk/slack-web-api-*.tgz


question: Is this path correct? Or, should it include /packages/?

Suggested change

npm install path/to/node-slack-sdk/slack-web-api-*.tgz

npm install path/to/node-slack-sdk/packages/slack-web-api-*.tgz

@mwbrooks I fear the earlier change was missing the actual package path itself! But now in a monorepo setup these packages are built at the top level 🎁

zimeg

🔭 A final note on documentation before merging soon!

zimeg · 2026-01-29T20:02:04Z

.github/maintainers_guide.md

-npm run docs
+npm run docs --workspace packages/web-api


📚 note: The existence of workspaces adds more information to reference that I think is meaningful to keep, but I want to call this out as a change:

- Defined in: [src/errors.ts:13](https://github.com/slackapi/node-slack-sdk/blob/main/packages/webhook/src/errors.ts#L13) + Defined in: [packages/webhook/src/errors.ts:13](https://github.com/slackapi/node-slack-sdk/blob/main/packages/webhook/src/errors.ts#L13)

zimeg · 2026-01-29T20:08:30Z

@srtaalej @mwbrooks Huge thanks in helping bring these changes to the finish line 🏁

At least for now! We might find more improvements toward maintenance in #2483 but let's merge this now for adjacent tests of #2484!

This might also be noted as effort toward #2359 as the latest features of node and npm become encouraged 🐢 ✨

zimeg added 2 commits January 26, 2026 14:54

build: setup monorepo workspace for dependent packagings

87118a6

revert: undo package bumps

aaab8b4

zimeg self-assigned this Jan 26, 2026

zimeg added 3 commits January 26, 2026 15:08

ci: ignore prepare script when installing packagse

5601453

build: replace prepare script with prepublish only

d85e8ce

build: lint the repo instead of packages

3fdec0e

zimeg mentioned this pull request Jan 27, 2026

chore: add opt-in pre-commit lint --write hook #2475

Open

2 tasks

zimeg added 2 commits January 28, 2026 20:27

build: replace prepublishOnly script with prepack

0a444a5

https://docs.npmjs.com/cli/v6/commands/npm-pack

docs: update runbooks and maintainers guide with workspace command

37fe12b

zimeg commented Jan 29, 2026

View reviewed changes

zimeg marked this pull request as ready for review January 29, 2026 05:07

zimeg requested a review from a team as a code owner January 29, 2026 05:07

ci: update depenedencies of the monorepo on schedule

a2205af

srtaalej approved these changes Jan 29, 2026

View reviewed changes

mwbrooks changed the title ~~build: setup monorepo workspace for dependent packages~~ build: setup monorepo npm workspace for dependent packages Jan 29, 2026

mwbrooks approved these changes Jan 29, 2026

View reviewed changes

zimeg commented Jan 29, 2026

View reviewed changes

zimeg merged commit 45452bc into main Jan 29, 2026
58 checks passed

zimeg deleted the zimeg-build-workspaces branch January 29, 2026 20:11

zimeg mentioned this pull request Jan 30, 2026

docs: workspaces changes URLs to be full paths #2494

Merged

2 tasks


		The script places the reference markdown files in `/docs/english/reference/package-name`.

		### 🚀 Releases


		Labels are used to run issues through an organized workflow. Here are the basic definitions:

		* `bug`: A confirmed bug report. A bug is considered confirmed when reproduction steps have been documented and the

	npm install path/to/node-slack-sdk/slack-web-api-*.tgz
	npm install path/to/node-slack-sdk/packages/slack-web-api-*.tgz

build: setup monorepo npm workspace for dependent packages #2478

build: setup monorepo npm workspace for dependent packages #2478

Uh oh!

Conversation

zimeg commented Jan 26, 2026

Summary

Requirements

Uh oh!

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

Uh oh!

Codecov Report

Uh oh!

zimeg left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

srtaalej left a comment

Choose a reason for hiding this comment

Uh oh!

mwbrooks left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

zimeg left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

zimeg commented Jan 29, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

codecov bot commented Jan 26, 2026 •

edited

Loading