DTRT NPM Scripts

NPM build scripts.

Background

• Migrating Gulp build tasks to NPM scripts.

Dependencies

1. Composer - https://getcomposer.org/doc/00-intro.md#installation-linux-unix-macos
2. Mono (Natural Docs' framework) - https://www.mono-project.com/download/stable/ (deprecated)
3. Natural Docs - https://www.naturaldocs.org/download/ and save to ./bin/Natural Docs (deprecated)
4. n - https://www.npmjs.com/package/n

Set up Github Actions CI

The Github Actions CI build needs access to Github in order to provide Composer with permissions to clone the private repo wpdtrt-dbth repository.

Ensure that this repository, and any repository using this repository, have an Actions Secret named GH_TOKEN which contains the value of a dedicated or shared Personal Access Token from https://github.com/settings/tokens.

See https://github.com/dotherightthing/generator-wpdtrt-plugin-boilerplate/wiki/Set-up-Github-Actions-CI

Installation

Note: #semver:* downloads the latest tagged version of this repository. Omit #semver:* to download the latest development version.

n 18.7.0 # change node version (see package.json - engines.node)
npm install dotherightthing/wpdtrt-npm-scripts#semver:* --save-dev

Files

1. .gitignore

Please add these lines to your .gitignore:

# Files supporting or generated by wpdtrt-npm-scripts
config/naturaldocs
css
cypress.config.js
release*
!.github/workflows/release*
.babelrc
.browserslistrc
.eslintrc
.stylelint*
mochawesome-report
nodemon.json
phpcs.xml
phpunit.xml.dist
postcss.config.js
bin/Natural\ Docs
js/backend*.js
js/frontend*.js
docs
node_modules
vendor
# End

2. CHANGELOG.md

This file contains a list of changes in the current version/tag.

Please commit this (initially empty) file and push it to your Github repository.

See also #33.

npm run version will populate this with all changes since the last tag.

3. composer.json (optional)

Please add these lines to your composer.json:

  "require-dev": {
    "wp-coding-standards/wpcs": "^0.14.1",
    "dealerdirect/phpcodesniffer-composer-installer": "^0.4.4",
    "phpunit/phpunit": "^7.5.14",
    "psy/psysh" : "~0.6",
    "wp-cli/wp-cli": "^2.3",
    "yoast/phpunit-polyfills": "^1.0"
  },

See also #19.

4. .github

This folder is generated by wpdtrt-npm-scripts. It contains configurations file for Github Actions (Continuous Integration).

Please commit this folder and push it to your Github repository.

5. package.json

Please add these lines to your package.json:

  "config": {
    "wpdtrt_base_url_local": "http://domain.local",
    "wpdtrt_npm_scripts": "./node_modules/wpdtrt-npm-scripts"
  },
  "scripts": {
    "compile": "npm run compile --prefix $npm_package_config_wpdtrt_npm_scripts",
    "docs": "npm run docs --prefix $npm_package_config_wpdtrt_npm_scripts",
    "lint": "npm run lint --prefix $npm_package_config_wpdtrt_npm_scripts",
    "release": "npm run release --prefix $npm_package_config_wpdtrt_npm_scripts",
    "scrape:wordpress_maintenance_page": "npm run scrape:wordpress_maintenance_page --prefix $npm_package_config_wpdtrt_npm_scripts -- $npm_package_config_wpdtrt_base_url_local",
    "test": "npm run test --prefix $npm_package_config_wpdtrt_npm_scripts",
    "test:js": "npm run test:js --prefix $npm_package_config_wpdtrt_npm_scripts",
    "version": "npm run version --prefix $npm_package_config_wpdtrt_npm_scripts",
    "watch": "nodemon"
  },

Note:

• config.wpdtrt_base_url_local is used by WordPress themes with scrape:wordpress_maintenance_page. Change the value to match your local staging server.
• --prefix forces non-global commands to run in the specified folder
• $npm_package_config_wpdtrt_npm_scripts = the value of package.json's config.wpdtrt_npm_scripts
• npx cypress run cannot be appended to the test script (see #46)

6. tests/bootstrap.php (optional)

Plugins

See https://github.com/dotherightthing/generator-wpdtrt-plugin-boilerplate/blob/master/generators/app/templates/tests/bootstrap.php

Themes

<?php
/**
 * PHPUnit bootstrap file for wpdtrt-npm-scripts
 */

// .

7. README.md

Add the following badges:

[![GitHub release](https://img.shields.io/github/v/tag/AUTHOR/REPO)](https://github.com/AUTHOR/REPO/releases) [![Build Status](https://github.com/AUTHOR/REPO/workflows/Build%20and%20release%20if%20tagged/badge.svg)](https://github.com/AUTHOR/REPO/actions?query=workflow%3A%22Build+and+release+if+tagged%22) [![GitHub issues](https://img.shields.io/github/issues/AUTHOR/REPO.svg)](https://github.com/AUTHOR/REPO/issues)

8. js/backend.txt

Please create this file and push it to your Github repository.

Add a list of files to bundle into backend.js, one file per line, with a trailing blank line.

This process allows other DTRT scripts to be included in the linting and transpiling process.

It is not intended to replace WordPress JavaScript loading.

./vendor/dotherightthing/wpdtrt-plugin-boilerplate/js/_backend.js
./js/_backend.js

9. js/frontend.txt

Please create this file and push it to your Github repository.

Add a list of files to bundle into frontend.js, one file per line, with a trailing blank line.

This process allows other DTRT scripts to be included in the linting and transpiling process.

It is not intended to replace WordPress JavaScript loading.

./js/_frontend_.js

Update

npm update wpdtrt-npm-scripts

Uninstallation

npm uninstall wpdtrt-npm-scripts

Usage

Compile

npm run compile
# or
npm run watch

Input	Script	Config	Compiler	Output
*.scss	compile/css.sh		Dart Sass	*.css
*.css	compile/css.sh	postcss.config.js	PostCSS	*.css
backend.txt	compile/js.sh	.babelrc	Custom merge + Babel	backend-es5.js
frontend.txt	compile/js.sh	.babelrc	Custom merge + Babel	frontend-es5.js

Document

Note: this feature is currently untested.

npm run docs

Lint

npm run lint

Input	Script	Config	Linter
*.scss	lint/css.sh	.stylelintignore, .stylelintrc.json	Stylelint
*.js	lint/js.sh	.eslintrc	ESLint
composer.json	lint/php.sh	-	Composer
*.php	lint/php.sh	phpcs.xml	PHP Code Sniffer (PHPCS)

Note: linting errors may cause the script to exit before all issues have been logged. In this case, fix the errors then run the script again.

Release

Bundle files for release by the CI:

npm run release

Scrape

Scrape WordPress maintenance page to /maintenance.php:

npm run scrape:wordpress_maintenance_page

This requires a (locally) published page with a slug of maintenance-template.

Test

# Run PHPUnit tests
npm run test

# Run Cypress JavaScript unit and UI tests
npm run test:js

Input	Script	Config	Testing Framework	Output
e2e/*.cy.js	test/cypress.mjs	cypress.config.js	Cypress	mochawesome-report
src/	test/phpunit.sh	phpunit.xml.dist	PHPUnit	-

See also DTRT WordPress Plugin Boilerplate - Testing & Debugging

Version

• Update package.json and package-lock.json
• Update CHANGELOG.md with all commit messages since the last tag, version files for Release
• Update version strings in project files
• Tag commit

npm run version --v=1.2.3

---

Maintenance

Lint

npm run lint:internal

Test

Tests are written in Mocha, with Chai assertions.

Execa is used to verify the output of Shell and Node child processes.

# Test against fixtures loaded by Composer
npm run test:internal

Release

1. Lint and Test the codebase (see above)
2. npm run version:internal --v=1.2.3
   • Update test fixtures
   • Update: composer.lock, package.json and package-lock.json
   • Update CHANGELOG.md with all commit messages since the last tag
   • Tag commit
3. Push to Github (Github Actions CI will run)