Skip to content

Commit a88b704

Browse files
adamzieladamziel
authored
Blueprint bundles (#75)
1 parent ace3224 commit a88b704

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

60 files changed

+2223
-199
lines changed

‎.github/actions/prepare-playground/action.yml

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -39,3 +39,6 @@ runs:
3939
- name: Set NX_HEAD
4040
shell: bash
4141
run: echo "NX_HEAD=$(git rev-parse HEAD)" >> $GITHUB_ENV
42+
- name: Reset NX cache
43+
shell: bash
44+
run: npx nx reset

‎package-lock.json

Lines changed: 12 additions & 0 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎package.json

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -70,6 +70,7 @@
7070
"@types/react-transition-group": "4.4.11",
7171
"@types/wicg-file-system-access": "2023.10.5",
7272
"@wordpress/dataviews": "4.5.0",
73+
"@zip.js/zip.js": "2.7.57",
7374
"ajv": "8.12.0",
7475
"async-lock": "1.4.1",
7576
"axios": "1.6.1",

‎packages/docs/site/docs/blueprints/02-using-blueprints.md

Lines changed: 31 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5,9 +5,11 @@ slug: /blueprints/using-blueprints
55

66
# Using Blueprints
77

8-
You can use Blueprints in one of two ways:
8+
You can use Blueprints in one of the following ways:
99

1010
- By passing them as a URL fragment to the Playground.
11+
- By loading them from a URL using the `blueprint-url` parameter.
12+
- By using Blueprint bundles (ZIP files or directories).
1113
- By using the JavaScript API.
1214

1315
## URL Fragment
@@ -93,6 +95,34 @@ Note that the Blueprint must be publicly accessible and served with [the correct
9395
Access-Control-Allow-Origin: *
9496
```
9597

98+
#### Blueprint Bundles
99+
100+
The `?blueprint-url` parameter now also supports Blueprint bundles in ZIP format. A Blueprint bundle is a ZIP file that contains a `blueprint.json` file at the root level, along with any additional resources referenced by the Blueprint.
101+
102+
For example, you can load a Blueprint bundle like this:
103+
104+
[https://playground.wordpress.net/?blueprint-url=https://example.com/my-blueprint-bundle.zip](https://playground.wordpress.net/?blueprint-url=https://example.com/my-blueprint-bundle.zip)
105+
106+
When using a Blueprint bundle, you can reference bundled resources using the `bundled` resource type:
107+
108+
```json
109+
{
110+
"landingPage": "/my-file.txt",
111+
"steps": [
112+
{
113+
"step": "writeFile",
114+
"path": "/wordpress/my-file.txt",
115+
"data": {
116+
"resource": "bundled",
117+
"path": "/bundled-text-file.txt"
118+
}
119+
}
120+
]
121+
}
122+
```
123+
124+
For more information on Blueprint bundles, see the [Blueprint Bundles](/blueprints/bundles) documentation.
125+
96126
## JavaScript API
97127

98128
You can also use Blueprints with the JavaScript API using the `startPlaygroundWeb()` function from the `@wp-playground/client` package. Here's a small, self-contained example you can run on JSFiddle or CodePen:

‎packages/docs/site/docs/blueprints/04-resources.md

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -131,3 +131,31 @@ To use the _LiteralReference_ resource, you need to provide the name of the file
131131
"contents": "Hello, World!"
132132
}
133133
```
134+
135+
### BundledReference
136+
137+
The `BundledReference` resource is used to reference files that are bundled with the Blueprint itself. This is particularly useful for creating self-contained Blueprint bundles that include all necessary resources. The `BundledReference` resource is defined as follows:
138+
139+
```typescript
140+
type BundledReference = {
141+
resource: 'bundled';
142+
path: string;
143+
};
144+
```
145+
146+
To use the `BundledReference` resource, you need to provide the relative path to the file within the bundle. For example, to reference a file named "plugin.php" that is bundled with the Blueprint, you can create a `BundledReference` as follows:
147+
148+
```json
149+
{
150+
"resource": "bundled",
151+
"path": "plugin.php"
152+
}
153+
```
154+
155+
Blueprint bundles can be distributed in various formats, including:
156+
157+
- ZIP files with a top-level `blueprint.json` file
158+
- Directories containing a `blueprint.json` file and related resources
159+
- Remote URLs where the Blueprint and its resources are hosted together
160+
161+
For more information on Blueprint bundles, see the [Blueprint Bundles](/blueprints/bundles) documentation.

‎packages/docs/site/docs/blueprints/06-bundles.md

Lines changed: 150 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,150 @@
1+
---
2+
title: Blueprint Bundles
3+
slug: /blueprints/bundles
4+
---
5+
6+
# Blueprint Bundles
7+
8+
Blueprint bundles are self-contained packages that include a Blueprint declaration (`blueprint.json`) along with all the additional resources required to compile and run it. This makes it easier to distribute and share complete WordPress Playground setups.
9+
10+
## What are Blueprint Bundles?
11+
12+
A Blueprint bundle is a collection of files that includes:
13+
14+
1. A `blueprint.json` file that defines the Blueprint configuration
15+
2. Any additional resources referenced by the Blueprint (themes, plugins, content files, etc.)
16+
17+
Blueprint bundles can be distributed in various formats:
18+
19+
- A ZIP file with a top-level `blueprint.json` file and additional resources
20+
- A directory inside a git repository where `blueprint.json` resides alongside other resources
21+
- A local directory on your computer
22+
- An inline JavaScript object with the relevant files inlined
23+
24+
## Using Blueprint Bundles
25+
26+
### On the Website
27+
28+
The WordPress Playground website supports Blueprint bundles through the `?blueprint-url=` query parameter. You can provide a URL to a ZIP file containing your Blueprint bundle:
29+
30+
```
31+
https://playground.wordpress.net/?blueprint-url=https://example.com/my-blueprint-bundle.zip
32+
```
33+
34+
The ZIP file should contain a `blueprint.json` file at the root level, along with any additional resources referenced by the Blueprint.
35+
36+
### In the CLI
37+
38+
The Playground CLI supports Blueprint bundles through the `--blueprint=` option. You can provide:
39+
40+
- A path to a local directory containing a Blueprint bundle
41+
- A path to a local ZIP file containing a Blueprint bundle
42+
- A URL to a remote Blueprint bundle (http:// or https://)
43+
44+
For example:
45+
46+
```bash
47+
# Using a local ZIP file
48+
npx @wp-playground/cli --blueprint=./my-blueprint.zip server
49+
50+
# Using a remote URL
51+
npx @wp-playground/cli --blueprint=https://example.com/my-blueprint.zip server
52+
53+
# Using a local directory
54+
npx @wp-playground/cli --blueprint=./my-blueprint-directory server
55+
```
56+
57+
By default, the CLI restricts access to local files for security reasons. If your Blueprint needs to access files in the same parent directory, you need to explicitly grant permission using the `--blueprint-may-read-adjacent-files` flag:
58+
59+
```bash
60+
npx @wp-playground/cli --blueprint=./my-blueprint.json --blueprint-may-read-adjacent-files server
61+
```
62+
63+
## Creating Blueprint Bundles
64+
65+
### Basic Structure
66+
67+
A basic Blueprint bundle might look like this:
68+
69+
```
70+
my-blueprint-bundle/
71+
├── blueprint.json
72+
├── theme.zip
73+
├── plugin.zip
74+
└── content/
75+
└── sample-content.wxr
76+
```
77+
78+
### Example Blueprint with Bundled Resources
79+
80+
Here's an example of a `blueprint.json` file that references bundled resources:
81+
82+
```json
83+
{
84+
"landingPage": "/my-file.txt",
85+
"steps": [
86+
{
87+
"step": "writeFile",
88+
"path": "/wordpress/my-file.txt",
89+
"data": {
90+
"resource": "bundled",
91+
"path": "/bundled-text-file.txt"
92+
}
93+
},
94+
{
95+
"step": "installTheme",
96+
"themeData": {
97+
"resource": "bundled",
98+
"path": "/theme.zip"
99+
}
100+
},
101+
{
102+
"step": "installPlugin",
103+
"pluginData": {
104+
"resource": "bundled",
105+
"path": "/plugin.zip"
106+
}
107+
},
108+
{
109+
"step": "importWxr",
110+
"file": {
111+
"resource": "bundled",
112+
"path": "/content/sample-content.wxr"
113+
}
114+
}
115+
]
116+
}
117+
```
118+
119+
In this example, the Blueprint references several bundled resources:
120+
121+
- A text file at `/bundled-text-file.txt`
122+
- A theme ZIP file at `/theme.zip`
123+
- A plugin ZIP file at `/plugin.zip`
124+
- A WXR content file at `/content/sample-content.wxr`
125+
126+
### Creating a ZIP Bundle
127+
128+
To create a ZIP bundle, simply create a directory with your `blueprint.json` and all required resources, then zip it up:
129+
130+
```bash
131+
# Create a directory for your bundle
132+
mkdir my-blueprint-bundle
133+
cd my-blueprint-bundle
134+
135+
# Create your blueprint.json and add resources
136+
# ...
137+
138+
# Zip it up
139+
zip -r ../my-blueprint-bundle.zip .
140+
```
141+
142+
## Troubleshooting
143+
144+
If you encounter issues with Blueprint bundles:
145+
146+
1. Ensure your `blueprint.json` file is at the root level of your ZIP file
147+
2. Check that all paths in your bundled resource references are correct
148+
3. Verify that your ZIP file is properly formatted
149+
4. When using the CLI, check if you need the `--blueprint-may-read-adjacent-files` flag
150+
5. Ensure all required resources are included in the bundle

‎packages/docs/site/docs/blueprints/08-examples.md

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -241,3 +241,58 @@ To specify the latest commit of a particular branch, you can change the referenc
241241
"wp": "https://playground.wordpress.net/plugin-proxy.php?build-ref=trunk"
242242
}
243243
}} />
244+
245+
## Using Blueprint Bundles
246+
247+
Here's an example of a Blueprint that uses bundled resources from a Blueprint bundle:
248+
249+
```json
250+
{
251+
"landingPage": "/",
252+
"preferredVersions": {
253+
"php": "8.0",
254+
"wp": "latest"
255+
},
256+
"steps": [
257+
{
258+
"step": "installTheme",
259+
"themeData": {
260+
"resource": "bundled",
261+
"path": "/my-theme.zip"
262+
},
263+
"activate": true
264+
},
265+
{
266+
"step": "installPlugin",
267+
"pluginData": {
268+
"resource": "bundled",
269+
"path": "/my-plugin.zip"
270+
},
271+
"activate": true
272+
},
273+
{
274+
"step": "writeFile",
275+
"path": "/wordpress/custom-page.html",
276+
"data": {
277+
"resource": "bundled",
278+
"path": "/assets/custom-page.html"
279+
}
280+
}
281+
]
282+
}
283+
```
284+
285+
This Blueprint bundle would be zip file containing the following files:
286+
287+
- `/blueprint.json` - The blueprint declaration outlined above
288+
- `/my-theme.zip` - A theme package
289+
- `/my-plugin.zip` - A plugin package
290+
- `/assets/custom-page.html` - A custom HTML file
291+
292+
You can use this Blueprint bundle by:
293+
294+
1. Creating a ZIP file with these files and the blueprint.json
295+
2. Hosting the ZIP file on a server
296+
3. Loading it with `?blueprint-url=https://example.com/my-blueprint-bundle.zip`
297+
298+
For more information on Blueprint bundles, see the [Blueprint Bundles](/blueprints/bundles) documentation.

‎packages/docs/site/docs/blueprints/intro.md

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -37,6 +37,8 @@ This docs hub is focused on Blueprints info and is divided into the following ma
3737

3838
- [Steps](/blueprints/steps): API Reference of all the available steps that can be set in a blueprint to run tasks such as login, plugin/theme activation, file operations, and more.
3939

40+
- [Blueprint Bundles](/blueprints/bundles): Learn how to create and use Blueprint bundles - self-contained packages that include a Blueprint and all its resources.
41+
4042
- [Examples](/blueprints/examples): Compilation of Blueprint examples for various WordPress Playground setups, including installing themes/plugins, running PHP code, enabling features, and loading specific WordPress versions.
4143

4244
- [Troubleshoot and debug Blueprints](/blueprints/troubleshoot-and-debug): Tips and tools for troubleshooting and debugging Blueprints.

0 commit comments

Comments
 (0)