Skip to content

Commit

Permalink
Improve local development scripts (#151)
Browse files Browse the repository at this point in the history
* Improve start and stop scripts

* Add schema and suppress pro notice

* Opt-in to browser opening
  • Loading branch information
chriszarate authored Oct 8, 2024
1 parent 3bc6114 commit 000e79f
Show file tree
Hide file tree
Showing 10 changed files with 141 additions and 120 deletions.
5 changes: 5 additions & 0 deletions .wp-env.json
Original file line number Diff line number Diff line change
@@ -1,10 +1,15 @@
{
"$schema": "https://raw.githubusercontent.com/WordPress/gutenberg/refs/heads/trunk/schemas/json/wp-env.json",
"config": {
"WP_DEBUG_DISPLAY": true,
"WP_DEVELOPMENT_MODE": "plugin",
"WP_ENVIRONMENT_TYPE": "development",
"WP_REDIS_DISABLE_BANNERS": true,
"WP_REDIS_HOST": "host.docker.internal"
},
"mappings": {
".htaccess": "./bin/conf/htaccess"
},
"plugins": [
".",
"./example",
Expand Down
File renamed without changes.
160 changes: 102 additions & 58 deletions bin/start
Original file line number Diff line number Diff line change
@@ -1,86 +1,130 @@
#!/bin/sh

set -e
root_dir=$(pwd)
env_type=$1

# Cleanup after error or trapping SIGINT (Ctrl+C) and SIGTERM signals
APP_MODE="$1" # "decoupled" or empty

# Set WordPress port and home URL.
PORT="${WP_ENV_PORT-8888}"
WP_HOME="${WP_ENV_HOME_URL-http://localhost:$PORT}"

if [ "$APP_MODE" = "decoupled" ]; then
# When running in decoupled mode, listen on a different port to avoid
# sticky cached redirects.
PORT="${WP_ENV_PORT-8899}"

WP_HOME="${WP_ENV_HOME_URL-http://localhost:3000}"
fi

FLAGS="${WP_ENV_FLAGS---xdebug}"
WP_ADMIN="http://localhost:$PORT/wp-admin/"

cleanup() {
exit_code=0
echo ""
echo "✊ Caught SIG signal. Stopping..."

npm run -s dev:stop
exit 0
}

if [ -n "$1" ]; then
exit_code=1
echo "⚠️ Error: $1"
activate_plugin() {
slug="$1"

if (npm run -s wp-cli plugin is-active "$slug" 2>/dev/null); then
echo "✏️ $slug is already active."
else
echo "✊ Caught SIG signal. Shutting down..."
echo "✏️ Activating $slug..."
npm run -s wp-cli plugin activate "$slug"
fi
}

deactivate_plugin() {
slug="$1"

if [ -n "$BACKEND_PID" ]; then
echo "Killing npm start process..."
kill "$BACKEND_PID" 2>/dev/null || true
if (npm run -s wp-cli plugin is-active "$slug" 2>/dev/null); then
echo "✏️ Deactivating $slug..."
npm run -s wp-cli plugin deactivate "$slug"
fi
}

echo "Shutting down Valkey / Redis..."
docker compose -f "$root_dir/docker-compose.overrides.yml" down
install_and_activate_plugin() {
plugin="$1"
slug="$2"

# This command echoes good status messages.
npx wp-env stop
if (npm run -s wp-cli plugin is-installed "$slug" 2>/dev/null); then
echo "✏️ $slug is already installed."
else
echo "✏️ Installing $slug..."
npm run -s wp-cli plugin install "$plugin"
fi

echo ""
echo "⏸️ Run \`npm run start:$env_type\` to resume or \`npm run destroy\` to clean up."
exit "$exit_code"
activate_plugin "$slug"
}

setup_object_cache() {
echo "Setting up object cache..."
docker compose -f "$root_dir/docker-compose.overrides.yml" up -d
# npx wp-env run cli -- wp redis enable
configure_wordpress() {
echo "✏️ Enabling Redis..."
npm run -s wp-cli redis enable

echo "✏️ Updating home option..."
npm run -s wp-cli config set WP_HOME "$WP_HOME"

if [ "$APP_MODE" = "decoupled" ]; then
configure_decoupled_wordpress
else
deactivate_plugin "vip-decoupled-bundle"
fi
}

composer install
configure_decoupled_wordpress() {
# We don't do this by default so we don't accidentally write code that
# depends on a particular permalink structure.
echo "✏️ Updating permalink structure..."
npm run -s wp-cli rewrite structure '/%postname%/'

trap 'cleanup' INT TERM
install_and_activate_plugin "$DECOUPLED_PLUGIN_URL" "vip-decoupled-bundle"

# Monolith via wp-env
if [ "$env_type" = "monolith" ]; then
# npx looks in node_modules/.bin first
setup_object_cache
npx wp-env start
npm start
exit 0
fi
echo "✅ Decoupled configuration complete."
}

# Monolith w/xdebug via wp-env
if [ "$env_type" = "monolith-xdebug" ]; then
setup_object_cache
npx wp-env start --xdebug=debug,develop,trace
npm start
exit 0
fi
start_redis() {
echo "🔼 Starting Redis..."
docker compose -f docker-compose.overrides.yml up -d
}

# Decoupled via wp-env
if [ "$env_type" = "decoupled" ]; then
if [ ! -d "$root_dir/../wp-components" ]; then
echo "⚠️ The wp-components repo does not exist. Please clone at sibling level to this repo."
exit 1
fi
start_wordpress() {
echo "🔼 Starting WordPress..."
WP_ENV_PORT="$PORT" npx wp-env start "$FLAGS"
}

cd ./bin/wp-env/decoupled
open_browser() {
echo ""
echo "> 🌐 $WP_ADMIN"
echo "> 🔑 Username: admin"
echo "> 🔑 Password: password"
echo ""

setup_object_cache
npx wp-env start
npx wp-env run cli -- wp rewrite structure '/%postname%/'
# Opening the browser is disruptive, make users opt-in.
if [ -z "$WP_ENV_OPEN_BROWSER" ]; then
return
fi

if [ $? -ne 0 ]; then
cleanup "Failed to set permalink structure"
UNAME="$(uname -s)"

if [ "Darwin" = "$UNAME" ]; then
open "$WP_ADMIN"
elif [ "Linux" = "$UNAME" ]; then
xdg-open "$WP_ADMIN"
fi
}

npm start &
BACKEND_PID=$!
cd "$root_dir/../wp-components" && npm install && npm run build && ./.frontend-env/start react-next
exit 0
fi
# Cleanup after error or trapping SIGINT (Ctrl+C) and SIGTERM signals
trap 'cleanup' INT TERM

start_redis
start_wordpress
configure_wordpress
open_browser

echo "⚠️ Error: can't start the unknown!"
exit 1
# Start hot-reloading wp-scripts start
echo "🔼 Starting wp-scripts build process..."
npm start
26 changes: 16 additions & 10 deletions bin/stop
Original file line number Diff line number Diff line change
@@ -1,18 +1,24 @@
#!/bin/sh

root_dir=$(pwd)
TASK="${1-stop}"

echo "Shutting down Valkey / Redis..."
docker compose -f "$root_dir/docker-compose.overrides.yml" down
teardown_redis() {
echo "🔽 Shutting down Redis..."
docker compose -f docker-compose.overrides.yml down
}

# We don't know which environment is running, so we'll stop both and suppress output.
echo "Stopping WordPress..."
cd ./bin/wp-env/decoupled || exit 1
npx wp-env stop 2>/dev/null
cd "$root_dir" || exit 1
npx wp-env stop 2>/dev/null
teardown_wordpress() {
if [ "$TASK" = "destroy" ]; then
npx wp-env destroy
echo "👋 Run \`npm run dev\` to recreate."
else
npx wp-env stop
echo "⏹️ Rerun \`npm run dev\` to resume or \`npm run dev:destroy\` to clean up."
fi
}

# Kill any lingering Node.js processes.
pkill -f 'remote-data-blocks/node_modules/'

echo "⏸️ Rerun \`npm run start:*\` command to resume or \`npm run destroy\` to clean up."
teardown_redis
teardown_wordpress
21 changes: 0 additions & 21 deletions bin/wp-env/decoupled/.wp-env.json

This file was deleted.

16 changes: 0 additions & 16 deletions bin/wp-env/decoupled/mu-plugins/home-url-filter.php

This file was deleted.

8 changes: 4 additions & 4 deletions docs/local-development.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@ composer install
To start a development environment with Xdebug enabled:

```sh
npm run start:monolith-xdebug
npm run dev
```

This will spin up a WordPress environment and a Valkey (Redis) instance for object cache. It will also build the block editor scripts, watch for changes, and open a Node.js debugging port. The WordPress environment will be available at `http://localhost:8888` (admin user: `admin`, password: `password`).
Expand Down Expand Up @@ -50,8 +50,8 @@ npm run destroy
While not a suitable for local developement, it can sometimes be useful to quickly spin up a local WordPress playground using `@wp-now/wp-now`:

```sh
npm run build # or `npm run start` in a separate terminal
npm run start:playground
npm run build # or `npm start` in a separate terminal
npm run playground
```

Playgrounds do not closely mirror production environments and are missing persistent object cache, debugging tools, and other important features. Use `npm run start:monolith-xdebug` for local development.
Playgrounds do not closely mirror production environments and are missing persistent object cache, debugging tools, and other important features. Use `npm run dev` for local development.
6 changes: 5 additions & 1 deletion docs/troubleshooting.md
Original file line number Diff line number Diff line change
@@ -1,8 +1,12 @@
# Troubleshooting and debugging

This plugin provides a [local development environment](local-development.md) with built-in debugging tools.

## Query monitor

Installing the [Query Monitor plugin](https://wordpress.org/plugins/query-monitor/) in your local development environment is highly recommended. When present, Remote Data Blocks will output debugging information to the Query Monitor "Logs" panel, including error details, stack traces, query execution details, and cache hit/miss status.
When the [Query Monitor plugin](https://wordpress.org/plugins/query-monitor/) is installed and activated, Remote Data Blocks will output debugging information to the Query Monitor "Logs" panel, including error details, stack traces, query execution details, and cache hit/miss status.

The provided local development environment includes Query Monitor by default. You can also install it in non-local environments, but be aware that it may expose sensitive information in production environments.

## Debugging

Expand Down
4 changes: 2 additions & 2 deletions package-lock.json

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

15 changes: 7 additions & 8 deletions package.json
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,10 @@
"cmd:build:example": "npm run cmd:build -- --config=example/$EXAMPLE/webpack.config.js --output-path=example/$EXAMPLE/build --webpack-src-dir=example/$EXAMPLE/src",
"cmd:format": "prettier '**/*.(js|json|jsx|md|ts|tsx|yml|yaml)'",
"cmd:lint": "eslint --ext 'js,jsx,ts,tsx' --quiet",
"destroy": "npm run stop && wp-env destroy",
"dev": "./bin/start",
"dev:decoupled": "./bin/start decoupled",
"dev:destroy": "./bin/stop destroy",
"dev:stop": "./bin/stop",
"format": "npm run cmd:format -- --write",
"format:check": "npm run cmd:format -- --check",
"lint": "npm run cmd:lint .",
Expand All @@ -34,16 +37,12 @@
"lint:phpcs:fix": "vendor/bin/phpcbf",
"lint:psalm": "vendor/bin/psalm.phar",
"packages-update": "wp-scripts packages-update",
"playground": "npx @wp-now/wp-now start --php=8.2 --blueprint=blueprint.local.json",
"playground:reset": "npm run playground -- --reset",
"plugin-zip": "npm run build && composer install --prefer-dist --optimize-autoloader --no-dev && wp-scripts plugin-zip",
"postinstall": "composer install",
"release": "./bin/release",
"start": "wp-scripts start --experimental-modules",
"start:decoupled": "./bin/start decoupled",
"start:monolith": "./bin/start monolith",
"start:monolith-xdebug": "./bin/start monolith-xdebug",
"start:playground": "npx @wp-now/wp-now start --php=8.2 --blueprint=blueprint.local.json",
"start:playground:reset": "npm run start:playground -- --reset",
"stop": "./bin/stop",
"start": "wp-scripts start --experimental-modules --stats=minimal",
"test": "npm run test:php && npm run test:js",
"test:php": "composer test",
"test:php:coverage": "composer test-coverage",
Expand Down

0 comments on commit 000e79f

Please sign in to comment.