Enable npm workspace for user project and generated code #3159

cprecioso · 2025-09-15T15:18:14Z

Closes Share dependencies through an npm workspace #3130

🎉 It's here! 🎉

This PR enables npm workspaces in the users' projects, pulling the dependencies from each folder's node_modules to a the common top-level node_modules (when possible, for most packages). This was in general easier than expected, and looks like it will be mostly transparent for our users. npm will adapt to whether the .wasp/{out,build} folders exist or not and fold them into the general dependency resolution.

Added workspaces to starters
Added workspaces to example projects
The compiler checks that package.json#workspaces exists and has the correct value
There was some complex logic in NpmDependencies to deduplicate dependencies between the user package and the framework packages. npm now takes care of this, so we don't need it.
This change does not require users to do anything different. The current https://wasp.sh/docs/project/dependencies docs are still the way to do, we're just now intelligent about it. No changes to docs.

Extra fixes that I had to do:

Update Wasp App Runner because of the behaviour of npx in workspaces (actually done in Correctly set dir to serve in wasp-app-runner #3168)
Ensure the node_modules folder is always created inside Docker (even if empty) so the instruction copying it doesn't fail.
I had to change the names of the generated packages. npm needs every package in a workspace to have a different name. The server and web-app packages have the same name whether output to .wasp/out or .wasp/build, so I made the generation change the name based on if it's dev or build: @wasp.sh/generated-{server,client}-{build,dev}. I added an issue to improve this here Unsplit .wasp/build and .wasp/out #3163

Left over:

Adding the SDK folder as a workspace too. Currently it is not necessary because we run the install and build ourselves anyways, and it is fully a dependency so the dependencies are correctly shared. Still, we should upgrade it to a workspace so we can remove the ugly file:.wasp/out/sdk dependency.
- Currently a overly-zealous resolution makes an incompatible resolution for @types/react that would make the workspace installation fail. We should review when we Migrate to React 19 #2482.

Steps / Criteria

Copied from #3130

Check Wasp behaves correctly with package.json#workspaces
Edit the starter package.json's to have the workspaces key
Check that dependencies are correctly shared
Test that dependency checking logic inside waspc still works correctly
Add a check for workspaces in the compiler
~~Adapt wasp deps command~~ not needed
Add a migration guide and documentation

cloudflare-workers-and-pages · 2025-09-17T14:06:12Z

Deploying wasp-docs-on-main with Cloudflare Pages

Latest commit:	`b15f1fb`
Status:	✅ Deploy successful!
Preview URL:	https://e4623771.wasp-docs-on-main.pages.dev
Branch Preview URL:	https://cprecioso-npm-workspaces.wasp-docs-on-main.pages.dev

View logs

cprecioso · 2025-09-18T16:32:47Z

waspc/src/Wasp/Generator/Valid/Common.hs

This file is just stuff extracted from TsConfig.hs that I also wanted to use in PackageJson.hs.

cprecioso · 2025-09-18T16:35:59Z

waspc/src/Wasp/Generator/Valid/PackageJson.hs

-getOppositePackageJsonDepedencyKey :: PackageRequirement -> Maybe String
-getOppositePackageJsonDepedencyKey = \case
+getOppositePackageJsonDependencyKey :: PackageRequirement -> Maybe String
+getOppositePackageJsonDependencyKey = \case


Just fixing a typo

-getOppositePackageJsonDepedencyKey +getOppositePackageJsonDependencyKey ^ here

cprecioso · 2025-10-28T11:33:31Z

waspc/src/Wasp/Generator/Valid/PackageJson.hs

 validateDevelopmentDependencies :: P.PackageJson -> [GeneratorError]
 validateDevelopmentDependencies packageJson =
-  concat $
+  concat


Fixing a linter warning

cprecioso · 2025-10-28T12:25:40Z

@sodic ready for re-review

Undid the validator refactor and made an smaller change for validation
When defining the globs, convert from StrongPath to regular String earlier to simplify code
Turned PackageJson.workspaces into a Set as it fits better how I'm checking it
Updated main and solved conflicts

sodic

All good!

I left a few comments with suggested changes on the messages. Please consider them.
I don't want to dwell on this for too long since we're refactoring it soon.

You don't need to ping me again before merging :)

sodic · 2025-10-28T13:04:33Z

waspc/src/Wasp/Generator/Valid/PackageJson.hs

+          [ "Wasp requires \"workspaces\" to include",
+            showSet NW.workspaceGlobs,
+            "but is missing",
+            showSet $ NW.workspaceGlobs `S.difference` definedWorkspaces,
+            "in package.json."
+          ]


Suggested change

[ "Wasp requires \"workspaces\" to include",

showSet NW.workspaceGlobs,

"but is missing",

showSet $ NW.workspaceGlobs `S.difference` definedWorkspaces,

"in package.json."

]

[ "Wasp requires package.json \"workspaces\" to include",

showSet NW.workspaceGlobs,

", but",

showSet $ NW.workspaceGlobs `S.difference` definedWorkspaces,

"is missing."

]

This sounds a little more natural. But the entire message might leave users confused (because of the arrays surrounding the output).

I recommend saying:

- Wasp requires package.json "workspaces" to include: ".wasp/build", ".wasp/out". You are missing: ".wasp/build".

sodic · 2025-10-28T13:09:45Z

waspc/src/Wasp/ExternalConfig/Npm/PackageJson.hs

    dependencies :: !DependenciesMap,
-    devDependencies :: !DependenciesMap
+    devDependencies :: !DependenciesMap,
+    workspaces :: !(Maybe (Set String))


How come we went with a set here?

This structure should mirror how the file works, not how we want it to work. So I believe this should be an array. If we need the set, we should introduce it in the processing.

sodic · 2025-10-28T13:13:33Z

waspc/src/Wasp/Generator/Valid/PackageJson.hs

+          [ "Wasp requires \"workspaces\" to be present with the value",
+            showSet NW.workspaceGlobs,
+            "in package.json."
+          ]


Suggested change

[ "Wasp requires \"workspaces\" to be present with the value",

showSet NW.workspaceGlobs,

"in package.json."

]

[ "Wasp requires package.json \"workspaces\" to be present and include values:",

showSet NW.workspaceGlobs, -- we do a comma separated list without the brackets.

]

Slighly more correct and readable I think.

Also, do we want to allow them to have extra workspaces? Perhaps it's simpler keeping it airtight for now: You must have this and only this.

I initially went for not allowing it, but Miho asked me to allow it.

cprecioso added 2 commits September 15, 2025 17:14

Unique package names

3e2f284

Add workspaces

e094a41

cprecioso self-assigned this Sep 15, 2025

cprecioso added 8 commits September 16, 2025 13:29

Snapshots

dda141b

Do not remove dependencies from the framework packages

1e8ad7d

Add package.json#workspaces check

544a5a9

Update snaphsot

7fd0290

Fix tests

c1a1da0

Merge branch 'main' into cprecioso/npm-workspaces

ac9bd17

Add changelog

a7d71d7

Add migration guide

7a6441f

cprecioso added 8 commits September 17, 2025 16:10

Fix example apps

c3883b9

Format

ca9bb9d

Update dockerfile

4ea1332

Update snaphsot

25b7e1c

Add ts-spec notice

ac348fe

Update migration guide

d4c84a9

Update package locks

636434b

Merge remote-tracking branch 'origin/main' into cprecioso/npm-workspaces

2173f34

This was referenced Sep 18, 2025

Correctly set dir to serve in wasp-app-runner #3168

Merged

Run the local version of wasp-app-runner instead of the published one #3169

Open

cprecioso added 2 commits September 18, 2025 16:00

Merge branch 'main' into cprecioso/npm-workspaces

063e210

Update wasp-app-runner version

e267c5b

cprecioso force-pushed the cprecioso/npm-workspaces branch from b2c82e8 to e267c5b Compare September 18, 2025 14:03

Add SDK note

641e6cd

cprecioso commented Sep 18, 2025

View reviewed changes

cprecioso marked this pull request as ready for review September 18, 2025 16:38

cprecioso changed the title ~~Move to npm workspaces~~ Turn the user project and the generated packages into an npm workspace Sep 18, 2025

cprecioso changed the title ~~Turn the user project and the generated packages into an npm workspace~~ Enable npm workspace for user project and the generated code Sep 18, 2025

cprecioso temporarily deployed to fly-deploy-test October 17, 2025 09:38 — with GitHub Actions Inactive

Martinsos mentioned this pull request Oct 17, 2025

Uncaught TypeError: Cannot read properties of undefined (reading 'ReactCurrentDispatcher') #3266

Closed

cprecioso mentioned this pull request Oct 27, 2025

Rework Generator's validation system #3262

Open

Merge branch 'main' into cprecioso/npm-workspaces

b15f1fb

cprecioso temporarily deployed to fly-deploy-test October 28, 2025 09:23 — with GitHub Actions Inactive

Unrefactor checks

94f32db

cprecioso had a problem deploying to fly-deploy-test October 28, 2025 11:27 — with GitHub Actions Error

cprecioso added 3 commits October 28, 2025 12:31

Wrong imports

c87bc1c

Undo change

34b0431

Undo change

78d8220

cprecioso temporarily deployed to fly-deploy-test October 28, 2025 11:32 — with GitHub Actions Inactive

cprecioso commented Oct 28, 2025

View reviewed changes

cprecioso added 3 commits October 28, 2025 12:51

Make wildcards strings

68b35a9

Use Sets for workspaces

c1c998d

Improve errors

650ce4c

cprecioso temporarily deployed to fly-deploy-test October 28, 2025 12:01 — with GitHub Actions Inactive

cprecioso added 2 commits October 28, 2025 13:15

Some formatting

e66a26d

Update ask-the-documents

4704bb4

cprecioso temporarily deployed to fly-deploy-test October 28, 2025 12:20 — with GitHub Actions Inactive

sodic approved these changes Oct 28, 2025

View reviewed changes

cprecioso added 4 commits October 28, 2025 14:37

Remove unneeded mkdir

092134c

Better error messages

dcbc7cf

Do not use a set when parsing

ee2d172

Update snapshots

180be2f

cprecioso temporarily deployed to fly-deploy-test October 28, 2025 13:56 — with GitHub Actions Inactive

Fix tests

59192e0

cprecioso temporarily deployed to fly-deploy-test October 28, 2025 14:07 — with GitHub Actions Inactive

cprecioso merged commit ce81a90 into main Oct 28, 2025
24 checks passed

cprecioso deleted the cprecioso/npm-workspaces branch October 28, 2025 14:33

Uh oh!

Enable npm workspace for user project and generated code #3159

Enable npm workspace for user project and generated code #3159

Uh oh!

Conversation

cprecioso commented Sep 15, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🎉 It's here! 🎉

Steps / Criteria

Uh oh!

cloudflare-workers-and-pages bot commented Sep 17, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Deploying wasp-docs-on-main with Cloudflare Pages

Uh oh!

cprecioso Sep 18, 2025

Choose a reason for hiding this comment

Uh oh!

cprecioso Sep 18, 2025

Choose a reason for hiding this comment

Uh oh!

cprecioso Oct 28, 2025

Choose a reason for hiding this comment

Uh oh!

cprecioso commented Oct 28, 2025

Uh oh!

sodic left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

sodic Oct 28, 2025

Choose a reason for hiding this comment

Uh oh!

sodic Oct 28, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

sodic Oct 28, 2025

Choose a reason for hiding this comment

Uh oh!

sodic Oct 28, 2025

Choose a reason for hiding this comment

Uh oh!

cprecioso Oct 28, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

cprecioso commented Sep 15, 2025 •

edited

Loading

cloudflare-workers-and-pages bot commented Sep 17, 2025 •

edited

Loading

sodic left a comment •

edited

Loading

sodic Oct 28, 2025 •

edited

Loading