Skip to content

Commit

Permalink
Merge branch 'feature/node-integration' into feature/1password-cli-in…
Browse files Browse the repository at this point in the history
…tegration

# Conflicts:
#	CHANGELOG.md
  • Loading branch information
dpellenwood committed Jan 10, 2025
2 parents 97be4b8 + 071710c commit 6987633
Show file tree
Hide file tree
Showing 8 changed files with 137 additions and 41 deletions.
16 changes: 13 additions & 3 deletions .lando.yml
Original file line number Diff line number Diff line change
@@ -1,20 +1,23 @@
name: moose
recipe: wordpress

config:
php: '8.3'
database: mariadb:11.5
composer_version: 2-latest
via: nginx
xdebug: false
memcached: true

services:
appserver:
run:
- composer install
- composer run copy-local-configs
build:
- composer create-local-configs
overrides:
environment:
- XDEBUG_TRIGGER=1
node:
type: node:22

# Enabling MailHog will cause an error on start: `/bin/sh: 1: curl: not found`.
# Related GH Issue: https://github.com/lando/mailhog/issues/35
Expand All @@ -30,7 +33,14 @@ services:
# - appserver_nginx
# - appserver

events:
post-start:
- appserver: composer install
- node: npm install && npm run build

tooling:
npm:
service: node
xdebug-on:
service: appserver
description: Enable xdebug for nginx.
Expand Down
4 changes: 4 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,10 @@ item (Added, Changed, Depreciated, Removed, Fixed, Security).

## [2025.01]

