Kanopi Pack is tool set designed to consolidate and ease the management of CSS and JS assets used in a web application along with the supporting packages which build them. The project is available for installation via NPM and documentation of the Why, When, and How for the tool are published in the Github repository

Readme⁠

Migrating a WordPress site to Kanopi Pack

There are many steps involved in converting a legacy site or creating a new site, using

Kanopi Pack⁠

. Below, they are detailed in the steps recommended. This is meant to be a high-level overview with explanations. Considerations may be needed on a project-to-project basis.

Composer

Docksal

WP Config

MU Plugins

Theme

CircleCI and Tugboat changes are not referenced here, as that should be handled by the TechOps team. However, any compiled changes should NOT be stored in the repo, and instead, handled via CI.

Composer

In your project root, you will need to have a composer.json file. This is separate from your WordPress theme files.

You should ensure that the name is unique to your project. It’s highly suggested that you match this to the GitHub repo name (in this case, ftd-fpi).

The example composer.json file below is for a Pantheon-based, fully composer build.

Remove the johnpbloch/wordpress-core package if you do not manage core via Composer. However, the rest is required for use of the Kanopi Pack Asset Loader, and the updated PHPCS standards.

If you do manage core via Composer, to add contributed plugins, run composer require wpackagist-plugin/[plugin name]. You can search for these on WPackagist, or simply by taking the slug from the official Plugin repo, and using that for the plugin name.

This sample uses PHPCS, you can read more about WordPress configuration of PHPCS in this

Cacher⁠

IMPORTANT: This is a blueprint which is not up to date. The listed versions of packages are being updated regularly, please check and update the version of PHP, WordPress Core, and Kanopi Pack based on the latest supported version available through NPM and Composer.

NOTE: If your project is a Pantheon-hosted site, the root of your WordPress site and hence its files are in the web/ subfolder. Sites on WPEngine and many legacy support projects store WordPress in the root directory. Check configuration file paths to ensure they use the correct root path.

