I think we should avoid "private": true. Most packages need to be published to npm to be used by WordPress Core even if they are bundled packages.

Also for me this documentation is a bit redundant compared to the README of @wordpress/build

"wpScript": false is also unnecessary.

I mostly added the "wpScript" bit because it wasn't clear to me from reading the README of @wordpress/build, sorry! I found those docs a bit brief in this regard. We also set "wpScript": false in the ui package, so I thought being explicit there might have been the intention 🤔

I think we should avoid "private": true.

If so, I think this would be good to explain in the docs, as there around 18 or so packages in the repo with "private" true.

I don't mean to be at all argumentative with my comment here! I mostly wanted to capture my own confusion in trying to follow the existing documentation. I feel a little embarrassed to say that the reason I'd like to document this part of things more clearly is that I spent quite a bit of time trying to wrap my head around it while preparing the media fields PR (#73071) and I'm still not quite sure I did it right 😅

So (perhaps selfishly), I was hoping we could have a clear section for "you want to add a private package for use within Gutenberg, but don't want it to be exposed anywhere, here's how to do that task".

@wordpress/build

Is this a new package? Or is that wp-build?

Or is that wp-build?

Yep, it's wp-build in the packages directory, but @wordpress/build in the package name that gets published to npm.

Should we update these docs instead and link to them?

Sounds good 👍

Do you want it to be bundled within a WordPress Core script or not? What does "expose mean"

Great questions, I'd love it if we can tease this apart in the docs.

I'm still not 100% sure what "bundled within a WordPress Core script" means exactly, either.

To be slightly more specific about use cases, here's a couple:

1. I want to add a media fields package, but don't (yet) want it available in npm, I simply want Gutenberg packages to be able to use it until I can stabilise the shape of the API. It also shouldn't be available from the wp global.
2. We want to introduce an image cropper package (ie. Image Cropper: add package and basic stories #72414), and wish to use it in the block-editor package, but we don't yet want to publish it to npm. Again, until we're satisfied with the API we'd like this to be private to everything outside the Gutenberg repo. And then, once stable, switch it over to public and published to npm so that it can be used elsewhere.

For both of these cases, if we make it to a major WP release and the packages don't feel ready for npm, does bundled mean that the imported code winds up in the package that imports from it?

I'm finding the nuances surrounding this hard to wrap my head around, and I feel like I probably need to spend a little more time with the wp-build package to make sure I'm following how it's all hooked together.

Let's leave this PR open for now, and if no-one beats me to it, I'm happy to continue chipping away at this next week — it'll be a nice reminder to make sure I actually understand the package relationships properly 😄

Feel free to ship this, I just want to correct that "private": true is potentially dangerous. Break core backports so it really shouldn't be the default.

I want to add a media fields package, but don't (yet) want it available in npm, I simply want Gutenberg packages to be able to use it until I can stabilise the shape of the API. It also shouldn't be available from the wp global.
We want to introduce an image cropper package (ie. #72414), and wish to use it in the block-editor package, but we don't yet want to publish it to npm. Again, until we're satisfied with the API we'd like this to be private to everything outside the Gutenberg repo. And then, once stable, switch it over to public and published to npm so that it can be used elsewhere.

For both of these, it should just be a regular package: no flags at all, public npm package. It's the default case basically, it's like you're building an external npm package but you still want it to be published otherwise the packages that rely on it won't be able to be added as dependencies in core. (they'll have missing dependencies in npm)

Ah, perfect, that helps, thank you. I'll think about how to word this in the docs (and flag that packages should be public by default)

I've given it another pass in 3692334 with the help of Claude. I think that clarifies things a bit better, but I've quite possibly been looking at this a little too long (and there's also nuance surrounding the use of wp-build for plugins that I mightn't have considered, given that the global variable can be configured).

I'll leave it there for now — feel free to change any of this if anyone would like to! If this is still open next week I'll take a look at it with fresh eyes and when my 🧠 is a little clearer 😄

Thanks again for all the discussion here, much appreciated!