newspack-scripts 5.5.1 → 5.5.2

package/.circleci/config.yml

@@ -24,7 +24,7 @@ jobs:
           command: node --version
       - run:
           name: install
-          command: npm install
+          command: npm install --legacy-peer-deps
       - run:
           name: release
           command: npm run semantic-release || true

package/.eslintrc.js

@@ -0,0 +1,9 @@
+require( '@rushstack/eslint-patch/modern-module-resolution' );
+
+module.exports = {
+	extends: [ './config/eslintrc.js' ],
+	ignorePatterns: [ 'node_modules' ],
+	rules: {
+		'@typescript-eslint/no-var-requires': 'off',
+	},
+};

package/.nvmrc

@@ -1 +1 @@
-16.11.1
+lts/*

package/README.md

@@ -6,20 +6,46 @@ Scripts for Newspack, heavily inspired by [`react-scripts`](https://github.com/f
 
 ## Available scripts
 
-### test
+Repos consuming the `newspack-scripts` package can use the following NPM scripts. Prefix each at the command line with `npm run` (or [`bun run`](https://bun.sh/)) to execute.
 
-Will run `jest` tests. Useful flags:
+### start
 
-- `--watch` to run in file watch mode,
-- `--coverage` to collect test coverage
+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.
 
 ### build
 
-Will run `calypso-build`, creating optimised production builds.
+Will run `wp-scripts build` to create optimised production builds.
 
 ### watch
 
-Will run `calypso-build` in watch mode.
+Will run `wp-scripts start` to start a development build in devserver/watch mode.
+
+### lint:js, lint:scss, lint
+
+Will run `wp-scripts lint-js`, `wp-scripts lint-style`, or both. See the [`@wordpress/scripts` handbook](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-scripts/) for implementation details and additional options.
+
+### fix:js
+
+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).
+
+### format:js
+
+Will run `wp-scripts format-js` to reformat JS files according to [Prettier](https://prettier.io/) rules. Note that formatting is separate from code quality errors, which are handled by `fix:js` (see above).
+
+### format:scss
+
+Will run `wp-scripts lint-style --fix` to reformat SCSS files according to [Stylelint](https://stylelint.io/) rules.
+
+### test
+
+Will run `jest` tests. Useful flags:
+
+- `--watch` to run in file watch mode,
+- `--coverage` to collect test coverage
+
+### lint:php, fix:php
+
+Will 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.
 
 ### commit
 
@@ -39,11 +65,15 @@ Will validate TypeScript code in the project. This requires a `tsconfig.json` fi
 
 ```json
 {
-  "extends": "newspack-scripts/config/tsconfig.json",
-  "compilerOptions": {
-    "rootDir": "src"
-  },
-  "include": ["src"]
+	"extends": "newspack-scripts/config/tsconfig.json",
+	"compilerOptions": {
+		"rootDir": "src",
+		"jsx": "react-jsx"
+	},
+	"include": [
+		"src",
+		"src/**/*.json"
+	]
 }
 ```
 
@@ -115,12 +145,11 @@ 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",
-    },
-  }
+	{
+		entry: {
+			'output-file': './src/entrypoint-file.js',
+		},
+	}
 );
 
 module.exports = webpackConfig;
@@ -131,36 +160,69 @@ module.exports = webpackConfig;
 A basic `babel.config.js`:
 
 ```js
