给你的配置文件加上代码提示 - 2022-06-23

~~卧槽，scss-loader 的参数是啥来着？又特么得去翻webpack文档~~

还记得当年在 webpack.config.js 和 webpack.js.org 来回切的场景吗？好不容易配置完webpack，babel.config.js、postcss.config.js ... xxx.config.js 在等着你。

现如今我们基本都有封装自己的脚手架，再也不用面向配置编程了，虽说配置是减少了很多，但也还是有一些，我们也不希望同事一手配置文件一手配置文档来回切，那就给你的配置文件加上代码提示吧！

首先，你得给你的配置加上类型定义，有了类型定义，现在主流编辑器都能提供代码提示。具体可参考 https://www.typescriptlang.org/docs/handbook/declaration-files/templates/module-d-ts.html

如果你得包是用typescripts写的，那么编译的时候应该是可以导出d.ts文件的。

如果是用js写的，我们就可以自己去编写d.ts文件，比如我们的包叫做 @mi/miot-react-scripts，我们可以写一个types.d.ts文件，大致内容如下：

export default interface Config {
  template?: string
  outputDir?: string
  entry?: {
    base?: string,
    pages?: string[],
    pattern?: string
  }
}

现在我们需要把我们的配置文件和这个类型关联起来，大致有两种方式：

jsdoc注释

通过 jsdoc 注释，我们可以给 js 加上编辑器的类型提示，现在主流编辑器应该都是支持的，那我们就可以在我们的配置文件上加上这样的注释：

/**
* @type {import("@mi/miot-react-scripts/types")}
*/
const config = {
}
module.exports = config

我们还可以在我们包的package.json 上加上types配置：

{
  "types": "types.d.ts"
}

这样，我们的类型注释就可以不用指定到类型文件：

/**
* @type {import("@mi/miot-react-scripts")}
*/
const config = {
}
module.exports = config

这时候，我们在config中就支持代码提示了，再也不用去翻配置文档了。

当然，如果你不喜欢这种注释的方式，那我们还可以在包里面导出一个辅助函数来帮你加上类型提示。

辅助函数

本质上辅助函数啥都没做，你传入什么，就给返回什么，只不过在参数上加上了类型注释，直接上代码：

/**
 *
 * @param {import("./types")} config
 * @returns
 */
function defineConfig(config) {
  return config
}


module.exports = {
  defineConfig,
}

假设我们package.json中的main字段指向以上文件（实际上任意位置都可以，只要和引入路径匹配），现在我们在写配置文件的时候，就可以这么写了：

const { defineConfig } = require("@mi/miot-react-scripts");
module.exports = defineConfig({

})

这样，我们的配置文件也就支持了代码提示了。

鼠标悬停到具体字段上，也有提示：

到这里基本就ok了，有两个细节再补充一下：

1. 辅助方法的名称？

你爱叫啥叫啥，当然推荐 defineConfig , rollup、vite 都是这么叫的，这样大家在用各种框架时，一眼就能看出来是干嘛的（没错，我就是从他们那儿抄过来的）。

2. 如果你的package.json 中指定了 types 字段，而你又想直接从包名导入 defineConfig, 而不是指向index.js 文件，那么你就需要在 types.d.ts 中导出 defineConfig 的类型：

interface Config {

}

declare function defineConfig(config: Config): Config

export { defineConfig, Config }

这样，你既可以用 jsdoc 注释， 也可以用 defineConfig 辅助函数了。

到这里就真的结束了，赶紧去给你的配置文件加上类型提示吧，你的同事再也不会在背后偷偷骂你了，说不定还会请你和奶茶 [:doge] ⁣⁣