Feat/config types (#1624)

Author: rschristian

.changeset/big-walls-double.md

@@ -0,0 +1,5 @@
+---
+'preact-cli': patch
+---
+
+Added typings for users to use in their preact.config.js files

.eslintrc

@@ -40,5 +40,13 @@
     "react/jsx-no-undef": 2,
     "react/jsx-uses-react": 2,
     "react/jsx-uses-vars": 2
-  }
+  },
+  "overrides": [
+    {
+      "files": ["**/*.ts"],
+      "rules": {
+        "no-undef": "off"
+      }
+    }
+  ]
 }

README.md

@@ -219,39 +219,21 @@ To customize preact-cli create a `preact.config.js` or a `preact.config.json` fi
 ```js
 // ... imports or other code up here ...
 
-// these props are both optional
-export default {
-	// you can add preact-cli plugins here
-	plugins: [
-		// either a function
-		// (you'd probably import this because you can use the `webpack` function instead of an inline plugin)
-		function () {},
-		// strings also work (they get imported by preact-cli), useful for the json config
-		'plugin-name',
-		// with options
-		[
-			'plugin-name',
-			{
-				option: true,
-			},
-		],
-	],
-	/**
-	 * Function that mutates the original webpack config.
-	 * Supports asynchronous changes when a promise is returned (or it's an async function).
-	 *
-	 * @param {object} config - original webpack config.
-	 * @param {object} env - options passed to the CLI.
-	 * @param {WebpackConfigHelpers} helpers - object with useful helpers for working with the webpack config.
-	 * @param {object} options - this is mainly relevant for plugins (will always be empty in the config), default to an empty object
-	 **/
-	webpack(config, env, helpers, options) {
-		/** you can change the config here **/
-	},
+/**
+ * Function that mutates the original webpack config.
+ * Supports asynchronous changes when a promise is returned (or it's an async function).
+ *
+ * @param {import('preact-cli').Config} config - original webpack config
+ * @param {import('preact-cli').Env} env - current environment and options pass to the CLI
+ * @param {import('preact-cli').Helpers} helpers - object with useful helpers for working with the webpack config
+ * @param {Record<string, unknown>} options - this is mainly relevant for plugins (will always be empty in the config), default to an empty object
+ */
+export default (config, env, helpers, options) => {
+	/** you can change the config here **/
 };
 ```
 
-See [WebpackConfigHelpers] docs for more info on `helpers` argument which contains methods to find various parts of configuration. Additionally see our [recipes wiki] containing examples on how to change webpack configuration.
+See [Webpack config helpers wiki] for more info on the `helpers` argument which contains methods to find various parts of configuration. Additionally see our [recipes wiki] containing examples on how to change webpack configuration.
 
 #### Prerender multiple routes
 
@@ -397,6 +379,7 @@ Automatic code splitting is applied to all JavaScript and TypeScript files in th
 [plugins wiki]: https://github.com/preactjs/preact-cli/wiki/Plugins
 [preactjs-templates organization]: https://github.com/preactjs-templates
 [preactjs-templates/default]: https://github.com/preactjs-templates/default
+[webpack config helpers wiki]: https://github.com/preactjs/preact-cli/wiki/Webpack-Config-Helpers
 [recipes wiki]: https://github.com/preactjs/preact-cli/wiki/Config-Recipes
 [prpl]: https://developers.google.com/web/fundamentals/performance/prpl-pattern
 [`babel-preset-env`]: https://github.com/babel/babel-preset-env#targetsbrowsers

docs/webpack-helpers.md

