Documentation for using wp-now with Playground

[flexseth]

Error code

command not found: wp-now

Exists when

User has not installed wp-now package
https://www.npmjs.com/package/@wp-now/wp-now

If wp-now is not installed on a users machine, many of the commands will not work.

The need

Blueprints or instructions that use the wp-now package should help users navigate how to install and use the package with Playground.

Docs to include

• Requirements & known limitations
• wp-now vs. VS Code extension
• Installing via npx
• Installing in a single directory vs. globally on your machine
• Using blueprints with wp-now
• etc

[ironnysh]

That's already available on NPM/GitHub, so just need to import the README to the docs directory. Or am I missing something? :-)

And slightly off-topic: the image in the README is broken on NPM.

[adamziel]

That's already available on NPM/GitHub, so just need to import the README to the docs directory. Or am I missing something? :-)

You're exactly right! :-)

[ironnysh]

Coolio. Will do it tomorrow :-)

[flexseth]

About wp-now

wp-now streamlines the process of setting up a local WordPress environment.
See the NPM package on wp-now.

Requirements

wp-now includes an entire WordPress environment, so you don't need to install WordPress separately. It runs on PHP WASM (Web Assembly) - @ironnysh - please provide link for more context

Node.js is required to run wp-now. You can download it from the Node.js website.
Node is required because the Playground using NPM behind the scenes to install packages.

---

Boot modes

theme
plugin
wp-content
"blueprint mode" - on the roadmap
(@ironnysh - I've documented wp-content mode here a little bit)

Limitations

When booting in wp-content mode without a theme, you will receive an error that there is no theme present.
Solution: Add an empty themes directory

shell step in wp-now with wp-cli

The shell step currently won't work in wp-now because it doesn't support the shell command.
This is a known limitation that we are working towards making work!

Other known limitations

Please check the Playground Tools GitHub repo for issues related to wp-now

Also see the Known Limitations sections on the wp-now documentation for more info

---

How to boot up Playground in easy mode

wp-content mode

• Loads up everything in the wp-content directory
• Themes, Plugins, and Uploads

A great option if you want to create a new theme for a website, or work with existing website content.
TODO: Show steps to boot in wp-content mode - @ironnysh :)

Or want to work with an existing website to test out a plugin or theme.

How to boot up Playground in wp-content mode

Content needed for wp-content mode
WordPress installation should include the following:

• All uploaded media to this website
• The current theme being used
• All plugins being used

---

Security warnings

Sometimes when you use NPM packages from an external source, the project you are using needs to update them.

See the Security Warnings page for more information on how to audit and fix security issues in wp-now.

You can report these types of errors if you aren't able to get them fixed.
Here is a sample error report on the playground-tools repo

• wp-now: Resolve npm audit warnings #224
• TODO: Update docs with how to audit and fix security issues in wp-now

wp-now: Error starting: getaddrinfo ENOTFOUND

• wp-now: Error starting: getaddrinfo ENOTFOUND new-playground1.wpnow #32

[flexseth]

@ironnysh Included a bunch of notes. They're kinda organized. :)

[ironnysh]

@flexseth, thanks for the list :-)

I went over everything here, as well as the published docs (specifically, the Contributing chapter), and I have some suggestions.

If it’s okay with you (and @adamziel, of course :-) ), I’d like to propose this as a working plan, which I’d be happy to take on.

Reorganize the chapters

1. Add a new chapter: Local Playground, which will include:
   • The wp-now README (note: the wp-now docs are outdated, and need to be revised before importing to Docusaurus. See details below, under "wp-now Docs").
   • The VS Code extension doc.
   • Restructure the current Usage in Node.js chapter into a page, focusing only on the @php-wasm/node package (i.e., import the README to the docs).

• The FAQ should be removed
• The WordCamp Contributor Day needs a rewrite, and should be under the Contributing chapter.

Revise the Contributing chapter

All the subsections in the Contributing chapter need a rewrite.

