SPARK-12: Move to monorepo setup by splitting Stacks Docs and Classic into NPM workspaces #1969

mukunku · 2025-08-26T14:49:06Z

Summary

This is for SPARK-12 and is being done in preparation for project SHINE.

This PR transitions the stacks classic and stacks docs projects into the npm workspaces structure. This allows several different packages to be maintained in a single monorepo, which we will need once we start bringing stacks svelte, etc into this repo.

How to Test

Testing is straightforward: Everything should work the same as it did before.

Click around the PR environment to confirm it's good
Run some npm scripts locally like tests to confirm they work
Run a local build and make some changes to confirm your local build environment behaves the same as it did before

How to Review (To be updated)

Most of the file changes in this PR are from cheese being moved around. Mainly moving the docs and lib folders into new npm workspaces. Here are a list of file changes that are not part of this simple move; I left comments on the files themselves to share my thoughts and rationale for the changes.

.github/
├─ workflows/
│  ├─ workflow.yml
.gitignore
adrs/
├─ 0001-pseudo-private-custom-properties.md
├─ 0003-monorepo.md
netlify.toml
package-lock.json
package.json
packages/
├─ stacks-classic/
│  ├─ package.json
├─ stacks-docs/
│  ├─ package.json
run-test-visual.ps1
web-test-runner.config.mjs

changeset-bot · 2025-08-26T14:49:11Z

🦋 Changeset detected

Latest commit: 699adb6

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
@stackoverflow/stacks	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

netlify · 2025-08-26T14:49:13Z

✅ Deploy Preview for stacks ready!

Name	Link
🔨 Latest commit	`699adb6`
🔍 Latest deploy log	https://app.netlify.com/projects/stacks/deploys/68bb2ef9be2cb50008d8bf46
😎 Deploy Preview	https://deploy-preview-1969--stacks.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify project configuration.

giamir

Thanks @mukunku for making great progress on this. ❤️

I have left a few comments to address. The major one is about embracing the npm workspaces cli more to avoid having to cd into packages and changing our workflows more than necessary.

The rest of the stuff is pretty minor. I have not tested yet that the publishing workflow still work as expected. I will do that in a second review after the package.json files get adjusted.

adrs/0003-monorepo.md

package.json

packages/stacks-classic/package.json

packages/stacks-docs/package.json

package.json

giamir

Thanks @mukunku

Notes from Giamir's second review pass (we can discuss and address those sync later):