@@ -139,6 +139,8 @@ module.exports = async function (env, webpackConfig, isServer = false) {
 /**
  * WebpackConfigHelpers
  *
+ * @typedef {import('../../../types.js').Helpers} Helpers
+ *
  * @class WebpackConfigHelpers
  */
 class WebpackConfigHelpers {
@@ -150,7 +152,8 @@ class WebpackConfigHelpers {
 	 * Webpack module used to create config.
 	 *
 	 * @readonly
-	 * @returns {object}
+	 * @type {Helpers['webpack']}
+	 *
 	 * @memberof WebpackConfigHelpers
 	 */
 	get webpack() {
@@ -160,8 +163,7 @@ class WebpackConfigHelpers {
 	/**
 	 * Returns wrapper around all loaders from config.
 	 *
-	 * @param {object} config - [webpack config](https://webpack.js.org/configuration/#options).
-	 * @returns {LoaderWrapper[]}
+	 * @type {Helpers['getLoaders']}
 	 *
 	 * @memberof WebpackConfigHelpers
 	 */
@@ -176,8 +178,7 @@ class WebpackConfigHelpers {
 	/**
 	 * Returns wrapper around all rules from config.
 	 *
-	 * @param {object} config - [webpack config](https://webpack.js.org/configuration/#options).
-	 * @returns {RuleWrapper[]}
+	 * @type {Helpers['getRules']}
 	 *
 	 * @memberof WebpackConfigHelpers
 	 */
@@ -191,8 +192,7 @@ class WebpackConfigHelpers {
 	/**
 	 * Returns wrapper around all plugins from config.
 	 *
-	 * @param {object} config - [webpack config](https://webpack.js.org/configuration/#options).
-	 * @returns {PluginWrapper[]}
+	 * @type {Helpers['getPlugins']}
 	 *
 	 * @memberof WebpackConfigHelpers
 	 */
@@ -201,11 +201,9 @@ class WebpackConfigHelpers {
 	}
 
 	/**
+	 * Returns wrapper around all rules that match provided file.
 	 *
-	 *
-	 * @param {object} config - [webpack config](https://webpack.js.org/configuration/#options).
-	 * @param {string} file - path to test against loader. Resolved relatively to $PWD.
-	 * @returns {RuleWrapper[]}
+	 * @type {Helpers['getRulesByMatchingFile']}
 	 *
 	 * @memberof WebpackConfigHelpers
 	 */
@@ -221,9 +219,8 @@ class WebpackConfigHelpers {
 	 *
 	 * @example
 	 * helpers.getLoadersByName(config, 'less-loader')
-	 * @param {object} config - [webpack config](https://webpack.js.org/configuration/#options).
-	 * @param {string} name - name of loader.
-	 * @returns {LoaderWrapper[]}
+	 *
+	 * @type {Helpers['getLoadersByName']}
 	 *
 	 * @memberof WebpackConfigHelpers
 	 */
@@ -252,9 +249,8 @@ class WebpackConfigHelpers {
 	 *
 	 * @example
 	 * helpers.getPluginsByName(config, 'HtmlWebpackPlugin')
-	 * @param {object} config - [webpack config](https://webpack.js.org/configuration/#options).
-	 * @param {string} name - name of loader.
-	 * @returns {PluginWrapper[]}
+	 *
+	 * @type {Helpers['getPluginsByName']}
 	 *
 	 * @memberof WebpackConfigHelpers
 	 */
@@ -270,39 +266,12 @@ class WebpackConfigHelpers {
 	 *
 	 * @example
 	 * helpers.getPluginsByType(config, webpack.optimize.CommonsChunkPlugin)
-	 * @param {object} config - [webpack config](https://webpack.js.org/configuration/#options).
-	 * @param {any} type - type of plugin.
-	 * @returns {PluginWrapper[]}
+	 *
+	 * @type {Helpers['getPluginsByType']}
 	 *
 	 * @memberof WebpackConfigHelpers
 	 */
 	getPluginsByType(config, type) {
 		return this.getPlugins(config).filter(w => w.plugin instanceof type);
 	}
 }
-
-/**
- * Wrapper around webpack's [loader entry](https://webpack.js.org/configuration/module/#useentry).
- *
- * @typedef {object} LoaderWrapper
- * @property {object} rule - [rule entry](https://webpack.js.org/configuration/module/#module-rules).
- * @property {number} ruleIndex - index of rule in config.
- * @property {object} loader - [loader entry](https://webpack.js.org/configuration/module/#useentry).
- * @property {number} loaderIndex - index of loader in rule.
- */
-
-/**
- * Wrapper around webpack's [rule](https://webpack.js.org/configuration/module/#module-rules).
- *
- * @typedef {object} RuleWrapper
- * @property {object} rule - [rule entry](https://webpack.js.org/configuration/module/#module-rules).
- * @property {number} index - index of rule in config.
- */
-
-/**
- * Wrapper around webpack's [plugin](https://webpack.js.org/configuration/plugins/#plugins).
- *
- * @typedef {object} PluginWrapper
- * @property {object} plugin - [plugin entry](https://webpack.js.org/configuration/plugins/#plugins).
- * @property {number} index - index of plugin in config.
- */

packages/cli/lib/lib/webpack/transform-config.js

@@ -7,6 +7,7 @@
   "bin": {
     "preact": "lib/index.js"
   },
+  "types": "types.d.ts",
   "scripts": {
     "pretest": "rimraf ./tests/output",
     "test": "jest"
@@ -80,6 +81,7 @@
     "@preact/async-loader": "^3.0.1",
     "@prefresh/babel-plugin": "^0.4.1",
     "@prefresh/webpack": "^3.2.2",
+    "@types/webpack": "^4.38.0",
     "autoprefixer": "^10.2.5",
     "babel-esm-plugin": "^0.9.0",
     "babel-loader": "^8.2.2",