- Added: Node service to Lando so FE assets can be built automatically on start up.
- Updated: project start up scripts to automatically generate the correct contents of the lcoal config files.
- Updated: script to install WordPress so we can use a version constant and not install WP every time composer is
installed or updated.
- Updated: ESLint config now supports browser environment variable such as `IntersectionObserver`
- Added: ability for table blocks to utilize the `overflow-x` set on them by setting a `min-width` property for the
`table` element within the table block.
Expand Down
18 changes: 11 additions & 7 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,8 @@ maintained by the folks at [Modern Tribe](https://tri.be).
* [Git](https://git-scm.com/)
* [Composer](https://getcomposer.org/)
* [Node & NPM](https://nodejs.org/)
* [NVM](https://github.com/nvm-sh/nvm) is recommended for managing multiple versions of node on the same workstation.
* [NVM](https://github.com/nvm-sh/nvm) is recommended for managing multiple versions of node on the same
workstation.
* [Lando](https://lando.dev/) (Optional) Provides a consistent local development environment for all team members.
* [1Password CLI](https://developer.1password.com/docs/cli/) (Optional) Automates the creation of composer's `auth.json`
file so that paid 3rd-party plugins like Advanced Custom Fields Pro and Gravity Forms can be installed via composer.
Expand All @@ -28,12 +29,11 @@ maintained by the folks at [Modern Tribe](https://tri.be).
[1Password CLI](#1password-cli). See the [Composer Docs](./docs/composer.md#creating-an-authjson-file) for manual
instructions.)
3. Run `lando start` to create the local environment.
4. Run `nvm use` to ensure the correct version of node is in use.
5. Run `npm install` to install the required npm dependencies.
6. Run `npm run dist` to build the theme assets.

That should be it! After Lando starts the first time, it should automatically trigger a composer install and create the
necessary local config files for the project.
That should be it! After Lando starts the first time, it will automatically create the necessary local config files for
the project. Additionally, each time Lando starts it will automatically run `composer install` and
`npm install && npm run build` to make sure all the project dependencies are installed and the theme assets have been
built.

## Documentation

Expand All @@ -47,6 +47,7 @@ members to use and provides a number of helpful features. Below are a number of
* `lando poweroff` - Completely shuts down all running Lando services.
* `lando composer <command>` - Runs a composer command within the project container.
* `lando wp <command>` - Runs a WP-CLI command within the project container.
* `lando npm <command>` - Runs an npm command within the node container. Useful for rebuilding the theme assets.
* `lando db-export` - Exports the project database to a file in the project root.
* `lando db-import <filename.sql>` - Imports a database file into the project database. This file must be located within
the project directory. It can be either an archived (`.zip`) or unarchived SQL (`.sql`) file.
Expand All @@ -56,6 +57,8 @@ members to use and provides a number of helpful features. Below are a number of
* `lando destroy` - Destroys the local development environment. *WARNING:* This is a destructive action and will delete
the existing data within the project database and completely remove all the project containers. It will not delete the
project files on your local machine.
* `lando xdebug-on` - Enables Xdebug in the project container (xDebug is disabled by default).
* `lando xdebug-off` - Disables Xdebug in the project container (xDebug is disabled by default).

For further documentation on Lando, please visit the [Lando Docs](https://docs.lando.dev/).

Expand All @@ -67,7 +70,8 @@ day-to-day PHP development. You can learn more about the available scripts and h

#### Updating WordPress

To adjust the installed version of WordPress, change the `--version=` value in the `install-wordpress` composer script.
To adjust the installed version of WordPress, run `composer config extra.wordpress-version <new-version>` and then
`composer install-wordpress`.

### NPM Packages, Scripts & Building Frontend Assets

Expand Down
12 changes: 5 additions & 7 deletions composer.json
Original file line number Diff line number Diff line change
Expand Up @@ -22,11 +22,8 @@
"prefer-stable": true,
"scripts": {
"create-auth": "op inject -i auth.template.json -o auth.json",
"copy-local-configs": [
"@php -r \"file_exists('local-config.php') || copy('local-config-sample.php', 'local-config.php');\"",
"@php -r \"file_exists('local-config.json') || copy('local-config-sample.json', 'local-config.json');\""
],
"install-wordpress": "./vendor/bin/wp core download --version=6.7.1 --skip-content --force",
"create-local-configs": "php ./dev/scripts/create-local-configs.php",
"install-wordpress": "./dev/scripts/install-wordpress.sh",
"phpcbf": "./vendor/bin/phpcbf -s",
"phpcs": "./vendor/bin/phpcs",
"phpstan": "./vendor/bin/phpstan analyse --memory-limit=-1",
Expand All @@ -40,8 +37,8 @@
},
"scripts-descriptions": {
"create-auth": "Create or update the auth.json file for Composer via 1Password CLI.",
"copy-local-configs": "Copies the local-config.php and local-config.json files.",
"install-wordpress": "Runs the wpcli command to download and install core WordPress. To change the WordPress version, update the --version value.",
"create-local-configs": "Creates local config files for the project.",
"install-wordpress": "Runs the WP CLI command to download and install WordPress. To change the WordPress version, run `composer config extra.wordpress-version <new-version>`.",
"phpcs": "Run PHPCS on the project.",
"phpcbf": "Run PHPCBF on the project.",
"phpstan": "Run PHPStan on the project.",
Expand Down Expand Up @@ -123,6 +120,7 @@
"wpengine/advanced-custom-fields-pro": "6.3.11"
},
"extra": {
"wordpress-version": "6.7.1",
"installer-paths": {
"wp-content/plugins/{$name}": [
"type:wordpress-plugin"
Expand Down
59 changes: 59 additions & 0 deletions dev/scripts/create-local-configs.php
Original file line number Diff line number Diff line change
@@ -0,0 +1,59 @@
<?php declare(strict_types=1);
/**
* Copies the local-config-sample.php file to local-config.php if it doesn't exist.
* Generates a local-config.json file using Lando's own environment variables if it doesn't exist.
*/

if ( ! file_exists( '.lando.yml' ) ) {
// This script should only be run from the root of the project, not called directly in a browser.
die();
}

/**
* PHP Local Config
*/

if ( file_exists( 'local-config.php' ) ) {
echo "local-config.php already exists. Skipping.\n";
} else {
copy('local-config-sample.php', 'local-config.php');
}

/**
* JSON Local Config
*/

if ( ! getenv( 'LANDO_INFO' ) ) {
echo "To create a local-config.json file, this script must be run within a Lando container.\n";
echo "Try `lando composer create-local-configs` if you're using Lando or manually create the file using local-config-sample.json as an example.\n";
exit;
}

if ( file_exists( 'local-config.json' ) ) {
echo "local-config.json already exists. Skipping.\n";
exit;
}

$lando_info = json_decode( getenv( 'LANDO_INFO' ) );

// Get the HTTP server details, depending on the project configuration
$http_service_info = $lando_info->appserver->via === 'apache' ? $lando_info->appserver : $lando_info->appserver_nginx;

// Get the cert directory by removing the root `/lando` directory from Lando's internal cert path
$cert_directory = str_replace( '/lando', '', dirname( getenv( 'LANDO_SERVICE_CERT' ) ) );

// Create the config array
$config = [
// Append Lando's cert directory to Lando's local config directory path
'certPath' => getenv( 'LANDO_CONFIG_DIR' ) . $cert_directory,
// Set the cert name to the base name of Lando's hostname without the `.internal` extension
'certName' => basename( $http_service_info->hostnames[0], '.internal' ),
// Set the host from Lando's service URL
'host' => parse_url( $http_service_info->urls[0] )['host'],
'protocol' => 'https'
];

// Write the config values to local-config.json
file_put_contents( 'local-config.json', json_encode( $config, JSON_PRETTY_PRINT | JSON_UNESCAPED_SLASHES ) );

exit;
14 changes: 14 additions & 0 deletions dev/scripts/install-wordpress.sh
Original file line number Diff line number Diff line change
@@ -0,0 +1,14 @@
#!/bin/bash
# Simple bash script to check the current version of WordPress and update it if necessary.

CURRENT_VERSION=$(wp core version)
REQUESTED_VERSION=$(composer config extra.wordpress-version)

if [ "$CURRENT_VERSION" == "$REQUESTED_VERSION" ]; then
echo "WordPress is already at version $REQUESTED_VERSION. Skipping install."
exit 0
fi

echo "Updating WordPress to version $REQUESTED_VERSION..."
wp core download --version=$REQUESTED_VERSION --skip-content --force
exit 0;
29 changes: 15 additions & 14 deletions docs/composer.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,19 +13,19 @@ day-to-day PHP development.

* `composer create-auth` - Create or update the auth.json file for Composer via 1Password CLI. (Cannot be run within a
Lando container.)
* `composer copy-local-configs` - Creates the `local-config.php` and `local-config.json` files from the respective
sample file.
* `composer install-wordpress` - Runs the WP CLI command to download and install WordPress core. To change the WordPress
version, update the `--version` value for this script.
* `composer create-local-configs` - Creates the `local-config.php` and `local-config.json` files as needed for the
project.
* `composer install-wordpress` - Runs the WP CLI command to download and install WordPress core.
* `composer phpcs` - Run PHPCS on the project.
* `composer phpcbf` - Run PHPCBF on the project.
* `composer phpstan` - Run PHPStan on the project.
* `composer update-db` - Runs the WP CLI command to update the WordPress database. This is often required after a
* `composer update-db` - Runs the WP CLI command to update the WordPress database. This is often required after a
WordPress version update.

## Updating WordPress

To adjust the installed version of WordPress, change the `--version=` value in the `install-wordpress` composer script.
To adjust the installed version of WordPress, run `composer config extra.wordpress-version <new-version>` and then
`composer install-wordpress`.

## Adding a Paid or Premium WordPress Plugin

Expand All @@ -34,28 +34,29 @@ WordPress plugin directory and thus can't be installed from `https://wpackagist.
installing such premium plugins:

1. Check to see if the plugin maker provides its own composer-based installation method. This is the best option.
Many providers including Advanced Custom Fields (ACF), Gravity Forms, and Yoast SEO provide composer-based installation
options. This project is already configured to use composer for both ACF and Gravity Forms.
Many providers including Advanced Custom Fields (ACF), Gravity Forms, and Yoast SEO provide composer-based
installation
options. This project is already configured to use composer for both ACF and Gravity Forms.
1. Check the plugin files into the repository directly. This is the simplest option but is not ideal for a number of
reasons, including licensing, security, and ease of management.
reasons, including licensing, security, and ease of management.

### Creating an auth.json File

If the plugin maker provides a composer-based installation method, you will likely create an `auth.json` file to
store the required credentials. This file is used by composer to install the plugin. This project provides an
If the plugin maker provides a composer-based installation method, you will likely create an `auth.json` file to
store the required credentials. This file is used by composer to install the plugin. This project provides an
auth.json template file that the 1Password CLI can use to automatically generate the required `auth.json` file. See the
[1Password CLI Docs](./1password-cli.md) for more information on this integration.

To manually create the `auth.json` file, copy the `auth.template.json` file to `auth.json` and update the placeholder
To manually create the `auth.json` file, copy the `auth.template.json` file to `auth.json` and update the placeholder
values within the file with the required credentials.

> [!IMPORTANT]
> The populated `auth.json` file should never be checked into the git repository as it contains
> The populated `auth.json` file should never be checked into the git repository as it contains
> project-specific secrets (software license keys) which should never be available in source control.
## Platform Dependencies

There are several PHP platform dependencies added as composer requirements. These dependencies include the required
version of PHP as well as several PHP extensions required by WordPress (`ext-exif`, `ext-gd`, `ext-intl`, & `ext-json`).
These PHP extensions are installed within a [project's Dokku env](actions.md#dokku-deployment-workflows) and should not
These PHP extensions are installed within a [project's Dokku env](actions.md#dokku-deployment-workflows) and should not
be removed unless or until Dokku is not utilized by the project.
26 changes: 16 additions & 10 deletions docs/npm.md
Original file line number Diff line number Diff line change
@@ -1,26 +1,31 @@
# NPM Packages, Scripts & Building Assets

NPM is used to manage frontend dependencies. There are also a number of npm scripts defined to assist in day-to-day
development. These npm scripts are based on WordPress's [WP-Scripts](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-scripts/) package. See the documentation there for
further details.
development. These npm scripts are based on
WordPress's [WP-Scripts](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-scripts/)
package. See the documentation there for further details.

## Building Assets

To build the theme assets for your local development environment, the following steps are sufficient:
If you are not working with the theme assets locally, and you are using Lando, you can skip this section. Lando will
automatically build the assets for you each time the project is started. To manually build the theme assets for your
local development environment, use the following steps:

1. In the root of the project, run `nvm use` to confirm the correct version of node is in-use.
1. Run `npm install` to install the required dependencies.
1. Run `npm run dist` to build the production assets
1. Run `npm run build` to build the non-production assets.

## Using Browsersync for Local Dev

To handle live-reload for changes, this project utilizes Browsersync to watch for asset file changes and reload the
browser. In addition, Browsersync can be configured via a `local-config.json` file to proxy your local environment's
SSL configuration to allow live-reloading from a specific local project URL rather than localhost. To use Browsersync
for local development follow the steps below:
To handle live-reload for changes, this project utilizes Browsersync to watch for asset file changes and reload the
browser. In addition, Browsersync can be configured via a `local-config.json` file to proxy your local environment's
SSL configuration to allow live-reloading from a specific local project URL rather than localhost.

Lando will automatically generate an proper local-config.json file the first time a project is started. If you are not
using Lando, you'll need to manually create this file using the steps below:

1. Duplicate the `local-config-sample.json` file into a git-ignored `local-config.json` and update the `certsPath`,
`certName` and `host` values to match your local dev set up. Examples are provided for Lando and LocalWP.
`certName` and `host` values to match your local dev set up. Examples are provided for Lando and LocalWP.
1. In the root of the project, run `nvm use` to confirm the correct version of node is in-use.
1. Run `npm install` to install the required dependencies.
1. Run `npm run dev` to start the webpack watch & browsersync tasks.
Expand All @@ -33,7 +38,8 @@ for local development follow the steps below:
* `npm run format` - Runs Prettier on all theme assets (css, scss, js, & json files).
* `npm run lint` - Prettifies, lints (and fixes) theme & root assets (css, scss, js, & json files).
* `npm run create-block` - Starts an interactive shell script to generate a new block per WordPress's
[Create Block script](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-create-block/) and the theme config.
[Create Block script](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-create-block/)
and the theme config.

Several scripts have sub-tasks that can be run individually. Reference `package.json` for details.
Additionally, there are several scripts aliased directly from wp-scripts that may be useful:
Expand Down

0 comments on commit 6987633

Please sign in to comment.