-module.exports = (api) => {
-  api.cache(true);
-  return {
-    extends: "newspack-scripts/config/babel.config.js",
-  };
+module.exports = api => {
+	api.cache( true );
+	return {
+		extends: 'newspack-scripts/config/babel.config.js',
+	};
+};
+```
+
+### ESLint
+
+`@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](https://github.com/eslint/eslint/issues/3458) 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:
+
+```js
+require( '@rushstack/eslint-patch/modern-module-resolution' );
+
+module.exports = {
+	extends: [ './node_modules/newspack-scripts/config/eslintrc.js' ],
+	// Additional options…
 };
 ```
 
-### eslint
+### Prettier
 
-Because of eslint's [issue](https://github.com/eslint/eslint/issues/3458) 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:
+`@wordpress/scripts` uses [Prettier](https://prettier.io/) 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:
 
 ```js
-require("@rushstack/eslint-patch/modern-module-resolution");
+const baseConfig = require( './node_modules/newspack-scripts/config/prettier.config.js' );
 
 module.exports = {
-  extends: ["./node_modules/newspack-scripts/config/eslintrc.js"],
-  // Additional options…
+	...baseConfig,
+	// Additional options…
 };
 ```
 
+You should also include a [`.prettierignore` file](https://prettier.io/docs/en/ignore.html) to tell Prettier which files and directories it should ignore, using [gitignore syntax](https://git-scm.com/docs/gitignore#_pattern_format):
+
+```
+dist
+node_modules
+release
+vendor
+```
+
 ### stylelint
 
-Install `stylelint` via npm and reference this package's config file when running it, e.g.:
+`@wordpress/scripts` uses [Stylelint](https://stylelint.io/) under the hood for SCSS linting and formatting.
 
 ```shell
-stylelint '**/*.scss' --syntax scss --config=./node_modules/newspack-scripts/config/stylelint.config.js
+newspack-scripts wp-scripts lint-style '**/*.scss' --customSyntax postcss-scss
 ```
 
-_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 https://github.com/Automattic/newspack-scripts/issues/1 for more information._
+Extend this repo's config with a `.stylelintrc.js` file like so:
+
+```js
+module.exports = {
+	extends: [ './node_modules/newspack-scripts/config/stylelint.config.js' ],
+	// Additional options…
+};
+```
 
 ### TypeScript
 
@@ -207,4 +269,4 @@ Note that before the first time updating you'll need to set the API key for Circ
 
 ### `@wordpress/*` packages
 
-This project list [`@wordpress/*` packages](https://github.com/WordPress/gutenberg/tree/trunk/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](https://www.npmjs.com/package/@wordpress/dependency-extraction-webpack-plugin) for more information.
+This project lists [`@wordpress/*` packages](https://github.com/WordPress/gutenberg/tree/trunk/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](https://www.npmjs.com/package/@wordpress/dependency-extraction-webpack-plugin) for more information.

package/bin/newspack-scripts.js

@@ -1,43 +1,43 @@
 #!/usr/bin/env node
 
-const spawn = require("cross-spawn");
-const utils = require("../scripts/utils/index.js");
+const spawn = require( 'cross-spawn' );
+const utils = require( '../scripts/utils/index.js' );
 
-const [scriptName, ...nodeArgs] = process.argv.slice(2);
+const [ scriptName, ...nodeArgs ] = process.argv.slice( 2 );
 
 if (
-  [
-    "test",
-    "build",
-    "watch",
-    "commit",
-    "commitlint",
-    "release",
-    "typescript-check",
-  ].includes(scriptName)
+	[
+		'test',
+		'commit',
+		'commitlint',
+		'release',
+		'semantic-release',
+		'typescript-check',
+		'wp-scripts',
+	].includes( scriptName )
 ) {
-  const result = spawn.sync(
-    process.execPath,
-    [require.resolve("../scripts/" + scriptName), ...nodeArgs],
-    { stdio: "inherit" }
-  );
-  if (result.signal) {
-    if (result.signal === "SIGKILL") {
-      utils.log(
-        "The build failed because the process exited too early. " +
-          "This probably means the system ran out of memory or someone called " +
-          "`kill -9` on the process."
-      );
-    } else if (result.signal === "SIGTERM") {
-      utils.log(
-        "The build failed because the process exited too early. " +
-          "Someone might have called `kill` or `killall`, or the system could " +
-          "be shutting down."
-      );
-    }
-    process.exit(1);
-  }
-  process.exit(result.status);
+	const result = spawn.sync(
+		process.execPath,
+		[ require.resolve( '../scripts/' + scriptName ), ...nodeArgs ],
+		{ stdio: 'inherit' }
+	);
+	if ( result.signal ) {
+		if ( result.signal === 'SIGKILL' ) {
+			utils.log(
+				'The build failed because the process exited too early. ' +
+          'This probably means the system ran out of memory or someone called ' +
+          '`kill -9` on the process.'
+			);
+		} else if ( result.signal === 'SIGTERM' ) {
+			utils.log(
+				'The build failed because the process exited too early. ' +
+          'Someone might have called `kill` or `killall`, or the system could ' +
+          'be shutting down.'
+			);
+		}
+		process.exit( 1 );
+	}
+	process.exit( result.status );
 } else {
-  utils.log(`Unknown script "${scriptName}".`);
+	utils.log( `Unknown script "${ scriptName }".` );
 }

package/config/babel.config.js

@@ -1,9 +1,8 @@
 module.exports = api => {
-  api.cache(true);
-  return {
-    presets: [
-      "@automattic/calypso-build/babel/default",
-      "@automattic/calypso-build/babel/wordpress-element"
-    ]
-  };
+	api.cache( true );
+	return {
+		presets: [
+			'@wordpress/babel-preset-default',
+		],
+	};
 };

package/config/commitlint.config.js

@@ -1 +1 @@
-module.exports = { extends: ["@commitlint/config-conventional"] };
+module.exports = { extends: [ '@commitlint/config-conventional' ] };

package/config/eslintrc.js

@@ -1,65 +1,77 @@
-// Assume `@wordpress/*` packages are available. This is because `calypso-build` is using
-// Dependency Extraction Webpack Plugin to use core WP packages instead of those from
-// node_modules. The packages should still be part of the project (they are listed in this
-// project's package.json) so that they are available in testing environment.
-// More on this:
-// - https://www.npmjs.com/package/@wordpress/dependency-extraction-webpack-plugin
-// - https://github.com/WordPress/gutenberg/issues/35630
-const GLOBALLY_AVAILABLE_PACKAGES = ["@wordpress/.*"];
+const wpRecommended = require.resolve( '@wordpress/eslint-plugin/configs/recommended' );
+const reactRecommended = require.resolve( '@wordpress/eslint-plugin/configs/react' );
+
+/**
+ *  Assume `@wordpress/*` packages are available. This is because `@wordpress/scripts` is using
+ * Dependency Extraction Webpack Plugin to use core WP packages instead of those from
+ * node_modules. The packages should still be part of the project (they are listed in this
+ * project's package.json) so that they are available in testing environment.
+ *
+ * More on this:
+ * - https: *www.npmjs.com/package/@wordpress/dependency-extraction-webpack-plugin
+ * - https: *github.com/WordPress/gutenberg/issues/35630
+ *
+ * React is also included here as it's a peer dependency of @wordpress/scripts.
+ */
+const GLOBALLY_AVAILABLE_PACKAGES = [ '@wordpress/.*', 'react' ];
 
 module.exports = {
-  extends: [
-    "plugin:@wordpress/eslint-plugin/recommended",
-    "plugin:react/recommended",
-    "plugin:import/errors",
-    "plugin:import/warnings",
-    "plugin:@typescript-eslint/eslint-recommended",
-    "plugin:@typescript-eslint/recommended",
-  ],
-  env: {
-    browser: true,
-    jest: true,
-  },
-  parser: "@typescript-eslint/parser",
-  plugins: ["@typescript-eslint"],
-  settings: {
-    "import/resolver": {
-      node: {
-        extensions: [".js", ".jsx", ".ts", ".tsx"],
-      },
-    },
-  },
-  ignorePatterns: ["dist/", "node_modules/"],
-  parser: "@typescript-eslint/parser",
-  rules: {
-    "no-console": "off",
-    camelcase: "off",
-    // Some dependencies are injected by WP, and should not be declared in package.json (won't be used anyway).
-    // See https://github.com/WordPress/gutenberg/blob/e035f71/packages/dependency-extraction-webpack-plugin/README.md#behavior-with-scripts
-    // Unfortunately there's no "ignore" option for this rule, so it's disabled altogether.
-    "import/no-extraneous-dependencies": "off",
-    "import/no-unresolved": ["error", { ignore: GLOBALLY_AVAILABLE_PACKAGES }],
-    // There's a conflict with prettier here:
-    "react/jsx-curly-spacing": "off",
-    // Skip prop types validation for now
-    "react/prop-types": "off",
-    "react/react-in-jsx-scope": "off",
-    "react/self-closing-comp": "error",
-    // JSDoc rules overrides
-    "jsdoc/require-returns": "off",
-    "jsdoc/require-param": "off",
-    // Deprecated rules
-    "jsx-a11y/no-onchange": "off",
-    // For TypeScript type declarations.
-    camelcase: "off",
-    "@typescript-eslint/no-empty-function": "off",
-    // Fail on unused vars.
-    "@typescript-eslint/no-unused-vars": "error",
-    // Disallow logging.
-    "no-console": "error",
-    // Handle the issue where no-shadow is a false positive when declaring TS enums.
-    // See https://github.com/typescript-eslint/typescript-eslint/issues/2483
-    "no-shadow": "off",
-    "@typescript-eslint/no-shadow": "error",
-  },
+	extends: [
+		'plugin:import/errors',
+		'plugin:import/warnings',
+		'plugin:@typescript-eslint/eslint-recommended',
+		'plugin:@typescript-eslint/recommended',
+		reactRecommended,
+		wpRecommended,
+	],
+	env: {
+		browser: true,
+		jest: true,
+	},
+	parser: '@typescript-eslint/parser',
+	plugins: [ '@typescript-eslint' ],
+	settings: {
+		'import/resolver': {
+			node: {
+				extensions: [ '.js', '.jsx', '.ts', '.tsx' ],
+			},
+		},
+	},
+	ignorePatterns: [ 'dist/', 'node_modules/', 'release/', 'scripts/', '/vendor' ],
+	rules: {
+		'arrow-parens': 'off',
+		camelcase: 'off',
+		// Disallow logging.
+		'no-console': 'error',
+		'no-mixed-operators': 'off',
+		'wrap-iife': 'off',
+		// Some dependencies are injected by WP, and should not be declared in package.json (won't be used anyway).
+		// See https://github.com/WordPress/gutenberg/blob/e035f71/packages/dependency-extraction-webpack-plugin/README.md#behavior-with-scripts
+		// Unfortunately there's no "ignore" option for this rule, so it's disabled altogether.
+		'import/no-extraneous-dependencies': 'off',
+		'import/no-unresolved': [ 'error', { ignore: GLOBALLY_AVAILABLE_PACKAGES } ],
+		'import/namespace': 'off',
+		// There's a conflict with prettier here:
+		'react/jsx-curly-spacing': 'off',
+		// Skip prop types validation for now
+		'react/prop-types': 'off',
+		'react/react-in-jsx-scope': 'off',
+		'react/self-closing-comp': 'error',
+		'react-hooks/exhaustive-deps': 'off',
+		// JSDoc rules overrides
+		'jsdoc/require-returns': 'off',
+		'jsdoc/require-param': 'off',
+		// Deprecated rules
+		'jsx-a11y/no-onchange': 'off',
+		'@typescript-eslint/no-empty-function': 'off',
+		// Fail on unused vars.
+		'@typescript-eslint/no-unused-vars': 'error',
+		// Handle the issue where no-shadow is a false positive when declaring TS enums.
+		// See https://github.com/typescript-eslint/typescript-eslint/issues/2483
+		'no-shadow': 'off',
+		'@typescript-eslint/no-shadow': 'error',
+		'@typescript-eslint/ban-ts-comment': 'warn',
+		'@typescript-eslint/no-explicit-any': 'warn',
+		'prettier/prettier': 'off', // We're mainly concerned about code quality rules, not formatting. npm run format:js can be used to reformat JS if desired.
+	},
 };

package/config/getWebpackConfig.js

@@ -1,27 +1,25 @@
-const path = require("path");
+const path = require( 'path' );
+require( '@wordpress/browserslist-config' );
+const defaultConfig = require( '@wordpress/scripts/config/webpack.config' );
 
-const getWebpackConfig = require("@automattic/calypso-build/webpack.config.js");
+module.exports = ( ...args ) => {
+	let config = { ...defaultConfig };
 
-module.exports = (...args) => {
-  const config = getWebpackConfig(...args);
+	// Merge config extensions into default config.
+	args.forEach( extension => {
+		config = { ...config, ...extension };
+	} );
 
-  const scssRuleIndex = config.module.rules.findIndex(rule =>
-    rule.test.toString().match(/\(sc\|sa\|c\)ss/)
-  );
-  if (scssRuleIndex !== -1) {
-    const scssRule = config.module.rules[scssRuleIndex];
-    const postCssLoaderIndex = scssRule.use.findIndex(
-      loader => loader.loader && loader.loader.indexOf("postcss") > 0
-    );
-    if (postCssLoaderIndex !== -1) {
-      const postCssLoader = scssRule.use[postCssLoaderIndex];
-      const postCssConfigPath = path.resolve(__dirname, "postcss.config.js");
-      // Replace calypso-build's PostCSS config with this project's one.
-      postCssLoader.options.postcssOptions.config = postCssConfigPath;
-      config.module.rules[scssRuleIndex].use[
-        postCssLoaderIndex
-      ] = postCssLoader;
-    }
-  }
-  return config;
+	// Ensure that webpack resolves modules from the Newspack Scripts node_modules as well as the root repo's node_modules.
+	config.resolve.modules = [
+		path.resolve( __dirname, '../node_modules' ),
+		'node_modules',
+	];
+
+	// Clear cacheGroups so that CSS files don't get the `style-` prefix.
+	if ( config?.optimization?.splitChunks?.cacheGroups?.style ) {
+		delete config.optimization.splitChunks.cacheGroups.style;
+	}
+
+	return config;
 };

package/config/postcss.config.js

@@ -1,6 +1,6 @@
-const postcssFocusWithin = require("postcss-focus-within");
-const autoprefixer = require("autoprefixer");
+const postcssFocusWithin = require( 'postcss-focus-within' );
+const autoprefixer = require( 'autoprefixer' );
 
 module.exports = {
-  plugins: [autoprefixer(), postcssFocusWithin()]
+	plugins: [ autoprefixer(), postcssFocusWithin() ],
 };

package/config/prettier.config.js

@@ -0,0 +1,6 @@
+const wpConfig = require( '@wordpress/prettier-config' );
+
+module.exports = {
+	...wpConfig,
+	arrowParens: 'avoid',
+};

package/config/stylelint.config.js

@@ -1,30 +1,34 @@
 module.exports = {
-  extends: ["stylelint-config-standard"],
-  rules: {
-    "rule-empty-line-before": null,
-    "at-rule-empty-line-before": null,
-    "comment-empty-line-before": null,
-    "no-descending-specificity": null,
-    "function-url-quotes": null,
-    "font-weight-notation": null,
-    "color-named": null,
-    "selector-class-pattern": null,
-    "custom-property-pattern": null,
-    "at-rule-no-unknown": null,
-    "alpha-value-notation": null,
-    "color-function-notation": null,
-    "selector-not-notation": null,
-    "function-no-unknown": [
-      true,
-      {
-        ignoreFunctions: ["/color/"],
-      },
-    ],
-    "annotation-no-unknown": [
-      true,
-      {
-        ignoreAnnotations: ["/default/"],
-      },
-    ],
-  },
+	extends: [
+		'@wordpress/stylelint-config',
+	],
+	rules: {
+		'rule-empty-line-before': null,
+		'at-rule-empty-line-before': null,
+		'comment-empty-line-before': null,
+		'no-descending-specificity': null,
+		'function-url-quotes': null,
+		'font-weight-notation': null,
+		'color-named': null,
+		'selector-class-pattern': null,
+		'custom-property-pattern': null,
+		'at-rule-no-unknown': null,
+		'alpha-value-notation': null,
+		'color-function-notation': null,
+		'selector-not-notation': null,
+		'function-no-unknown': [
+			true,
+			{
+				ignoreFunctions: [ '/color/' ],
+			},
+		],
+		'annotation-no-unknown': [
+			true,
+			{
+				ignoreAnnotations: [ '/default/' ],
+			},
+		],
+		'media-feature-range-notation': null,
+		'max-line-length': null,
+	},
 };

package/config/tsconfig.json

@@ -1,21 +1,25 @@
 {
-  "$schema": "https://json.schemastore.org/tsconfig",
-  "compilerOptions": {
-    "noEmit": true,
-    "composite": true,
-    "noEmitHelpers": true,
-    "skipLibCheck": true,
-    "lib": ["ESNext", "DOM", "DOM.Iterable"],
-    "target": "es6",
-    "module": "ESNext",
-    "esModuleInterop": true,
-    "jsx": "react-jsx",
-    "strict": true,
-    "isolatedModules": true,
-    "moduleResolution": "node",
-    "resolveJsonModule": true,
-    "forceConsistentCasingInFileNames": true,
-    "allowJs": true,
-    "checkJs": false
-  }
-}
+	"$schema": "https://json.schemastore.org/tsconfig",
+	"compilerOptions": {
+		"noEmit": true,
+		"composite": true,
+		"noEmitHelpers": true,
+		"skipLibCheck": true,
+		"lib": [
+			"ESNext",
+			"DOM",
+			"DOM.Iterable"
+		],
+		"target": "es6",
+		"module": "ESNext",
+		"esModuleInterop": true,
+		"jsx": "react-jsx",
+		"strict": true,
+		"isolatedModules": true,
+		"moduleResolution": "node",
+		"resolveJsonModule": true,
+		"forceConsistentCasingInFileNames": true,
+		"allowJs": true,
+		"checkJs": false
+	}
+}