Scripts for Newspack, heavily inspired by react-scripts
.
Repos consuming the newspack-scripts
package can use the following NPM scripts. Prefix each at the command line with npm run
(or bun run
) to execute.
Execute with npm start
. This is the only script you run without the run
prefix. This will install Composer and NPM dependencies, then run the watch
command to start a development build. Best used when cloning a repo for the first time, or when you need to restore a locally cloned repo to a fresh state.
Will run wp-scripts build
to create optimised production builds.
Will run wp-scripts start
to start a development build in devserver/watch mode.
Will run wp-scripts lint-js
, wp-scripts lint-style
, or both. See the @wordpress/scripts
handbook for implementation details and additional options.
Will run wp-scripts lint-js --fix
, allowing ESLint to correct any autofixable code quality errors it finds. Note that code quality errors are separate from formatting, which is handled by format:js
(see below).
Will run wp-scripts format-js
to reformat JS files according to Prettier rules. Note that formatting is separate from code quality errors, which are handled by fix:js
(see above).
Will run wp-scripts lint-style --fix
to reformat SCSS files according to Stylelint rules.
Will run jest
tests. Useful flags:
--watch
to run in file watch mode,--coverage
to collect test coverageWill run phpcs
or phpcbf
to lint or autofix PHP files, respectively. Note that you must install these PHP packages via composer install
or npm start
before you can use these locally.
Uses commitizen
to create a structured commit message.
Lints to commit message, to be used in a git commit-msg
hook.
Will run semantic-release
based on a very opinionated configuration.
Will validate TypeScript code in the project. This requires a tsconfig.json
file to be placed in the project root. Example:
{
"extends": "newspack-scripts/config/tsconfig.json",
"compilerOptions": {
"rootDir": "src",
"jsx": "react-jsx"
},
"include": [
"src",
"src/**/*.json"
]
}
This package contains a configuration of semantic-release
, which can be used for automated software releases, published on Github. It's configured to work with the following repository branch setup:
trunk
– ongoing developmentalpha
– release candidatehotfix/*
- for testing urgent bugfixesepic/*
- for testing large-scale featuresrelease
– the production-ready, released codeThe following assumes that CI will run:
npm run release
for release
, alpha
, hotfix/*
, and epic/*
branchespost-release.sh
script on release
branch, after the above command completestrunk
branch.trunk
. Changes must be tested and approved before merging.trunk
branch. When merging into trunk
, SQUASH the merge.trunk
into alpha
to create a release candidate (e.g. 1.2.0-alpha.1
). When merging trunk
into alpha
, DO NOT SQUASH the merge.alpha
into release
to create a production release (e.g. 1.2.0
). When merging alpha
into release
, DO NOT SQUASH the merge.alpha
branch will be reset on top of release
.trunk
branch will be updated with the changes from the release
branch.For large-scale features that require more than one interdependent branch throughout development.
epic/*
branch off the trunk
branch. Push the branch to GitHub so all engineers can work off it simultaneously. Keep this branch up-to-date with trunk
, to minimize the risk of merge conflicts.
epic/*
branch, to minimize the risk of merge conflicts.
epic/*
branch. Changes must be tested and approved before merging.epic/*
branch. When merging into epic/*
, DO NOT SQUASH the merge.1.2.0-epic-feature.1
) will be tagged and published when changes are merged via PR. Use epic releases for QA and other pre-release testing.epic/*
branch have been tested and approved, open a pull request for final review based on trunk
. Final review doesn't require full-scale functional testing, only a review of the changeset (as changes have already been tested in individual PRs).epic/*
branch to the trunk
branch. When merging an epic branch into trunk
, SQUASH the merge.epic/*
has been merged to trunk
, follow the regular release flow to generate release candidates and production releases.hotfix/*
branch off the release
branch.1.2.0-hotfix.1
) will be tagged and published.release
. Changes must be tested and approved before merging.release
to create a release. When merging a hotfix into release
, SQUASH the merge.alpha
& trunk
branches will be updated with the changes from the release
branch.* semantic-release
will not release if the CI job was triggered by a PR
This package exposes a couple of configuration files.
The webpack.config.js
file should use this package's config-extending function:
const getBaseWebpackConfig = require("newspack-scripts/config/getWebpackConfig");
const webpackConfig = getBaseWebpackConfig(
{
entry: {
'output-file': './src/entrypoint-file.js',
},
}
);
module.exports = webpackConfig;
A basic babel.config.js
:
module.exports = api => {
api.cache( true );
return {
extends: 'newspack-scripts/config/babel.config.js',
};
};
@wordpress/scripts
uses ESLint under the hood for JS code quality linting. Note that this is separate from code formatting, which is handled by Prettier (see below).
Because of ESLint's issue with resolving dependencies of extended configurations, a patch has to be used to use this config in a stand-alone fashion: install @rushstack/eslint-patch
and set up the .eslintrc.js
like so:
require( '@rushstack/eslint-patch/modern-module-resolution' );
module.exports = {
extends: [ './node_modules/newspack-scripts/config/eslintrc.js' ],
// Additional options…
};
@wordpress/scripts
uses Prettier under the hood for JS formatting. Note that this is separate from code quality, which is handled by ESLint (see above).
To configure Prettier rules, extend this repo's config by creating a .prettierrc.js
file like so:
const baseConfig = require( './node_modules/newspack-scripts/config/prettier.config.js' );
module.exports = {
...baseConfig,
// Additional options…
};
You should also include a .prettierignore
file to tell Prettier which files and directories it should ignore, using gitignore syntax:
dist
node_modules
release
vendor
@wordpress/scripts
uses Stylelint under the hood for SCSS linting and formatting.
newspack-scripts wp-scripts lint-style '**/*.scss' --customSyntax postcss-scss
Extend this repo's config with a .stylelintrc.js
file like so:
module.exports = {
extends: [ './node_modules/newspack-scripts/config/stylelint.config.js' ],
// Additional options…
};
See note about typescript-check
script above.
This repository hosts a CircleCI Orb, in /src
directory. An Orb is a re-usable configuration – here's an example of how to use it:
version: 2.1
orbs:
newspack: newspack/[email protected]
workflows:
version: 2
all:
jobs:
- newspack/build
To update the Orb, use CircleCI's CLI's pack
and publish
commands:
# Replace the `version` at the end (e.g. 1.0.1)
circleci orb pack src/ > orb.yml && circleci orb publish orb.yml newspack/newspack@version
Note that before the first time updating you'll need to set the API key for CircleCI CLI by running $ circleci setup
.
pwd | pbcopy
) and "install" it as an npm dependency in the repository on which you wish to test (e.g. npm i /path/to/newspack-scripts
). You should end up with a "newspack-scripts": "file:*"
entry in package.json
instead of a version number.npm run semantic-release -- --dry-run
@wordpress/*
packagesThis project lists @wordpress/*
packages as dependencies in order to provide them to consumers. In a project using @wordpress/scripts
(e.g. a consumer of newspack-scripts
), the @wordpress/*
packages are sourced from WP Core, not node_modules
. The packages should be included in node_modules
, though, to be available in other environments – notably when running tests. See Dependency Extraction Webpack Plugin for more information.