Update .gitattributes to point to new location of the screenshots **/screenshots/** to make sure the files are still treated using git LFS and don’t blow up the repo
path in the test.yml workflow for uploading the regression test results should be adjusted to packages/stacks-classic/screenshots
Maintain npm start on the root package.json as a shortcut to start up the docs site quickly for development
Need to specify prettier config files also for the format script in stacks classic as well "format": "prettier --write ./lib --config ../../.prettierrc --ignore-path ../../.prettierignore"
cannot run the visual test via npm run test:visual -w packages/stacks-classic - need to specify the config file like we do in the GH workflow --config ./packages/stacks-classic/web-test-runner.config.mjs - A better solution would be actually to modify line 32 and 33 in the run-test-visual.ps1 to -v "${current_dir}/packages/stacks-classic/web-test-runner.config.mjs:/app/web-test-runner.config.mjs" -v "${current_dir}/packages/stacks-classic/web-test-runner.config.ci.mjs:/app/web-test-runner.config.ci.mjs"
jquery, list.js and docsearch.js should move as dependencies of stacks-docs (be removed from root)
We need to add a changeset with a patch release for stacks-classic and ensure that the release process still run smoothly https://github.com/changesets/changesets/blob/main/docs/adding-a-changeset.md#i-am-in-a-multi-package-repository-a-mono-repo
NIT: for build, format and lint we could use npm run <command> —workspaces —if-present syntax
NIT: we could add a test script in the root package.json in a similar fashion to what we do for lint, format and build already

mukunku · 2025-09-05T19:41:30Z

Hey @giamir , just to follow up on our discussion today: I believe I addressed all the items you mentioned in your second review. Kindly take a look and let me know how the PR looks now 🙌🏼

I additionally created the changeset file now. I didn't see any workflow that runs until the PR is merged so I guess we'll know if it works after we merge?

Finally, just wanted to share a recap of the test:visual script issue we discussed, here, for posterity:

It seems I broke the npm script locally while trying to get it to work in CI. As you mentioned when running visual tests locally the script wasn't picking up the web test runner configuration file.

The main issue as discussed is caused by the relative node_module paths in web-test-runner.config.ci.mjs

When we run a different test like a11y tests via: npm run test:a11y -w packages/stacks-classic -- --config web-test-runner.config.ci.mjs it works because the ../../node_modules path is correct in that case.

But when we run npm run test:visual -w packages/stacks-classic it fails because node_modules is in the same directory as the config files in the docker image:

Stacks/run-test-visual.ps1

Lines 15 to 20 in 2942938

    
           docker run --tty --rm -p 8000:8000 ` 
        
             -v "${current_dir}/lib:/app/lib" ` 
        
             -v "${current_dir}/screenshots:/app/screenshots" ` 
        
             -v "${current_dir}/web-test-runner.config.mjs:/app/web-test-runner.config.mjs" ` 
        
             -v "${current_dir}/web-test-runner.config.ci.mjs:/app/web-test-runner.config.ci.mjs" ` 
        
             stacks/test-visual @args

So to accommodate I had to mount the web-test-runner config files in sub-directories within the image so the paths align:

Stacks/packages/stacks-classic/run-test-visual.ps1

Lines 32 to 33 in 699adb6

    
           -v "${current_dir}/packages/stacks-classic/web-test-runner.config.mjs:/app/visual-runner/stacks-classic-runner-config/web-test-runner.config.mjs" ` 
        
           -v "${current_dir}/packages/stacks-classic/web-test-runner.config.ci.mjs:/app/visual-runner/stacks-classic-runner-config/web-test-runner.config.ci.mjs" `

I gave the path a unique name so it's not confused with existing file paths.

Consequently, I adjusted the path we pass in the test workflow:

Stacks/.github/workflows/workflow.yml

Line 42 in 699adb6

    
           command: npm run test:visual:ci -w packages/stacks-classic -- --config ./visual-runner/stacks-classic-runner-config/web-test-runner.config.ci.mjs

And locally:

Stacks/packages/stacks-classic/package.json

Line 22 in 699adb6

    
           "test:visual" : "npm run test:visual:ci -- --config ./visual-runner/stacks-classic-runner-config/web-test-runner.config.mjs",

giamir

Thanks @mukunku. Let's merge this. 🎉

I additionally created the changeset file now. I didn't see any workflow that runs until the PR is merged so I guess we'll know if it works after we merge?

Yes, that's fair.

* SPARK-8: Fix Modal Focus Issue when using Keyboard (#1963) * fix reported focus issue * Also handle case where modal has no tabbable elements * fix webpack.config.js for windows * move if check up * Create loud-suits-stare.md * fix whitespace * revert html changes * revert harder * add tests * lint * chore(new-release) (#1964) Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> * [SPARK-6] - update the notice border color for dark mode and high contrast dark mode (#1965) * Correct readme * Don't run minicssextractplugin when running locally * Revert changes * update border colour for dark mode and high contrast dark mode * Create tasty-masks-pump.md * Minor notice border style refactor * Update visual regression test images --------- Co-authored-by: Dan Cormier <[email protected]> * chore(new-release) (#1966) Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> * build(deps-dev): bump webpack from 5.99.9 to 5.101.2 (#1967) Bumps [webpack](https://github.com/webpack/webpack) from 5.99.9 to 5.101.2. - [Release notes](https://github.com/webpack/webpack/releases) - [Commits](webpack/webpack@v5.99.9...v5.101.2) --- updated-dependencies: - dependency-name: webpack dependency-version: 5.101.2 dependency-type: direct:development update-type: version-update:semver-minor ... Signed-off-by: dependabot[bot] <[email protected]> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> * SPARK-12: Move to monorepo setup by splitting Stacks Docs and Classic into NPM workspaces (#1969) * mention why we are doing this as part of project SHINE * move folders * update paths * fix docs site and visual tests script * fix a11y and unit test scripts and tweak visual regression threshold * fix workflow tests * revert ci import paths to fix tests * try older image * fix visual ci tests? * mark stacks-docs not publishable * adjust adr based on pr feedback * adjust names * address PR feedback * add missing workspace param * switch back to old script * fix netlify and a11y * fix path * try fix workflows * fix harder * PR feedback * pr feedback round 2 * move some more packages around * Create eighty-pillows-relate.md * chore(screenshots): adjust gitignore patterns excluding failed images (#1972) * chore(monorepo): follow-up tweaks post monorepo changes (#1974) * chore(git-lfs): ensure visual test baseline images are tracked by git lfs (#1978) * Fix aria-current attribute placement in sidebar widget navigation examples (#1970) * chore(new-release) (#1979) Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> * build(deps-dev): bump vite from 7.1.3 to 7.1.5 (#1980) Bumps [vite](https://github.com/vitejs/vite/tree/HEAD/packages/vite) from 7.1.3 to 7.1.5. - [Release notes](https://github.com/vitejs/vite/releases) - [Changelog](https://github.com/vitejs/vite/blob/main/packages/vite/CHANGELOG.md) - [Commits](https://github.com/vitejs/vite/commits/v7.1.5/packages/vite) --- updated-dependencies: - dependency-name: vite dependency-version: 7.1.5 dependency-type: indirect ... Signed-off-by: dependabot[bot] <[email protected]> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> --------- Signed-off-by: dependabot[bot] <[email protected]> Co-authored-by: svc_tooling <[email protected]> Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> Co-authored-by: Tavian Taylor <[email protected]> Co-authored-by: Dan Cormier <[email protected]> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> Co-authored-by: Giamir Buoncristiani <[email protected]> Co-authored-by: qheaden-stack <[email protected]>

* SPARK-8: Fix Modal Focus Issue when using Keyboard (#1963) * fix reported focus issue * Also handle case where modal has no tabbable elements * fix webpack.config.js for windows * move if check up * Create loud-suits-stare.md * fix whitespace * revert html changes * revert harder * add tests * lint * chore(new-release) (#1964) Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> * [SPARK-6] - update the notice border color for dark mode and high contrast dark mode (#1965) * Correct readme * Don't run minicssextractplugin when running locally * Revert changes * update border colour for dark mode and high contrast dark mode * Create tasty-masks-pump.md * Minor notice border style refactor * Update visual regression test images --------- Co-authored-by: Dan Cormier <[email protected]> * chore(new-release) (#1966) Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> * build(deps-dev): bump webpack from 5.99.9 to 5.101.2 (#1967) Bumps [webpack](https://github.com/webpack/webpack) from 5.99.9 to 5.101.2. - [Release notes](https://github.com/webpack/webpack/releases) - [Commits](webpack/webpack@v5.99.9...v5.101.2) --- updated-dependencies: - dependency-name: webpack dependency-version: 5.101.2 dependency-type: direct:development update-type: version-update:semver-minor ... Signed-off-by: dependabot[bot] <[email protected]> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> * SPARK-12: Move to monorepo setup by splitting Stacks Docs and Classic into NPM workspaces (#1969) * mention why we are doing this as part of project SHINE * move folders * update paths * fix docs site and visual tests script * fix a11y and unit test scripts and tweak visual regression threshold * fix workflow tests * revert ci import paths to fix tests * try older image * fix visual ci tests? * mark stacks-docs not publishable * adjust adr based on pr feedback * adjust names * address PR feedback * add missing workspace param * switch back to old script * fix netlify and a11y * fix path * try fix workflows * fix harder * PR feedback * pr feedback round 2 * move some more packages around * Create eighty-pillows-relate.md * chore(screenshots): adjust gitignore patterns excluding failed images (#1972) * chore(monorepo): follow-up tweaks post monorepo changes (#1974) * chore(git-lfs): ensure visual test baseline images are tracked by git lfs (#1978) * Fix aria-current attribute placement in sidebar widget navigation examples (#1970) * chore(new-release) (#1979) Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> * build(deps-dev): bump vite from 7.1.3 to 7.1.5 (#1980) Bumps [vite](https://github.com/vitejs/vite/tree/HEAD/packages/vite) from 7.1.3 to 7.1.5. - [Release notes](https://github.com/vitejs/vite/releases) - [Changelog](https://github.com/vitejs/vite/blob/main/packages/vite/CHANGELOG.md) - [Commits](https://github.com/vitejs/vite/commits/v7.1.5/packages/vite) --- updated-dependencies: - dependency-name: vite dependency-version: 7.1.5 dependency-type: indirect ... Signed-off-by: dependabot[bot] <[email protected]> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> * chore(docs): add readme for each workspace (#1982) * add readme's for each package * Create six-buckets-grab.md * adjust stacks classic readme a bit * don't publish changeset for private package stacks-docs (#1983) * chore(new-release) (#1985) Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> --------- Signed-off-by: dependabot[bot] <[email protected]> Co-authored-by: svc_tooling <[email protected]> Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> Co-authored-by: Tavian Taylor <[email protected]> Co-authored-by: Dan Cormier <[email protected]> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> Co-authored-by: Giamir Buoncristiani <[email protected]> Co-authored-by: qheaden-stack <[email protected]>

mention why we are doing this as part of project SHINE

5b40111

mukunku requested review from dancormier, giamir and ttaylor-stack August 26, 2025 14:49

mukunku removed request for dancormier, giamir and ttaylor-stack August 26, 2025 14:49

mukunku changed the title ~~(chore): mention why we are doing this as part of project SHINE (SPARK-12)~~ SPARK-12: Move to monorepo setup by merging Stacks Docs Aug 26, 2025

mukunku added the do-not-merge Pull requests that are in progress and should not be merged yet label Aug 26, 2025

mukunku added 2 commits August 26, 2025 11:15

move folders

aa7efad

update paths

6ea06ef

mukunku changed the title ~~SPARK-12: Move to monorepo setup by merging Stacks Docs~~ SPARK-12: Move to monorepo setup by splitting Stacks Docs and Classic into NPM workspaces Aug 27, 2025

mukunku added 6 commits August 27, 2025 11:41

fix docs site and visual tests script

618a958

fix a11y and unit test scripts and tweak visual regression threshold

3e23ac3

fix workflow tests

e5e9e6d

revert ci import paths to fix tests

4b00ef4

try older image

3d74fca

fix visual ci tests?

7e5de37

mukunku removed the do-not-merge Pull requests that are in progress and should not be merged yet label Aug 27, 2025

mukunku requested review from dancormier, giamir and ttaylor-stack August 28, 2025 17:45

giamir requested changes Aug 29, 2025

View reviewed changes

mukunku added 5 commits August 29, 2025 08:31

mark stacks-docs not publishable

de55a86

adjust adr based on pr feedback

a680403

adjust names

1c1c6dd

address PR feedback

4e3f5b7

add missing workspace param

0737ecc

mukunku added 5 commits September 4, 2025 15:45

switch back to old script

6356251

fix netlify and a11y

d8cab74

fix path

95e2061

try fix workflows

a0997c0

fix harder

c4891dc

mukunku requested a review from giamir September 4, 2025 20:45

giamir reviewed Sep 5, 2025

View reviewed changes

mukunku added 4 commits September 5, 2025 08:22

PR feedback

bc74669

pr feedback round 2

cb63c27

move some more packages around

34e631b

Create eighty-pillows-relate.md

699adb6

mukunku requested a review from giamir September 5, 2025 18:58

giamir approved these changes Sep 8, 2025

View reviewed changes

mukunku merged commit 1add86d into develop Sep 8, 2025
11 checks passed

mukunku deleted the sal/SPARK-12 branch September 8, 2025 15:07

This was referenced Sep 8, 2025

chore(new-release) #1971

Closed

chore(new-release) #1973

Closed

mukunku mentioned this pull request Sep 8, 2025

SPARK-12: Follow-up tweaks post mono-repo changes #1974

Merged

This was referenced Sep 9, 2025

chore(new-release) #1975

Closed

chore(new-release) #1976

Closed

chore(new-release) #1977

Closed

chore(new-release) #1979

Merged

mukunku mentioned this pull request Sep 12, 2025

chore(docs): add readme for each workspace #1982

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

SPARK-12: Move to monorepo setup by splitting Stacks Docs and Classic into NPM workspaces #1969

SPARK-12: Move to monorepo setup by splitting Stacks Docs and Classic into NPM workspaces #1969

Uh oh!

mukunku commented Aug 26, 2025 •

edited

Loading

Uh oh!

changeset-bot bot commented Aug 26, 2025 •

edited

Loading

Uh oh!

netlify bot commented Aug 26, 2025 •

edited

Loading

Uh oh!

giamir left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

giamir left a comment

Uh oh!

mukunku commented Sep 5, 2025

Uh oh!

giamir left a comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

SPARK-12: Move to monorepo setup by splitting Stacks Docs and Classic into NPM workspaces #1969

SPARK-12: Move to monorepo setup by splitting Stacks Docs and Classic into NPM workspaces #1969

Uh oh!

Conversation

mukunku commented Aug 26, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

How to Test

How to Review (To be updated)

Uh oh!

changeset-bot bot commented Aug 26, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🦋 Changeset detected

Uh oh!

netlify bot commented Aug 26, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview for stacks ready!

Uh oh!

giamir left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

giamir left a comment

Choose a reason for hiding this comment

Uh oh!

mukunku commented Sep 5, 2025

Uh oh!

giamir left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

mukunku commented Aug 26, 2025 •

edited

Loading

changeset-bot bot commented Aug 26, 2025 •

edited

Loading

netlify bot commented Aug 26, 2025 •

edited

Loading