Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Documentation: Update documentation about build process changes #66428

Merged
merged 5 commits into from
Oct 25, 2024
Merged

Documentation: Update documentation about build process changes #66428

Show file tree
Hide file tree
Changes from 3 commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
ba84233
Document package requirements for bundling
sirreal Oct 24, 2024
4d91975
Document script-module process for block-library
sirreal Oct 24, 2024
111085e
Fix typos and errors
sirreal Oct 24, 2024
03fb0aa
Update the steps for exposing a view script module
gziolo Oct 25, 2024
34e5eb5
Run docs:build
sirreal Oct 25, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
36 changes: 33 additions & 3 deletions packages/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,10 +4,11 @@ This repository uses [npm workspaces](https://docs.npmjs.com/cli/v10/using-npm/w

## Creating a New Package

When creating a new package, you need to provide at least the following:
When creating a new package, you need to provide at least the following. Packages bundled in Gutenberg or WordPress must include a `wpScript` and or `wpScriptModuleExports` field in their `package.json` file. See the details below.

1. `package.json` based on the template:
```json

```jsonc
sirreal marked this conversation as resolved.
Show resolved Hide resolved
{
"name": "@wordpress/package-name",
"version": "1.0.0-prerelease",
Expand All @@ -32,10 +33,39 @@ When creating a new package, you need to provide at least the following:
},
"publishConfig": {
"access": "public"
}
},
// Include this line to include the package as a WordPress script.
"wpScript": true,
// Include this line to include the package as a WordPress script module.
"wpScriptModuleExports": "./build-module/index.js"
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm not sure I like this. Why should a package.json mention a built file. why wpModule: true is not enough? since we already have module defined in the package.json ?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think one aspect needs to be documented. Using wpScript or/and wpScriptModuleExports marks the package as production package for strict verification of compatibility with GPL license.

module isn't configured correctly at the moment. Eventually, we can explore migrating to "type": "module" and exports configuration but it's a separate effort.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

module isn't configured correctly at the moment.

I'm not sure I understand, we've been relying on module to output ESmodules forever, why is it not correct?

Copy link
Contributor

@youknowriad youknowriad Oct 25, 2024 •
edited by sirreal
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I was looking at https://github.com/WordPress/gutenberg/blob/trunk/packages/a11y/package.json for instance

That package has both "module" and "wpScriptModuleExports" and they point to different modules/APIs. So we're saying that this package ships "two different ESmodules" in one package. As an npm package consumer, I'm really confused what import something from '@wordpress/a11y' will yield to me. Which one of these is going to be used? Ultimately a package can ship multiple modules, that's ok but not two versions of the same module.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think one aspect needs to be documented. Using wpScript or/and wpScriptModuleExports marks the package as production package for strict verification of compatibility with GPL license.

I opened a follow-up #66562.

}
```

This assumes that your code is located in the `src` folder and will be transpiled with `Babel`.

For packages that should ship as a WordPress script, include `wpScript: true` in the `package.json` file. This tells the build system to bundle the package for use as a WordPress script.

For packages that should ship as a WordPress script module, include a `wpScriptModuleExports` field the `package.json` file. The value of this field can be a string to expose a single script module, or an object with a [shape like the standard `exports` object](https://nodejs.org/docs/latest-v20.x/api/packages.html#subpath-exports) to expose multiple script modules from a single package:
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Isn't this a duplication of the exports field for regular npm packages. Do we really need to invent our own convention?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@sirreal can provide a more exhaustive response. We were discussing using the official configuration for ES Modules:

It'll eventually happen, but more work is necessary. For example, all import statements that contain file paths must contain the file extension, for example: import './file.js';. That isn't the case currently.


```jsonc
{
"name": "@wordpress/example",

// The string form exposes the `@wordpress/example` script module.
"wpScriptModuleExports": "./build-module/index.js",

// Multiple sub-modules can be exposed by providing an object:
"wpScriptModuleExports": {
// Exposed as `@wordpress/example` script module.
".": "./build-module/index.js",
// Exposed as `@wordpress/example/demo-block/view` script module.
"./demo-block/view": "./build-module/index.js"
}
}
```

Both `wpScript` and `wpScriptModuleExports` may be included if the package exposes both a script and a script module.

1. `README.md` file containing at least:
- Package name
- Package description
Expand Down
18 changes: 18 additions & 0 deletions packages/block-library/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -106,6 +106,24 @@ To find out more about contributing to this package or Gutenberg as a whole, ple
}
```

If the block exposes a script module, it must be included in the package's `package.json` file
in the `wpScriptModules` object. This will include the script module when it's bundled for use
in WordPress. See [the packages README for more details.](../README.md):

```json
{
"name": "@wordpress/block-library",
"wpScriptModuleExports": {
"./file/view": "./build-module/file/view.js",
"./image/view": "./build-module/image/view.js",
"./navigation/view": "./build-module/navigation/view.js",
"./query/view": "./build-module/query/view.js",
"./search/view": "./build-module/search/view.js"
// Add any new script modules here.
}
}
```

This file will get automatically loaded when the static block is present on the front end. For dynamic block, you need to manually enqueue the view script in `render_callback` of the block, example:

```php
Expand Down
Loading