Add documentation for testing with local Playground packages (#2144)

Author: bcotrim

CONTRIBUTING.md

@@ -22,6 +22,8 @@ If you find a bug or have a feature request, please [open an issue](https://gith
 
 For information on setting up your development environment for contributing code, see the [Code Contributions](./docs/code-contributions.md).
 
+For testing Studio with local WordPress Playground packages, see [Testing with Local Playground](./docs/testing-with-local-playground.md).
+
 We are truly grateful for any pull requests you open, and we assure you of our welcoming and respectful approach. We will review and consider all pull requests, valuing the diverse contributions, but we don’t guarantee that all proposed changes will be merged into the core.
 
 The most desirable pull requests are:

docs/testing-with-local-playground.md

@@ -0,0 +1,109 @@
+# Testing with Local Playground Packages
+
+When developing features that require changes to WordPress Playground packages (`@wp-playground/*` or `@php-wasm/*`), you can test Studio with locally built Playground packages.
+
+## Prerequisites
+
+Clone the WordPress Playground repository alongside the Studio repository:
+
+```
+Code/
+├── studio/
+└── wordpress-playground/
+```
+
+**Important:** Make sure to initialize git submodules:
+
+```bash
+cd /path/to/wordpress-playground
+git submodule update --init --recursive
+```
+
+## Setup Steps
+
+### 1. Build Playground packages
+
+```bash
+cd /path/to/wordpress-playground
+npm install
+npm run build
+```
+
+### 2. Update Studio's package.json
+
+Replace the existing Playground dependencies with local file references. These packages are grouped together at the end of `dependencies` in `package.json` for easier replacement:
+
+```json
+{
+  "dependencies": {
+    "@php-wasm/node": "file:../wordpress-playground/dist/packages/php-wasm/node",
+    "@php-wasm/scopes": "file:../wordpress-playground/dist/packages/php-wasm/scopes",
+    "@php-wasm/universal": "file:../wordpress-playground/dist/packages/php-wasm/universal",
+    "@wp-playground/blueprints": "file:../wordpress-playground/dist/packages/playground/blueprints",
+    "@wp-playground/cli": "file:../wordpress-playground/dist/packages/playground/cli",
+    "@wp-playground/wordpress": "file:../wordpress-playground/dist/packages/playground/wordpress"
+  }
+}
+```
+
+### 3. Update Playground's node_modules symlinks
+
+Playground's built packages import other packages from `node_modules`. By default, these point to source directories, but we need them to point to the built `dist/` packages.
+
+Run this from the wordpress-playground root:
+
+```bash
+cd /path/to/wordpress-playground
+
+for pkg in node-polyfills logger util progress fs-journal stream-compression scopes universal node web web-service-worker cli xdebug-bridge; do
+  if [ -d "dist/packages/php-wasm/$pkg" ]; then
+    rm -rf "node_modules/@php-wasm/$pkg" && ln -s "../../dist/packages/php-wasm/$pkg" "node_modules/@php-wasm/$pkg"
+  fi
+done
+
+for pkg in cli blueprints wordpress common storage client remote components wordpress-builds; do
+  if [ -d "dist/packages/playground/$pkg" ]; then
+    rm -rf "node_modules/@wp-playground/$pkg" && ln -s "../../dist/packages/playground/$pkg" "node_modules/@wp-playground/$pkg"
+  fi
+done
+```
+
+### 4. Install dependencies in Studio
+
+```bash
+cd /path/to/studio
+npm install
+```
+
+### 5. Start Studio
+
+```bash
+npm start
+```
+
+## Development Workflow
+
+After making changes to Playground:
+
+1. Rebuild the changed package(s):
+   ```bash
+   cd /path/to/wordpress-playground
+   npx nx build playground-cli  # or other package name
+   ```
+
+2. Restart Studio (restart `npm start`)
+
+## Reverting to npm Packages
+
+To go back to using the published npm packages:
+
+1. Restore both `package.json` and `package-lock.json`:
+   ```bash
+   git checkout package.json package-lock.json
+   ```
+2. Run `npm install`
+3. In the Playground repo, restore the original `node_modules` symlinks:
+   ```bash
+   cd /path/to/wordpress-playground
+   npm install
+   ```

package.json

@@ -109,9 +109,6 @@
 		"@formatjs/intl-locale": "^3.4.5",
 		"@formatjs/intl-localematcher": "^0.5.4",
 		"@inquirer/prompts": "^7.10.1",
-		"@php-wasm/node": "^3.0.22",
-		"@php-wasm/scopes": "^3.0.22",
-		"@php-wasm/universal": "^3.0.22",
 		"@reduxjs/toolkit": "^2.7.0",
 		"@rive-app/react-canvas": "^4.12.0",
 		"@sentry/electron": "^6.5.0",
@@ -122,9 +119,6 @@
 		"@wordpress/dataviews": "^10.2.0",
 		"@wordpress/i18n": "^6.1.0",
 		"@wordpress/icons": "^11.1.0",
-		"@wp-playground/blueprints": "^3.0.22",
-		"@wp-playground/cli": "^3.0.22",
-		"@wp-playground/wordpress": "^3.0.22",
 		"archiver": "^6.0.1",
 		"atomically": "^2.0.3",
 		"cli-table3": "^0.6.5",
@@ -158,7 +152,13 @@
 		"wpcom-xhr-request": "^1.3.0",
 		"yargs": "^18.0.0",
 		"yauzl": "^3.2.0",
-		"zod": "^3.24.3"
+		"zod": "^3.24.3",
+		"@php-wasm/node": "^3.0.22",
+		"@php-wasm/scopes": "^3.0.22",
+		"@php-wasm/universal": "^3.0.22",
+		"@wp-playground/blueprints": "^3.0.22",
+		"@wp-playground/cli": "^3.0.22",
+		"@wp-playground/wordpress": "^3.0.22"
 	},
 	"optionalDependencies": {
 		"appdmg": "^0.6.6"