@lipemat/js-boilerplate 10.6.0-beta.5 → 10.7.0

package/README.md

@@ -22,6 +22,7 @@ Add the following to your package.json. (this may also be found in the `template
 {
   "jsPath": "./js",
   "scripts": {
+    "analyze": "lipemat-js-boilerplate analyze",
     "browserslist": "lipemat-js-boilerplate browserslist",
     "dist": "lipemat-js-boilerplate dist",
     "lint": "lipemat-js-boilerplate lint",
@@ -44,7 +45,7 @@ Add the following to your package.json. (this may also be found in the `template
 * `cssTsFiles : {bool}` Enable auto generation of TypeScript definitions for CSS modules. 
 
 ## Code Completion In PHPStorm
-Some `@types` have been specified in this library to assist with code completion and allow using the built-in TypeScript support. Unfortunately, some typescripts still send errors to PHPStorm like "Default export is not declared in an imported module". I've found that it's easier to just remove this warning by un-checking `Editor -> Inspections -> JavaScript -> General -> Validate Imports`. (this may not need to be un-checked if you enable the built-in TypeScript support).
+Some `@types` have been specified in this library to help with code completion and allow using the built-in TypeScript support. Unfortunately, some typescripts still send errors to PHPStorm like "Default export is not declared in an imported module". I've found that it's easier to just remove this warning by un-checking `Editor -> Inspections -> JavaScript -> General -> Validate Imports`. (this may not need to be un-checked if you enable the built-in TypeScript support).
 
 
 ## ESLint
@@ -72,7 +73,7 @@ The console will display a list of browsers targeted by your [browserslist confi
 To use the built-in TypeScript, copy the following items from `templates` into your project root:
 1. `tsconfig.json`
 
-TypeScript will run a validator during dev and output any errors in the console. These same errors will display within PHPStorm if you copied tsconfig.json file in step 1. You technically don't have to fix any issues to compile but it's recommended. 
+TypeScript will run a validator during dev and output any errors in the console. These same errors will display within PHPStorm if you copied tsconfig.json file in step 1. You technically don't have to fix any issues to compile, but it's recommended. 
 
 Babel will automatically compile TypeScript files into the finished javascript, and will ignore errors. 
 
@@ -88,7 +89,7 @@ To create a package which extends any of the files within the `config` directory
 This is useful when you have often reused overrides to support a particular library. [Here is an example](https://github.com/lipemat/js-boilerplate-gutenberg)
 
 ### Testing
-To use the built in testing, copy the following items from `templates` into your project root:
+To use the built-in testing, copy the following items from `templates` into your project root:
 1. `jest.config.js`
 2. `tests`
 
@@ -103,11 +104,6 @@ Now you may write `jest` tests as desired and run them via `yarn run test`
 
 ## Legacy Browsers Support
 
-#### IE11
-
-By default, IE11 is disabled via an internal Browserslist configuration. If you would like to support IE11, add it 
-as a target to your project's Browserslist configuration and all tooling will automatically support it.
-
 #### ES6 Modules
 
 The app will automatically detect any packages in your `package.json` which do not support ES5 and add them to the list

package/bin/lipemat-js-boilerplate.js

@@ -17,12 +17,14 @@ const nodeArgs = scriptIndex > 0 ? args.slice( 0, scriptIndex ) : [];
 
 
 const TS_CONVERTED_SCRIPTS = [
+	'analyze',
 	'test',
 	'lint',
 	'validate-css-modules',
 ];
 
 switch ( script ) {
+	case 'analyze':
 	case 'browserslist':
 	case 'dist':
 	case 'fix-pnp':

package/config/{babel.config.js → babel.config.ts}

@@ -1,4 +1,17 @@
-const {getBrowsersList} = require( '../helpers/config' );
+import {getBrowsersList} from '../helpers/config';
+import type {TransformOptions} from '@babel/core';
+import type {Options} from '@babel/preset-env';
+
+/**
+ * @link https://webpack.js.org/loaders/babel-loader/#options
+ */
+export type BabelLoader = {
+	cacheDirectory?: boolean | string;
+	cacheIdentifier?: string;
+	cacheCompression?: boolean;
+	customize?: string;
+	metadataSubscribers?: string[];
+}
 
 /**
  * Use Babel's preset-env to add support for target browsers.
@@ -7,11 +20,12 @@ const {getBrowsersList} = require( '../helpers/config' );
  *
  * @see https://babeljs.io/docs/en/babel-preset-env
  */
-const presetEnv = {
+const presetEnv: Options = {
 	bugfixes: true,
 	corejs: {
 		// Use the core-js version currently installed in the project.
 		version: require( 'core-js/package.json' ).version,
+		proposals: false,
 	},
 	// Enable the `debug` option to debug the included polyfills and plugins.
 	debug: false,
@@ -25,7 +39,7 @@ const presetEnv = {
 };
 
 
-module.exports = {
+const babelConfig: TransformOptions & BabelLoader = {
 	cacheDirectory: true,
 	presets: [
 		[ '@babel/preset-env', presetEnv ],
@@ -39,3 +53,5 @@ module.exports = {
 		'@babel/plugin-syntax-dynamic-import',
 	],
 };
+
+module.exports = babelConfig;

package/config/webpack.dev.js

@@ -6,10 +6,10 @@ const {getPackageConfig} = require( '../helpers/package-config' );
 const {getEntries} = require( '../helpers/entries' );
 const {getConfig, getTsConfigFile, getBrowsersList} = require( '../helpers/config' );
 
-const postcssOptions = getConfig( 'postcss.config.js' );
-const babelOptions = getConfig( 'babel.config.js' );
-const cssLoaderOptions = getConfig( 'css-loader.config.js' );
-const devServerOptions = getConfig( 'dev-server.config.js' );
+const postcssOptions = getConfig( 'postcss.config' );
+const babelOptions = getConfig( 'babel.config' );
+const cssLoaderOptions = getConfig( 'css-loader.config' );
+const devServerOptions = getConfig( 'dev-server.config' );
 
 // To allow line numbers to show up in console errors. @see React Error Boundaries.
 babelOptions.plugins.unshift( '@babel/plugin-transform-react-jsx-source' );

package/config/webpack.dist.js

@@ -14,9 +14,9 @@ const config = require( '../helpers/package-config' );
 const {getEntries} = require( '../helpers/entries' );
 const {getPackageConfig} = require( '../helpers/package-config' );
 
-const postcssOptions = getConfig( 'postcss.config.js' );
-const babelOptions = getConfig( 'babel.config.js' );
-const cssLoaderOptions = getConfig( 'css-loader.config.js' );
+const postcssOptions = getConfig( 'postcss.config' );
+const babelOptions = getConfig( 'babel.config' );
+const cssLoaderOptions = getConfig( 'css-loader.config' );
 
 const ManifestPlugin = new WebpackAssetsManifest( {
 	integrity: true,

package/helpers/config.d.ts

@@ -0,0 +1,7 @@
+/**
+ * @todo convert the source to TS.
+ */
+
+export function getBrowsersList(): readonly string[];
+
+export function getConfig<T extends object>( fileName: string ): T;

package/helpers/config.js

@@ -171,6 +171,8 @@ const getDefaultBrowsersList = () => {
 
 /**
  * Adjust the browserslist to include our defaults.
+ *
+ * @todo Remove `not op_mini all` after 3/8/2024 if it does not creep back in to the defaults.
  */
 function adjustBrowserslist( browserRules ) {
 	browserRules.push( 'not op_mini all' );

package/helpers/entries.js

@@ -3,7 +3,7 @@ const fs = require( 'fs' );
 const path = require( 'path' );
 const {getConfig} = require( './config' );
 
-const entries = getConfig( 'entries.config.js' );
+const entries = getConfig( 'entries.config' );
 
 
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lipemat/js-boilerplate",
-  "version": "10.6.0-beta.5",
+  "version": "10.7.0",
   "description": "Dependencies and scripts for a no config JavaScript app",
   "author": "Mat Lipe",
   "license": "MIT",
@@ -48,13 +48,16 @@
     "@lipemat/css-mqpacker": "^9.0.0",
     "@lipemat/eslint-config": "^3.1.3",
     "@pmmmwh/react-refresh-webpack-plugin": "^0.5.10",
+    "@statoscope/webpack-plugin": "^5.28.2",
     "@teamsupercell/typings-for-css-modules-loader": "^2.5.2",
+    "@types/babel__preset-env": "^7.9.6",
     "@types/node": "^16",
     "@wordpress/browserslist-config": "^5.19.0",
     "are-you-es5": "^2.1.1",
     "babel-jest": "^29.0.0",
     "babel-loader": "9.1.2",
     "browserslist": "^4.21.9",
+    "chalk": "^4.0",
     "clean-css": "^5.3.0",
     "clean-webpack-plugin": "^4.0.0",
     "compression-webpack-plugin": "^10.0.0",

package/scripts/analyze.ts

@@ -0,0 +1,53 @@
+import {getConfig} from '../helpers/config';
+import webpack from 'webpack';
+import StatoscopeWebpackPlugin from '@statoscope/webpack-plugin';
+import fs from 'fs';
+import minimist from 'minimist';
+
+const help = `
+Uses Statoscope to visualize the size of the project's output files.
+
+Usage: lipemat-js-boilerplate analyze [--stats-only|--help]
+
+  --help, -h Show help menu.
+  --stats-only Generate stats.json file for use with https://statoscope.tech for comparing diffs between builds.
+	
+`;
+
+
+// Command line arguments.
+const flags = minimist( process.argv.slice( 2 ) );
+const workingDirectory = fs.realpathSync( process.cwd() );
+const statsDir = workingDirectory + '/node_modules/.cache/statoscope';
+const webpackConfig = getConfig<webpack.Configuration>( 'webpack.dist' );
+
+if ( true === flags.h || true === flags.help ) {
+	console.log( help );
+	process.exit( 0 );
+}
+
+
+function analyze() {
+	webpackConfig.plugins?.push( new StatoscopeWebpackPlugin( {
+		saveOnlyStats: true === ( flags[ 'stats-only' ] ?? false ),
+		saveStatsTo: statsDir + '/stats-[hash].json',
+		saveReportTo: statsDir + '/stats-[hash].html',
+	} ) );
+
+	// Use the default webpack stats configuration.
+	delete webpackConfig.stats;
+
+	webpack( webpackConfig ).run( ( err, stats ) => {
+		if ( err ) {
+			throw err;
+		}
+		if ( 'undefined' === typeof stats ) {
+			return;
+		}
+		if ( stats.hasErrors() ) {
+			process.exit( 1 );
+		}
+	} );
+}
+
+analyze();

package/scripts/dist.js

@@ -2,7 +2,7 @@ process.env.BABEL_ENV = 'production';
 process.env.NODE_ENV = 'production';
 
 const webpack = require( 'webpack' );
-const webpackConfig = require( '../helpers/config' ).getConfig( 'webpack.dist.js' );
+const webpackConfig = require( '../helpers/config' ).getConfig( 'webpack.dist' );
 
 async function build( config ) {
 	// Compiler Instance.

package/scripts/lint.ts

@@ -1,5 +1,6 @@
 import {ESLint} from 'eslint';
 import minimist from 'minimist';
+import chalk from 'chalk';
 
 import packageConfig from '../helpers/package-config';
 
@@ -30,6 +31,8 @@ function errorOccurred( results: ESLint.LintResult[] ): boolean {
 		cacheStrategy: 'content',
 	} );
 
+	console.log( chalk.underline( 'Running "js-boilerplate:lint" (eslint) task' ) );
+
 	// 2. Lint files. This doesn't modify target files.
 	const results: ESLint.LintResult[] = await eslint.lintFiles( [
 		packageConfig.workingDirectory + '/src/**/*.{js,jsx,ts,tsx}',
@@ -43,13 +46,15 @@ function errorOccurred( results: ESLint.LintResult[] ): boolean {
 	const resultText = formatter.format( results );
 
 	// 5. Output it.
-	console.log( resultText );
 	if ( '' === resultText ) {
-		console.log( '>> Linted JS files without errors.' );
-		console.log( '-----------------------------------' );
-	} else if ( errorOccurred( results ) ) {
-		process.exitCode = 1;
+		console.log( `>> Linted ${results.length} files without errors` );
+	} else {
+		console.log( resultText );
+		if ( errorOccurred( results ) ) {
+			process.exitCode = 1;
+		}
 	}
+	console.log( '' );
 }() ).catch( error => {
 	process.exitCode = 1;
 	console.error( error );

package/scripts/start.js

@@ -7,8 +7,8 @@ const {unlinkSync, writeFile} = require( 'fs' );
 const WebpackDevServer = require( 'webpack-dev-server' );
 const configHelper = require( '../helpers/config' );
 const path = require( 'path' );
-const webpackConfig = configHelper.getConfig( 'webpack.dev.js' );
-const devServerConfig = configHelper.getConfig( 'dev-server.config.js' );
+const webpackConfig = configHelper.getConfig( 'webpack.dev' );
+const devServerConfig = configHelper.getConfig( 'dev-server.config' );
 
 const server = new WebpackDevServer( devServerConfig, webpack( webpackConfig ) );
 

package/scripts/validate-css-modules.ts

@@ -14,7 +14,7 @@ Validate CSS modules using .d.ts definition files for each CSS module.
 
 Usage: lipemat-js-boilerplate validate-css-modules
 
---help, -h  Show help menu.`;
+--help, -h Show help menu.`;
 
 const args = process.argv.slice( 3 );
 if ( '-h' === args[ 0 ] || '--help' === args[ 0 ] ) {
@@ -23,7 +23,7 @@ if ( '-h' === args[ 0 ] || '--help' === args[ 0 ] ) {
 }
 
 async function validate() {
-	let webpackConfig: webpack.Configuration = getConfig( 'webpack.dist.js' );
+	let webpackConfig = getConfig<webpack.Configuration>( 'webpack.dist' );
 	webpackConfig.stats = 'errors-warnings';
 
 	// Add CSS module typings generation to webpack config.