Skip to content
/ bud Public

Commit 1219923

Browse files
kellymearskellymears
authored
📕 docs(none): wordpress enqueues (#2397)
Describe `entrypoints.json` and WordPress runtime dependency management in @roots/bud-preset-wordpress docs. ## Type of change **NONE: internal change**
1 parent f133de1 commit 1219923

File tree

11 files changed

+128
-21
lines changed

11 files changed

+128
-21
lines changed

‎sources/@repo/docs/content/extensions/bud-preset-wordpress/index.mdx‎

Lines changed: 103 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -23,15 +23,115 @@ It includes the following extensisons:
2323
npm install @roots/bud-preset-wordpress --save-dev
2424
```
2525

26-
## Excluding predefined externals
26+
## Managing WordPress enqueues
2727

28-
If WordPress provides a package in your bundle any references you make to it will be replaced by a reference to the WP provided global.
28+
If you are using [roots/sage](https://roots.io/sage) these details are handled for you by Acorn.
29+
30+
Otherwise you will want to do something like this:
31+
32+
```php
33+
add_action('enqueue_block_editor_assets', function () {
34+
// couple helper functions
35+
$get_path = fn ($endpoint) => join([get_template_directory(), 'dist', $endpoint], '/');
36+
$read = fn ($endpoint) => file_get_contents($dist_path($endpoint));
37+
38+
// entrypoints.json as an object
39+
$entrypoints = json_decode($read('entrypoints.json'));
40+
41+
wp_enqueue_script(
42+
'my-theme/editor/js',
43+
$get_path($entrypoints->editor->js[1]),
44+
[],
45+
null,
46+
true
47+
);
48+
49+
wp_enqueue_inline_script(
50+
'my-theme/editor/js',
51+
$read($entrypoints->editor->js[0]),
52+
'before',
53+
);
54+
55+
wp_enqueue_style(
56+
'my-theme/editor/css',
57+
$get_path($entrypoints->editor->css[0]),
58+
[],
59+
null
60+
);
61+
});
62+
```
63+
64+
## Managing WordPress runtime dependencies
65+
66+
If WordPress provides a package any references you make to it will be replaced by a reference to the WP provided global.
67+
68+
For example, if you import jquery in your application like so:
69+
70+
```
71+
import $ from 'jquery'
72+
```
73+
74+
It will be bundled as something like this:
75+
76+
```js
77+
const e = window.jQuery
78+
```
79+
80+
If you check out `entrypoints.json` you'll see the WordPress dependencies listed per entrypoint under the `dependencies` key:
81+
82+
```json
83+
{
84+
"editor": {
85+
"js": [
86+
"js/runtime.6390bb.js",
87+
"js/editor.b7e1d1.js"
88+
],
89+
"css": [
90+
"css/editor.8cd6ea.css"
91+
],
92+
"dependencies": [
93+
"jquery",
94+
"wp-blocks",
95+
"wp-dom-ready"
96+
]
97+
}
98+
}
99+
```
100+
101+
The intent is for you to read this file in your WordPress theme or plugin and enqueue the dependencies dynamically.
102+
103+
For example, building off the previous example code, this is how one might handle enqueues in a WordPress theme:
104+
105+
```php
106+
add_action('enqueue_block_editor_assets', function () {
107+
// couple helper functions
108+
$get_path = fn ($endpoint) => join([get_template_directory(), 'dist', $endpoint], '/');
109+
$read = fn ($endpoint) => file_get_contents($dist_path($endpoint));
110+
111+
// entrypoints.json as an object
112+
$entrypoints = json_decode($read('entrypoints.json'));
113+
114+
wp_enqueue_script(
115+
'my-theme/editor/js',
116+
$get_path($entrypoints->editor->js[1]),
117+
$entrypoints->editor->dependencies,
118+
null,
119+
true
120+
);
121+
122+
// ...
123+
});
124+
```
125+
126+
### Excluding modules
29127

30128
There may be situations where you want to exclude a package from this behavior. For example, you may wish to use a different version of jQuery than the one provided by WordPress.
31129

32-
To that end you can pass an array of packages to exclude:
130+
To address this, you can pass an array of packages to exclude:
33131

34132
```ts title=bud.config.ts
133+
import type {Bud} from '@roots/bud'
134+
35135
export default async (bud: Bud) => {
36136
bud.wp.externals.exclude(['jquery'])
37137
}

‎sources/@roots/bud-babel/src/extension.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,7 @@ import {
77
expose,
88
label,
99
} from '@roots/bud-framework/extension/decorators'
10-
import { InputError } from '@roots/bud-support/errors'
10+
import {InputError} from '@roots/bud-support/errors'
1111
import isString from '@roots/bud-support/lodash/isString'
1212
import isUndefined from '@roots/bud-support/lodash/isUndefined'
1313

‎sources/@roots/bud-babel/src/index.ts‎

Lines changed: 10 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -25,8 +25,7 @@ interface LoaderOptions {
2525
targets?: any
2626
}
2727

28-
interface BabelPublicApi
29-
extends PublicExtensionApi<BabelExtension> {
28+
interface BabelPublicApi extends PublicExtensionApi<BabelExtension> {
3029
plugins: BabelExtension[`plugins`]
3130
presets: BabelExtension[`presets`]
3231
setPlugin: BabelExtension[`setPlugin`]
@@ -97,6 +96,13 @@ declare module '@roots/bud-framework' {
9796
}
9897
}
9998

100-
10199
export default BabelExtension
102-
export type {BabelPublicApi, LoaderOptions, NormalizedPlugin, Options, Plugin, Registrable, Registry}
100+
export type {
101+
BabelPublicApi,
102+
LoaderOptions,
103+
NormalizedPlugin,
104+
Options,
105+
Plugin,
106+
Registrable,
107+
Registry,
108+
}

‎sources/@roots/bud-build/src/config/dependencies.ts‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
1-
import isUndefined from '@roots/bud-support/lodash/isUndefined'
2-
31
import type {Factory} from '@roots/bud-build/config'
42

3+
import isUndefined from '@roots/bud-support/lodash/isUndefined'
4+
55
export const dependencies: Factory<`dependencies`> = async ({
66
hooks,
77
root,

‎sources/@roots/bud-build/src/config/infrastructureLogging.ts‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
1-
import logger from '@roots/bud-support/logger'
2-
31
import type {Factory} from '@roots/bud-build/config'
42

3+
import logger from '@roots/bud-support/logger'
4+
55
export const infrastructureLogging: Factory<
66
`infrastructureLogging`
77
> = async bud =>

‎sources/@roots/bud-build/src/config/module.ts‎

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,5 @@
1-
import type {Bud} from '@roots/bud-framework'
2-
31
import type {Factory} from '@roots/bud-build/config'
2+
import type {Bud} from '@roots/bud-framework'
43

54
interface Props {
65
filter: Bud[`hooks`][`filter`]

‎sources/@roots/bud-build/src/config/parallelism.ts‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
1-
import {cpus} from 'node:os'
2-
31
import type {Factory} from '@roots/bud-build/config'
42

3+
import {cpus} from 'node:os'
4+
55
export const parallelism: Factory<`parallelism`> = async ({
66
build,
77
hooks,

‎sources/@roots/bud-build/src/config/resolve.ts‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
1-
import isString from '@roots/bud-support/lodash/isString'
2-
31
import type {Factory} from '@roots/bud-build/config'
42

3+
import isString from '@roots/bud-support/lodash/isString'
4+
55
export const resolve: Factory<`resolve`> = async bud => {
66
return await bud.hooks.filterAsync(`build.resolve`, {
77
alias: {

‎sources/@roots/bud-build/src/registry/index.ts‎

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -70,6 +70,5 @@ const makeRegister: makeRegister =
7070
}),
7171
)
7272

73-
7473
export {items, loaders, makeRegister, register, rules}
7574
export type {Factory, Props}

‎sources/@roots/bud-compiler/src/service/index.tsx‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -86,7 +86,8 @@ class Compiler extends Service implements BudCompiler {
8686
try {
8787
this.instance = this.implementation(this.config)
8888
} catch (error: unknown) {
89-
const normalError = error instanceof Error ? error : BudError.normalize(error)
89+
const normalError =
90+
error instanceof Error ? error : BudError.normalize(error)
9091
this.onError(normalError)
9192
}
9293

0 commit comments

Comments
 (0)