• The NX chapter: remove all general NX text (no reason to recreate the NX docs) and migrate only what’s relevant to Playground to the Code contribution page. NX is also mentioned under Architecture Overview, so that’s covered.
• The Code Contributions page mentions needing local custom domains. Is it still required or was it resolved since the original PR? The local debug is Windows-only, and should mention you need Chrome installed ;-)
• The Coding standards page should be renamed, shortened, and integrated at the top of the Code Contributions page.
• The Triage Contributions page feels out of place. It should be summarized and added to the Start Contributing page.
• The Publishing Packages, Releases, and More chapter should be removed. The relevant sections should be moved under Architecture Overview
• The Crash Reports page should be shortened, and either moved under Architecture Overview or the Code contribution page.
• The Contributing Documentation page: I suggest adding "dev:docs": "nx dev docs-site", to the scripts in Playground’s package.json, and rewrite the A more difficult way with a preview section. Also, the documentation tracking issue is too long and confusing to serve as a starting point for documentation contributors. There should be a project or a clean, up-to-date issue that’s regularly maintained. Remove the General guidelines.

wp-now Docs

Using Blueprints

1. Let’s add 1-2 simpler Blueprint examples.
2. Shelf the Defining Custom URLs until wp-now adds support for custom domains or SSL.

Known issues
Some were resolved for sure. Others, maybe:

• Running wp-now start in 'wp-content' or 'wordpress' mode will produce some empty directories: WordPress/wordpress-playground#328 —Is this still an issue?

• Inline images are broken when site starts on a different port: WordPress/wordpress-playground#356 —Is this still an issue, given this was merged?

• wp-now doesn't build or start on Windows: WordPress/playground-tools#66, WordPress/playground-tools#11 RESOLVED

• It's not possible to set WP_DEBUG and other wp-config.php constants: WordPress/playground-tools#17 RESOLVED

• In 'wordpress' mode, wp-now can connect to a MySQL database with define( 'DB_HOST', '127.0.0.1' );, but define( 'DB_HOST', 'localhost' ); does not work: WordPress/wordpress-playground#369

• wp-now published versions can appear random: WordPress/wordpress-playground#357 —Is this still an issue?

Misc

• Is it still impossible to run wp shell in Playground?

• See the Security Warnings page for more information on how to audit and fix security issues in wp-now.

  The link is broken. In any case, if this is related to NPM dependency issues, it shouldn’t be here.

• The Limitations chapter needs a rewrite.

• All contribution content should refer also to https://github.com/WordPress/playground-tools/.

[flexseth]

And slightly off-topic: the image in the README is broken on NPM.

Resolved by

• WP-NOW: Update readme link fixing wp-now-basics-diagram.png image to work on npmjs WordPress/playground-tools#223

[flexseth]

@ironnysh - working on some more page updates.

Also linked an issue that I think could help with organizing some of the content for the pages, once it's all there

• Visual feature list for "What all can I do with the Playground?" WordPress/wordpress-playground#1269
  Been doing some thinking on this, it would be really cool to see a "pricing tables" style view of the features that are

[flexseth]

All issues and known limitations of wp-now as of the date of this comment

• https://github.com/flexseth/playground-docs-updates/blob/trunk/wp-now/known-limitations.md

Should take care of that part of the doc update

[ironnysh]

organizing some of the content

@flexseth, are we talking about the documentation site? In any case, #126 should probably be a discussion and not an issue.

issues and known limitations

Probably shouldn't be combined in a single public-facing page in the docs.

Since all the content I mentioned is live, I'd like to work on this “textual refactor” ASAP.
@adamziel, would one PR for all of these be okay with you? I can also separate them by chapters/pages.

[adamziel]

@ironnysh That plan looks absolutely amazing! One PR for all of these is amazing, too. Let's make these updates in mdx and Docusaurus at https://github.com/WordPress/wordpress-playground/ as they could already benefit the readers and getting playground-docs-workflow repo ready to use will take a bit more time.

[ironnysh]

Let's make these updates in mdx and Docusaurus at https://github.com/WordPress/wordpress-playground/

Right :-) Also adding Improve the description of SetSiteOptionsStep #1291 to the list.

[ironnysh]

Can close this one 🥳

[flexseth]

Can close this one 🥳

done and done :)