Skip to content
What is Kanopi Pack and Why are we using it?
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 .
Migrating a WordPress site to Kanopi Pack
There are many steps involved in converting a legacy site or creating a new site, using . 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.
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
{
"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:
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.' );
}
include_once WP_CONTENT_DIR . '/mu-plugins/vendor/autoload.php';
}
Theme
NPM Packages
Want to print your doc?
This is not the way.
This is not the way.
Try clicking the ⋯ next to your doc name or using a keyboard shortcut (
CtrlP
) instead.