{

"name": "kanopi/name-of-project",

"description": "",

"type": "project",

"keywords": [],

"repositories": {

"wpackagist": {

"type": "composer",

"url": "https://wpackagist.org"

}

"require": {

"php": ">=8.2",

"composer/installers": "2.x-dev",

"johnpbloch/wordpress-core": "6.3",

"kanopi/pack-asset-loader": "~1.0.2"

"require-dev": {

"automattic/vipwpcs": "~3.0.0",

"phpunit/phpunit": "~9.5.3",

"roave/security-advisories": "dev-master",

"config": {

"vendor-dir": "web/wp-content/mu-plugins/vendor",

"preferred-install": "dist",

"optimize-autoloader": true,

"sort-packages": true,

"platform": {

"php": "8.2"

"allow-plugins": {

"composer/installers": true,

"cweagans/composer-patches": true,

"dealerdirect/phpcodesniffer-composer-installer": true,

"oomphinc/composer-installers-extender": true

}

"scripts": {

"move-core-files": "rsync -az --delete --exclude 'wp-content' web/wp-content/mu-plugins/vendor/johnpbloch/wordpress-core/* web/; echo 'Moved core files to web directory' ",

"post-install-cmd": [

"@move-core-files"

"post-update-cmd": [

"@move-core-files"

"code-sniff": [

"Composer\\Config::disableProcessTimeout",

"web/wp-content/mu-plugins/vendor/bin/phpcs --standard=\"./.phpcs.xml.dist\" web/wp-content/"

"code-fix": [

"Composer\\Config::disableProcessTimeout",

"web/wp-content/mu-plugins/vendor/bin/phpcbf --standard=\"./.phpcs.xml.dist\" web/wp-content/"

]

"extra": {

"installer-paths": {

"web/wp-content/plugins/{$name}/": [

"type:wordpress-plugin"

"web/wp-content/themes/{$name}/": [

"type:wordpress-theme"

"web/wp-content/themes/custom/{$name}/": [

"type:wordpress-theme-custom"

]

}

Docksal

.env

Below is a Pantheon-specific example for your docksal.env file. For WPEngine sites, change the stack to default, and the DOCROOT to .

DOCKSAL_STACK=pantheon

CLI_IMAGE='docksal/cli:php8.2-3.5'

# Docksal configuration.

DOCROOT=web

# Enable/disable xdebug

# To override locally, add .docksal/docksal-local.env and set XDEBUG_ENABLED=1

XDEBUG_ENABLED=0

# WordPress settings

WP_ADMIN_USER=example

WP_ADMIN_PASS=example

WP_ADMIN_EMAIL=example_email_address

# Change the following to match the project theme name

WP_THEME_SLUG=custom/theme-name

WP_THEME_RELATIVE_PATH=wp-content/themes/$WP_THEME_SLUG

# Subdomain used to proxy the Kanopi Pack dev server assets

WP_THEME_ASSETS_HOST_SUBDOMAIN=theme-assets

# Local ssl certs folder

CONFIG_CERTS="${CONFIG_CERTS:-$HOME/.docksal/certs}"

# Set hosting details for Pull command (Pantheon specific)

# Put any specific variables for your refresh command here.

.yml

version: "2.1"

services:

web:

extends:

file: ${HOME}/.docksal/stacks/services.yml

service: nginx

environment:

- APACHE_FILE_PROXY

- WP_THEME_ASSETS_HOST_SUBDOMAIN

- WP_THEME_RELATIVE_PATH

- WP_THEME_SLUG

- NGINX_VHOST_PRESET=wordpress

cli:

environment:

- WP_ADMIN_USER

- WP_ADMIN_PASS

- WP_ADMIN_EMAIL

- WP_THEME_RELATIVE_PATH

- WP_THEME_ASSETS_HOST_SUBDOMAIN

- WP_THEME_SLUG

- COMPOSER_MEMORY_LIMIT=-1

- VIRTUAL_HOST

- CONFIG_CERTS

- DB_HOST=db

- DB_NAME=default

- DB_USER=user

- DB_PASSWORD=user

labels:

- io.docksal.virtual-host=${WP_THEME_ASSETS_HOST_SUBDOMAIN}.${VIRTUAL_HOST}

- io.docksal.virtual-port=4400

expose:

- 4400

pma:

hostname: pma

image: phpmyadmin/phpmyadmin

environment:

- PMA_HOST=db

- PMA_USER=root

- PMA_PASSWORD=${MYSQL_ROOT_PASSWORD:-root}

labels:

- io.docksal.virtual-host=pma.${VIRTUAL_HOST}

Commands

You will need to create or update the following commands:

fin init

fin init-site

fin development

fin production

fin init-theme-assets

fin npm

Please copy these from (this Cacher)[

https://snippets.cacher.io/snippet/c0ba9321b584bfa1c756⁠

WP Config

For Kanopi Pack to be able to run its development server, you will need to add the following code to your wp-config-local.php (for Pantheon) or wp-config.php (for WPEngine and other projects):

/**

* For Front-end Development Server to be served via @kanopi/pack

define('KANOPI_DEVELOPMENT_ASSET_URL', 'https://' . getenv('WP_THEME_ASSETS_HOST_SUBDOMAIN') . '.' . getenv('VIRTUAL_HOST'));

For Docksal configurations, keep a copy of this configuration file in .docksal/etc/config and copy it into the root of the WordPress site in the init-site command.

MU-Plugins

Within the mu-plugins folder, situated under wp-content, you will need the following code added. The filename suggestion is 001-kanopi-app-loader.php. This is required for the Asset Loader to work. Please make sure to exclude it from the .gitignore.

<?php

/**

* Plugin Name: Kanopi MU Plugin Application Loader

* Author: Kanopi, Inc.

* Author URI: https://kanopi.com

* Description: Kanopi Autoloader initializes Composer-based Autoloader along with required plugins

* @wordpress-plugin

* Version: 1.0.0

// Run the autoloader for the site if not loaded externally

if ( ! class_exists( 'Kanopi\Assets\Registry\WordPress' ) ) {

if ( ! file_exists( WP_CONTENT_DIR . '/mu-plugins/vendor/autoload.php' ) ) {

wp_die( 'Unable to run theme autoloader.' );