[Documentation] Adding Playground CLI page and removing wp-now references #2337
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,118 @@ | ||
| --- | ||
| title: Playground CLI | ||
| slug: /developers/local-development/wp-playground-cli | ||
| --- | ||
|
|
||
| # Playground CLI | ||
|
|
||
| [@wp-playground/cli](https://www.npmjs.com/package/@wp-playground/cli) is the new command-line tool designed to simplify the development and testing flow. It runs a WordPress instance locally with Playground, and with the CLI, it is possible to auto-mount an environment with a plugin, theme, or WordPress installation. But if you need flexibility, the CLI supports mounting commands to personalize your local environment. | ||
fellyph marked this conversation as resolved.
Outdated
Show resolved
Hide resolved
fellyph marked this conversation as resolved.
Outdated
Show resolved
Hide resolved
|
||
|
|
||
| **Key features:** | ||
|
|
||
| - **Quick Setup**: Set up a local WordPress environment in seconds. | ||
| - **Flexibility**: Allows for configuration to adapt to different scenarios | ||
fellyph marked this conversation as resolved.
Outdated
Show resolved
Hide resolved
|
||
| - **Simple Environment**: No extra configuration, just a compatible Node installation, and you are ready to use it. | ||
fellyph marked this conversation as resolved.
Outdated
Show resolved
Hide resolved
|
||
|
|
||
| ## Requirements | ||
|
|
||
| The Playground CLI requires Node.js 20.18 or higher, which is the recommended Long-Term Support (LTS) version. You can download it from the Node.js website. | ||
|
|
||
| ## Quickstart | ||
|
|
||
| Running the Playground CLI is as simple as go to a command-line terminal and running: | ||
fellyph marked this conversation as resolved.
Outdated
Show resolved
Hide resolved
|
||
|
|
||
| ```bash | ||
| npx @wp-playground/cli@latest server | ||
| ``` | ||
|
|
||
| The previous command, you only get a fresh WordPress, instance to test. Most of the developers want to see their work running, If this is your case, test a plugin or a theme. You can run the CLI on your project folder and run the Playground CLI with the `--auto-mount` flag: | ||
fellyph marked this conversation as resolved.
Outdated
Show resolved
Hide resolved
|
||
|
|
||
| ``bash | ||
| cd my-plugin-or-theme-directory | ||
| npx @wp-playground/cli@latest server --auto-mount | ||
|
|
||
| ```` | ||
| ### Choosing a WordPress Version | ||
| By default, the CLI loads the latest stable version of WordPress and PHP 8.0 due to its improved performance. To specify your preferred versions, you can use the flag `--wp=<version>` and `--php=<version>`: | ||
| ```bash | ||
| npx @wp-playground/cli@latest server --wp=6.8 --php=8.4 | ||
| ```` | ||
|
|
||
| ### Mounting folders manually | ||
|
|
||
| Some projects have a specific structure that requires a custom configuration, for example, your repo contains all the files from the `/wp-content/` folder. So this scenario you can specify to the Plaground CLI you will mount your project from that folder using the flag `--mount`. | ||
|
|
||
| ```bash | ||
| npx @wp-playground/cli@latest server --mount=.:/wordpress/wp-content/plugins/ | ||
|
||
| ``` | ||
|
|
||
| ### Loading Blueprints | ||
|
|
||
| A way to bring the CLI playground to the next level is to integrate with Blueprints, which allows developers to set up the initial state from their WordPress instance. With the flag `--blueprint` the developer will be capable run a Playground with a custom inital state. | ||
fellyph marked this conversation as resolved.
Outdated
Show resolved
Hide resolved
|
||
|
|
||
| **(my-blueprint.json)** | ||
|
|
||
| ```bash | ||
| { | ||
| "landingPage": "/wp-admin/options-general.php?page=akismet-key-config", | ||
| "steps": [ | ||
| { | ||
| "step": "installPlugin", | ||
| "pluginData": { | ||
| "resource": "wordpress.org/plugins", | ||
| "slug": "akismet" | ||
| }, | ||
| "options": { | ||
| "activate": true | ||
| } | ||
| }, | ||
| { | ||
| "step": "login", | ||
| "username": "admin", | ||
| "password": "password" | ||
| }, | ||
| ] | ||
| } | ||
fellyph marked this conversation as resolved.
Show resolved
Hide resolved
|
||
| ``` | ||
|
|
||
| ```bash | ||
| npx @wp-playground/cli@latest server --blueprint=my-blueprint.json | ||
| ``` | ||
|
|
||
| ## Command and Arguments | ||
|
There was a problem hiding this comment. Is there something in Docusaurus that would enable us to auto-generate this section? I'm concerned about it getting outdated. |
||
|
|
||
| Playground CLI is simple, configurable, and unopinionated. You can set it up according | ||
| to your unique WordPress setup. With the Playground CLI, you can use the following top-level commands: | ||
|
|
||
| - **`server`**: (Default) Starts a local WordPress server. | ||
| - **`run-blueprint`**: Executes a Blueprint file without starting a web server. | ||
| - **`build-snapshot`**: Builds a ZIP snapshot of a WordPress site based on a Blueprint. | ||
|
|
||
| The `server` command supports the following optional arguments: | ||
|
|
||
| - `--port=<port>`: The port number for the server to listen on. Defaults to 9400. | ||
| - `--outfile`: When building, write to this output file. | ||
| - `--wp=<version>`: The version of WordPress to use. Defaults to the latest. | ||
| - `--auto-mount`: Automatically mount the current directory (plugin, theme, wp-content, etc.). | ||
| - `--mount=<mapping>`: Manually mount a directory (can be used multiple times). Format: /host/path:/vfs/path | ||
| - `--mount-before-install`: Mount a directory to the PHP runtime before WordPress installation (can be used multiple times). Format: `"/host/path:/vfs/path"`. | ||
fellyph marked this conversation as resolved.
Show resolved
Hide resolved
|
||
| - `--mount-dir`: Mount a directory to the PHP runtime (can be used multiple times). Format: `"/host/path"` `"/vfs/path"`. | ||
| - `--mount-dir-before-install`: Mount a directory before WordPress installation (can be used multiple times). Format: `"/host/path"` `"/vfs/path"` | ||
| - `--blueprint=<path>`: The path to a JSON Blueprint file to execute. | ||
| - `--blueprint-may-read-adjacent-files`: Consent flag: Allow "bundled" resources in a local blueprint to read files in the same directory as the blueprint file. | ||
| - `--login`: Automatically log the user in as an administrator. | ||
| - `--skip-wordpress-setup`: Do not download or install WordPress. Useful if you are mounting a full WordPress directory. | ||
| - `--skip-sqlite-setup`: Do not set up the SQLite database integration. | ||
| - `--quiet`: Do not output logs and progress messages. | ||
| - `--debug`: Print the PHP error log if an error occurs during boot. | ||
|
|
||
| ## Need some help with the CLI? | ||
|
|
||
| With the Playground CLI, you can use the `--help` to get some support about the available commands. | ||
|
|
||
| ```bash | ||
| npx @wp-playground/cli@latest --help | ||
| ``` | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -193,7 +193,7 @@ Here’s an example of a **[plugin that generates Custom Post Types](https://raw | |
|
|
||
| From a plugins' folder in your local development environment, you can quickly load locally a Playground instance with that plugin loaded and activated. | ||
|
|
||
| Use the [`@wp-playground/cli` command](/developers/local-development/wp-playground-cli) from your plugin's root directory using your preferred command line program. | ||
|
|
||
| With [Visual Studio Code](https://code.visualstudio.com/) IDE, you can also use the [Visual Studio Code extension](/developers/local-development/vscode-extension) while working in the root directory of your plugin. | ||
|
|
||
|
|
@@ -202,7 +202,7 @@ For example: | |
| ```bash | ||
| git clone [email protected]:wptrainingteam/devblog-dataviews-plugin.git | ||
| cd devblog-dataviews-plugin | ||
| npx @wp-playground/cli server --auto-mount | ||
| ``` | ||
|
|
||
| ### See your local changes in a Playground instance and directly create PRs in a GitHub repo with your changes | ||
|
|
||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -214,14 +214,14 @@ The ["Stylish Press"](https://github.com/WordPress/blueprints/tree/trunk/bluepri | |
|
|
||
| ### Local theme development and testing with Playground | ||
|
|
||
| From the root folder of a block theme's code, you can quickly load locally a Playground instance with that theme loaded and activated. You can do that by launching, in a theme directory, the [`@wp-playground/cli` command](/developers/local-development/wp-playground-cli) from your preferred command line program or the [Visual Code Studio extension](/developers/local-development/vscode-extension) from the [Visual Studio Code](https://code.visualstudio.com/) IDE. | ||
|
|
||
| For example: | ||
|
|
||
| ``` | ||
| git clone [email protected]:WordPress/community-themes.git | ||
| cd community-themes/blue-note | ||
| npx @wp-playground/cli server --auto-mount | ||
| ``` | ||
|
|
||
| ### Design your theme using the WordPress UI and save your changes as Pull Requests | ||
|
|
||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Uh oh!
There was an error while loading. Please reload this page.