isabella232 / newspack-scripts

Tooling for Newspack

newspack-scripts

Scripts for Newspack, heavily inspired by react-scripts.

---

Available scripts

test

Will run jest tests. Useful flags:

• --watch to run in file watch mode,
• --coverage to collect test coverage

build

Will run calypso-build, creating optimised production builds.

watch

Will run calypso-build in watch mode.

commit

Uses commitizen to create a structured commit message.

commitlint

Lints to commit message, to be used in a git commit-msg hook.

release

Will run semantic-release based on a very opinionated configuration.

typescript-check

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"
  },
  "include": ["src"]
}

---

Semantic Release

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:

1. master – ongoing development
2. alpha – release candidate
3. release – the production-ready, released code

The following assumes that CI will run:

1. npm run release for release, alpha, and hotfix/* branches
2. post-release.sh script on release branch, after the above command completes

Regular release flow

1. Commit ongoing changes to master branch, using structured commit messages
2. Merge master into alpha to create a release candidate (e.g. 1.2.0-alpha.1)
3. Merge alpha into release to create a release (e.g. 1.2.0)
4. alpha branch will be reset on top of release
5. master branch will be updated with the changes from the release branch

Hotfix release flow

1. Create a new hotfix/* branch off the release branch
2. Push the branch to Github, so the CI can process it – don't create a PR just yet!*
3. A new "hotfix" pre-release (e.g. 1.2.0-hotfix.1) will be published
4. Merge the hotfix branch into release to create a release
5. alpha & master 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

---

Available configs

This package exposes a couple of configuration files.

Webpack

The webpack.config.js file should use this package's config-extending function:

const getBaseWebpackConfig = require( 'newspack-scripts/config/getWebpackConfig' );

const webpackConfig = getBaseWebpackConfig(
  { WP: true },
  {
    entry: {
      'some-script': './src/some-script.js'
    },
  }
);

module.exports = webpackConfig;

Babel

A basic babel.config.js:

module.exports = api => {
  api.cache( true );
  return {
    extends: 'newspack-scripts/config/babel.config.js',
  };
};

eslint

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…
};

stylelint

Install stylelint via npm and reference this package's config file when running it, e.g.:

stylelint '**/*.scss' --syntax scss --config=./node_modules/newspack-scripts/config/stylelint.config.js

Note: Due to issue with dependency resolving, you might end up a different version of prettier in project's node_modules and node_modules/newspack-scripts/node_modules. See Automattic#1 for more information.

TypeScript

See note about typescript-check script above.

---

CircleCI Orb

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: adekbadek/[email protected]

workflows:
  version: 2
  all:
    jobs:
      - newspack/build

Updating the Orb

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 adekbadek/newspack@version

---

Misc

@wordpress/* packages

This project list @wordpress/* packages as dependencies in order to provide them to consumers. In a project using calypso-build (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.