Importing @wordpress packages from node_modules?

[g-elwell]

If you're working on a project and want to use the JavaScript APIs and libraries provided by WordPress, there are two options available:

• Destructure from the wp global variable (e.g. const { ToggleControl } = wp.components)
• Install from npm and import from node_modules (e.g. import { ToggleControl } from '@wordpress/components)

I was curious about the difference between these and wanted to know which one is the recommended approach. I couldn't find a clear answer, but while looking into it I discovered some interesting info that might be relevant to these build tools.

Destructuring is quick - you don't need to manually install a package and when developing for WordPress you can be certain that the global wp variable is going to be available when your code will run. However, because your code editor isn't aware of the wp global it can't provide you with any hinting or suggestions when you use it.

If you decide to install the packages you need using npm, your code editor can read their contents in order to provide some helpful tooling. In VSCode without any additional config you get suggestions, autocomplete and inline documentation about available imports, function params and component props as well as automatic import suggestions.

As a side note you end up recording which version of each package you are using in your project which might also be useful.

The downside to this approach is that you're importing packages that are already available to you in WordPress and increasing your bundle size needlessly. However, by listing these packages as externals in webpack you can prevent them from being added to your final bundle whilst still benefitting from the improved dev experience.

WordPress actually provide @wordpress/dependency-extraction-webpack-plugin which defines all the modern WordPress packages and libraries as externals in webpack. Also, this plugin will generate a php file for each of your entrypoints containing a dependency array that you can import when you enqueue your script, removing the need to manually maintain an array of dependencies for each of your scripts.

In terms of these build tools, on a basic level adding the @wordpress/* packages to the webpack config as externals should be fairly straightforward and would allow you to choose which approach you want to take when it comes to using them in your project.

[spbuckle]

Thanks for this @g-elwell!

I would be open to discussion on changing our approach on this. I believe the main reason we don't import the libraries is (as you stated) to not import packages that are already available but (again as you've stated) as there is a way around that it could work.

Along with all the dev benefits, 'automatically generating a dependency array' sounds like it would solve a few areas where some of our juniors have tripped up on including the right dependancies for their scripts.

I would be curious to know if the packages are kept as up to date as the ones available to us from WordPress itself.

[jaymcp]

they'll be more up to date. the gutenberg package versions are often much further ahead than the versions available in core (because core picks a gutenberg version to pin for a core release). gutenberg releases are far more frequent than wordpress ones.

[spbuckle]

That's good to know @jonmcp! Cheers! As you both (you and @g-elwell) raised below this would cause a miss-match of versions which may or may not cause issues.

[jaymcp]

thanks for the info, @g-elwell 👍
on the whole, that approach sounds reasonable to me.

i have two concerns:

• does this approach impact compile-times? i'm not sure how long these tools take to compile a decently-sized project, but often seemingly small changes can significantly slow down the process.
• this is possibly a hypothetical - since gutenberg package versions are usually a ways ahead of the versions available in core, there could be breakages if package functionality is utilised in our code that hasn't made it into core yet

[jaymcp]

that's fair enough, although one would have to be mindful of incorrect autocompletions and whatnot, if it's using the latest version packages for intellisense. i guess one could avoid that by making sure to specify version when adding a package into the project

[g-elwell]

The above assumption seems to be correct, although it's actually done in a slightly more sophisticated way by webpack.

I checked this by comparing webpack's build output using both methods and with/without listing the packages as externals. When using externals, the bundle size difference is negligible and nothing additional is compiled.

One thing to be aware of is that the version you're requiring in your package.json is no longer relevant since it won't necessarily match the external version you'll be using, but on the plus side you'll always be using the package version included in WordPress core, just as you would if you grabbed it yourself from the wp global variable.

[g-elwell]

@jonmcp yeah totally, the possibility for incorrect autocompletions would now seem to be the main 'downside', however like you said there's a way around this by specifying the same version core is using within your project.

[ampersarnie]

The above assumption seems to be correct, although it's actually done in a slightly more sophisticated way by webpack.

Just to note that this is right. We already utilise this for React, react-dom and jquery as some of our base externals setup.

Webpack documentation is here; https://webpack.js.org/configuration/externals/

[jaymcp]

we still have jquery in there? 😂

[ampersarnie]

Finally getting round to responding to this but it seems like @jonmcp has covered my concerns about this anyway. I am however not overly concerned about mismatching version as we've seen this in use in various in-production plugins and blocks. It's also used this way with Jest tests when it comes to Gutenberg/WordPress functions, etc. Of course that might mean we've just not encountered issues yet but it still leaves me with a lack of concern over that.

It's also worth adding that not even Automattic have this included in their own build scripts for Gutenberg plugins/assets from what I can understand. I've no idea what the reason is for this but I'm at least willing to explore the possibility of allowing this within our own tools.

So I'm going to suggest that we add the necessary @wordpress/* packages to the webpack config and test this out on a separate branch before committing to the idea incase there are any issues. At the moment I don't think I'd want to include any of the packages as dependencies for this (Build Tools) package, unless we find it works and everyone migrates over to that way of working. But it will, assuming there are no issues, allow engineers to have the choice - or at least leads when setting up.

WordPress actually provide @wordpress/dependency-extraction-webpack-plugin which defines all the modern WordPress packages and libraries as externals in webpack. Also, this plugin will generate a php file for each of your entrypoints containing a dependency array that you can import when you enqueue your script, removing the need to manually maintain an array of dependencies for each of your scripts.

This may actually be something we can integrate without the need for the @wordpress/* package external setup, so we can look into this as a separate exercise. It might fit in well with our asset-settings.php approach for asset naming any, so this is a good idea.

[g-elwell]

I believe Automattic are using their @wordpress/dependency-extraction-webpack-plugin to set up their externals in webpack, which includes a script to transform anything using the @wordpress namespace (with a couple of exceptions):
https://github.com/WordPress/gutenberg/blob/trunk/packages/dependency-extraction-webpack-plugin/lib/util.js

[ampersarnie]

@g-elwell Ohh that's a good spot. Completely missed that util file. Interesting, then I guess we can assume it's actually safe to use seeing as it seems to be the "WordPress way" of handling that in their build processes. Let's give this some implementation and test it to see how it works for us.

[ampersarnie]

I've created an issue from this (#9) and pencilled it in for the 1.1.0 roadmap.