authentik 前端代码规范基石深入解析goauthentik/prettier-config配置包【免费下载链接】authentikThe authentication glue you need.项目地址: https://gitcode.com/GitHub_Trending/au/authentikgoauthentik/prettier-config是 authentik 仓库中统一 Web 前端与各工具链包代码风格的 Prettier 共享配置包其 README 虽短背后却是一个包含格式化参数、导入排序插件、程序化格式化 API 与 CI 感知行为的完整工程化模块。本文以该包为绝对主体结合仓库内源码逐步拆解其配置结构、导入排序原理与实际接入方式帮助你理解 authentik 如何用一套配置同时驾驭 TypeScript、JSON 与 package.json 的格式一致性并掌握如何在自己的项目里复用它。包结构与定位在仓库中该包位于 packages/prettier-config通过 pnpm workspace 管理包名为goauthentik/prettier-config版本号可从 package.json 中确认当前为 4.0.2。它的定位正如 README.md 所写该包包含 authentik 使用的 Prettier 配置。README 同时给出了一个诚实的提示——虽然可以在外部项目中使用这份配置但由于其深度绑定 authentik 的工程约定例如针对goauthentik/*模块的导入重写规则你可能发现它不如其他流行配置那样通用好用。这是理解本包的关键前提它首先是 authentik 内部自用的工程基座其次才是可共享的 npm 包。从目录结构看包内包含以下核心文件index.js包入口默认导出AuthentikPrettierConfig并 re-export 常量与 formatterlib/constants.js完整 Prettier 配置对象定义lib/imports.js自定义导入排序插件imports-pluginlib/formatter.js程序化格式化工具函数eslint.config.mjs包自身使用的 ESLint 扁平配置tsconfig.json开启checkJs与emitDeclarationOnly为 JSDoc 类型标注的源码生成类型声明。package.json 通过exports字段暴露了三条子路径默认入口.指向index.js、./imports-plugin指向lib/imports.js和./formatter指向lib/formatter.js并声明了运行时要求node 24、pnpm 12.4.0使用pnpm12.4.0作为包管理器。prettier与prettier-plugin-packagejson作为 peerDependencies 出现说明使用方需要自行安装对应版本的 Prettier。快速接入如何在项目中启用在 authentik 仓库根目录的 package.json 中可以看到实际用法{ prettier: goauthentik/prettier-config }即在package.json中声明prettier字段指向该配置包这是 Prettier 官方支持的共享配置机制同时通过 workspace 依赖引用goauthentik/prettier-config: workspace:*并将prettier与prettier-plugin-packagejson加入依赖。对仓库外部项目而言接入方式为pnpm add -D prettier goauthentik/prettier-config prettier-plugin-packagejson然后在项目根目录的package.json中加入{ prettier: goauthentik/prettier-config }需要提醒的是如 README 所述这份配置包含 authentik 特有的导入重写逻辑详见下文外部项目直接使用会引入它预期的goauthentik/*导入约定因此更推荐将其作为参考蓝本按需裁剪后再复用。核心格式化参数一份少即是多的默认配置真正的配置主体定义在 lib/constants.js 的AuthentikPrettierConfig导出对象中。整体风格可概括为保持接近 Prettier 默认值、仅在少数关键点上收紧。完整参数如下配置项值说明arrowParensalways单参数箭头函数也保留括号如(x) xbracketSpacingtrue对象字面量花括号内侧保留空格如{ foo: 1 }embeddedLanguageFormattingauto自动格式化嵌入语言如模板字符串中的 CSS/HTMLhtmlWhitespaceSensitivitycssHTML 空白敏感度按 CSSdisplay语义处理insertPragma/requirePragmafalse不要求也不插入prettier标记注释全量格式化jsxSingleQuotefalseJSX 属性使用双引号printWidth100每行最大宽度 100 字符比 Prettier 默认的 80 更宽proseWrappreserveMarkdown 等散文文本保持原样换行quotePropsconsistent对象属性引号风格保持一致若任一属性需要引号则全部加引号semitrue语句末尾保留分号singleQuotefalse字符串统一使用双引号tabWidth4缩进宽度 4 空格这是与 Prettier 默认2差异最大的参数trailingCommaall多行结构末尾一律添加尾逗号useTabsfalse使用空格而非 TabvueIndentScriptAndStylefalseVue SFC 中script/style块不额外缩进plugins动态计算见下文插件体系overrides动态计算见下文覆盖规则值得注意的组合是tabWidth: 4与printWidth: 1004 空格缩进在 100 字符宽度下既能容纳较深的嵌套层级又保持行宽可控这构成了 authentik Web 代码web/src 下 900 余个 TS 文件统一的排版观感。覆盖规则overridesAuthentikPrettierConfig.overrides按文件类型做了三处特殊处理schemas/**/*.json将tabWidth强制为2。authentik 仓库中的 schema 文件如根目录 schema.yml 以及 JSON Schema 族文件采用 2 空格缩进避免与业务代码的 4 空格风格混淆tsconfig.json与*.jsonctrailingComma设为none。因为 JSON 标准不允许尾逗号tsconfig.json及带注释的 JSONC 文件必须遵守该约束package.json仅非 CI 环境启用prettier-plugin-packagejson并指定packageSortOrder对 JSON 字段按固定顺序排序见下文。插件体系CI 感知的动态加载lib/constants.js中插件数组是动态构建的const CI !!process.env.CI; const plugins [ fileURLToPath(import.meta.resolve(goauthentik/prettier-config/imports-plugin)), ]; if (!CI) { plugins.unshift(prettier-plugin-packagejson); // 并追加 package.json 的 overrides }imports-plugin始终加载这是 authentik 自定义的导入格式化插件下节详述在任何环境下都生效prettier-plugin-packagejson仅在非 CI 环境加载源码注释说明了原因——Sort order can be a source of false-positives in CI when this package is updated即当本配置包更新导致排序规则变化时CI 中会出现大量由排序产生的误报差异。因此在 CI 中禁用该插件只保留稳定的导入排序与格式化。非 CI 环境下package.json的packageSortOrder被指定为完整字段顺序name、version、description、license、private、author、authors、contributors、funding、repository、bugs、homepage、scripts、main、type、types、exports、imports、dependencies、devDependencies、peerDependencies、optionalDependencies、workspaces、files、wireit、resolutions、engines、devEngines、packageManager、prettier、eslintConfig。对照本包自己的 package.json 可以看到该排序的实际效果。自定义导入排序插件imports-plugin 的实现原理lib/imports.js 是这份配置最authentik 专属的部分。它通过包装 Prettier 内置的typescript与babel解析器在格式化前对 import 语句做preprocess实现三类能力1. 按分组规则重排 import核心依赖是format-imports库见 package.json 的 dependencies通过formatSourceFromFile.sync按groupRules对导入分组排序groupRules: [ ^node:, // Node 内置模块 ^[./], // 相对路径导入 ...webSubmodules.map((m) ^(goauthentik/|#)${m}.), // authentik Web 子模块 ^#., // # 别名导入 ^goauthentik., // 其余 goauthentik 包 {}, // 其他第三方包 ^(?)lit(.*)$, // lit 生态 \\.css$, // 样式文件 ^goauthentik/api$, // API 客户端 ],分组规则从下往上看{}表示其他导入兜底使得 Node 内置模块、相对路径、goauthentik子模块与第三方库被分隔成清晰的区块同时配置了nodeProtocol: alwaysNode 内置模块强制node:前缀、maxLineLength: printWidth行宽跟随配置和wrappingStyle: prettier。2. 遗留导入路径的自动迁移normalizeImports与normalizeExtensions两个函数用于处理 Web 前端的模块迁移。webSubmodules定义了common、elements、components、user、admin、flow六个子模块normalizeImports把旧式goauthentik/submodule/path导入重写为goauthentik/web/submodule/path并根据能否解析到对应模块决定是否追加/index若解析失败会打印警告并process.exit(1)将格式问题显式暴露为构建错误normalizeExtensions为所有不带扩展名的相对导入自动补上.js后缀满足浏览器原生 ES Module 对显式扩展名的要求。这两项仅在环境变量AK_FIX_LEGACY_IMPORTS true时启用避免在常规格式化中误改代码。3. 未使用导入的清理插件默认会删除未使用的 import通过keepUnused: []这是代码整洁度的重要保障。同时提供了逃生舱设置环境变量AK_KEEP_UNUSED_IMPORTS时keepUnused变为[.*]即保留全部未使用导入——这在需要临时保留引用、避免破坏副作用导入时很有用。此外preprocess还在文件头部以/**\n开头典型 JSDoc/许可头注释时在注释结束与首个 import 之间插入空行并支持在文件中写入ts-import-sorter: disable注释来整体跳过该文件的导入处理。关键环境变量速查环境变量生效值作用CI任意非空值禁用prettier-plugin-packagejson与 package.json 排序覆盖避免 CI 误报AK_FIX_LEGACY_IMPORTStrue启用遗留goauthentik/*导入路径迁移与扩展名补齐AK_KEEP_UNUSED_IMPORTS任意非空值保留所有未使用导入跳过删除逻辑程序化格式化 APIformatWithPrettier除了命令行工具该包还导出一个可在 Node 脚本中直接调用的格式化函数。lib/formatter.js 定义如下import { AuthentikPrettierConfig } from ./constants.js; import { format } from prettier; export function formatWithPrettier(fileContents) { return format(fileContents, { ...AuthentikPrettierConfig, parser: typescript, }); }它复用AuthentikPrettierConfig的全部选项并默认指定typescript解析器返回Promisestring。这意味着你可以把它集成进自定义代码生成器、迁移脚本或 lint 修复管线例如在生成 TypeScript 文件后直接调用formatWithPrettier(tsCode)获得规范化输出。从源码 JSDoc 标注可以确认parser目前固定为 TypeScript若要格式化其他语言需自行传参。包自身的工程质量最后值得一提的细节是这个配置包本身也是dogfooding自举的产物其 package.json 的 scripts 中包含prettier: prettier --write .与prettier-check: prettier --check .即用本配置格式化自己同时引入goauthentik/eslint-config做 ESLint 检查tsconfig.json 开启checkJs对 JSDoc 类型标注做静态校验。这种配置包自己吃自己的狗粮的做法保证了配置在真实工程中的可用性与可维护性。小结goauthentik/prettier-config表面上是十几行格式化参数实则是 authentik 前端工程规范的核心载体tabWidth: 4/printWidth: 100定义了代码外观imports-plugin通过format-imports统一了导入分组、路径迁移与未使用导入清理CI 感知的插件加载策略避免了持续集成中的排序误报而formatWithPrettier则为脚本化格式化提供了编程入口。无论是想理解 authentik 代码风格的由来还是希望为自己的项目设计一套配置 插件 工具函数的完整 Prettier 方案这份配置包都是一个结构清晰、值得研读的样本。【免费下载链接】authentikThe authentication glue you need.项目地址: https://gitcode.com/GitHub_Trending/au/authentik创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考