nuxt-imc 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 hzgotb
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,152 @@
+# nuxt-imc
+
+`nuxt-imc` 是一个 Nuxt module，用来把“目录式组件库”里的具名导出批量注册成 Nuxt 组件和 auto-import composable。
+
+它适合这样的场景：
+
+- 组件库不是一堆散落的 `.vue` 文件，而是按目录组织，每个组件目录通过 `index.ts` 或 `index.js` 统一导出。
+- 希望给一组组件统一加前缀，例如 `new`。
+- 希望组件和 `cps*` 风格的 composable 通过同一个入口暴露。
+
+## 安装
+
+```bash
+pnpm add nuxt-imc
+```
+
+## 如何使用
+
+在 `nuxt.config.ts` 的 `modules` 里启用，并提供 `imc` 配置：
+
+```ts
+export default defineNuxtConfig({
+  modules: [
+    'nuxt-imc'
+  ],
+
+  imc: {
+    libraries: [
+      { composablePrefix: 'cps', directory: 'app/components/ui', prefix: 'new' },
+      { directory: 'app/components/atom', ignore: true }
+    ]
+  }
+})
+```
+
+`libraries` 每一项的含义：
+
+- `composablePrefix`: 用来识别 composable 导出名的前缀，默认是 `cps`。
+- `directory`: 组件库根目录，路径相对于 Nuxt root。
+- `ignore`: 为 `true` 时，这一项会作为独立忽略规则；该目录不会参与 Nuxt 组件扫描，也不会作为 IMC library 解析。
+- `prefix`: 注册到模板中的组件名前缀，必须是 `kebab-case`。模块会先把它转成 PascalCase，再和组件导出名拼成最终组件名。
+
+## 推荐目录结构
+
+当前实现按“一级子目录 + index 导出”的约定工作。`library` 根目录下的每个一级子项都应该是目录，并且目录里要有 `index.ts` 或 `index.js`。
+
+```txt
+app/components/ui/
+  new-slideover/
+    index.ts
+    slideover.ts
+    cps-slideover.ts
+  new-scrollbar/
+    index.ts
+    scrollbar.ts
+```
+
+`index.ts` 示例：
+
+```ts
+export { cpsSlideover } from './cps-slideover'
+export { Slideover } from './slideover'
+```
+
+接入后：
+
+- `Slideover` 会被注册为 `NewSlideover`
+- `cpsSlideover` 会被注册为 auto import，可在 `script setup` 里直接调用
+
+```vue
+<script setup lang="ts">
+const slideover = cpsSlideover()
+</script>
+
+<template>
+  <NewSlideover />
+</template>
+```
+
+## 识别规则
+
+`nuxt-imc` 只解析 `index.ts` 或 `index.js` 的具名导出：
+
+- 导出名以大写字母开头：按组件处理，调用 `addComponent`
+- 导出名以当前 library 的 `composablePrefix` 开头：按 auto-import 处理，默认前缀是 `cps`
+- 其它导出名：忽略
+- `default export`: 不会被处理
+
+## 原理
+
+`nuxt-imc` 的工作流程分成两步。
+
+### 1. 解析 library 目录
+
+模块会先把每个配置项解析成绝对路径，然后读取它下面的一级子目录，作为后续要处理的组件目录列表。
+
+如果某个 `directory` 不存在、不是目录，或者当前进程没有读取权限，它会输出一条 `warn` 并跳过，而不是直接抛错中断整个模块初始化。
+
+### 2. 关闭默认扫描，改为按导出注册
+
+模块会在 `components:dirs` hook 里把 library 目录和 `ignore: true` 目录插入到 Nuxt 的组件目录列表前面，但故意把 `extensions` 设成 `['.xx']`。这样 Nuxt 不会去按默认规则扫描这些目录里的真实组件文件。
+
+接着模块会自己完成注册流程：
+
+1. 解析每个 `library` 根目录
+2. 读取根目录下的一级子目录
+3. 跳过根目录下的普通文件
+4. 读取每个子目录里的 `index.ts` 或 `index.js`
+5. 用 `oxc-parser` 解析 AST，而不是用正则匹配源码文本
+6. 遍历具名导出
+7. 根据导出名决定调用 `addComponent` 还是 `addImports`
+
+这样做的结果是：
+
+- 对外暴露什么组件、什么 composable，完全由 `index.ts/js` 决定
+- 可以在一个组件目录里同时维护组件和它的配套 composable
+- 可以通过 `prefix` 统一加命名空间，减少冲突
+
+## 当前实现的限制
+
+使用时要特别注意下面几个约束：
+
+- `library` 根目录下的普通文件会被忽略，不会参与注册。
+- 配置了 `ignore: true` 的目录会被忽略，不会参与 Nuxt 组件扫描或 IMC 注册。
+- 只扫描一级子目录，不会递归扫描更深层级。
+- 每个组件目录都必须有 `index.ts` 或 `index.js`；空目录或缺少入口文件的目录仍然会报错。
+- 只识别具名导出，不识别 `default export`。
+- `prefix` 必须是 `kebab-case`；不合法的值会直接抛错。
+- 无效的 `directory` 会发出 `warn` 并跳过，不会中断模块初始化。
+
+## 本地开发
+
+```bash
+pnpm install
+pnpm dev:prepare
+pnpm dev
+```
+
+常用检查：
+
+```bash
+pnpm lint
+pnpm test
+pnpm test:types
+pnpm prepack
+```
+
+`playground/` 用于交互开发，`test/fixtures/basic/` 用于真实 Nuxt SSR 集成测试。
+
+## License
+
+[MIT](./LICENSE)

package/dist/module.d.mts

@@ -0,0 +1,22 @@
+import * as _nuxt_schema from '@nuxt/schema';
+
+interface ComponentLibrary {
+    composablePrefix?: string;
+    prefix?: string;
+    /** base nuxt root */
+    directory: string;
+}
+interface IgnoredComponentLibraryDirectory {
+    /** base nuxt root */
+    directory: string;
+    ignore: boolean;
+}
+type ComponentLibraryConfig = ComponentLibrary | IgnoredComponentLibraryDirectory;
+interface ModuleOptions {
+    libraries: ComponentLibraryConfig[];
+}
+
+declare const _default: _nuxt_schema.NuxtModule<ModuleOptions, ModuleOptions, false>;
+
+export { _default as default };
+export type { ComponentLibrary, ComponentLibraryConfig, IgnoredComponentLibraryDirectory, ModuleOptions };

package/dist/module.json

@@ -0,0 +1,12 @@
+{
+  "name": "nuxt-imc",
+  "configKey": "imc",
+  "compatibility": {
+    "nuxt": ">=3.0.0"
+  },
+  "version": "0.1.0",
+  "builder": {
+    "@nuxt/module-builder": "1.0.3",
+    "unbuild": "unknown"
+  }
+}

package/dist/module.mjs

@@ -0,0 +1,124 @@
+import { addComponent, addImports, defineNuxtModule, createResolver } from '@nuxt/kit';
+import { readdir, readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { parseSync } from 'oxc-parser';
+
+const COMPONENT_EXPORT_NAME_RE = /^[A-Z]/;
+const KEBAB_CASE_PREFIX_RE = /^[a-z]+(?:-[a-z0-9]+)*$/;
+function toPascalCasePrefix(prefix) {
+  return prefix.split("-").map((part) => `${part[0]?.toUpperCase() || ""}${part.slice(1)}`).join("");
+}
+function validateComponentPrefix(prefix) {
+  if (!prefix || KEBAB_CASE_PREFIX_RE.test(prefix)) {
+    return;
+  }
+  throw new Error(`[imc] Component prefix "${prefix}" must be kebab-case`);
+}
+function isIgnoredComponentLibraryDirectory(lib) {
+  return "ignore" in lib && lib.ignore;
+}
+function isComponentLibrary(lib) {
+  return !isIgnoredComponentLibraryDirectory(lib);
+}
+function getModuleExportName(exported) {
+  return exported.type === "Literal" ? exported.value : exported.name;
+}
+function obtainLibDirs(resolve, warn = (message) => console.warn(message)) {
+  return async (libConfigs) => {
+    const ignoredDirs = new Set(
+      libConfigs.filter(isIgnoredComponentLibraryDirectory).map((lib) => resolve(lib.directory))
+    );
+    const resolvedDirs = await Promise.all(libConfigs.filter(isComponentLibrary).map(async (lib) => {
+      validateComponentPrefix(lib.prefix || "");
+      const libDir = resolve(lib.directory);
+      try {
+        const entries = await readdir(libDir, { withFileTypes: true });
+        return {
+          componentDirs: entries.filter((entry) => entry.isDirectory()).filter((entry) => !ignoredDirs.has(resolve(lib.directory, entry.name))).map((entry) => entry.name).sort(),
+          composablePrefix: lib.composablePrefix || "cps",
+          fullPath: libDir,
+          prefix: lib.prefix || ""
+        };
+      } catch {
+        warn(`[imc] Ignoring invalid library directory "${lib.directory}"`);
+        return null;
+      }
+    }));
+    return resolvedDirs.filter((dir) => dir !== null);
+  };
+}
+function obtainIgnoredDirs(resolve) {
+  return (libConfigs) => {
+    return libConfigs.filter(isIgnoredComponentLibraryDirectory).map((lib) => resolve(lib.directory));
+  };
+}
+function appendComponents(resolve, resolvePath) {
+  return async (libDir, compDir, prefix, composablePrefix = "cps") => {
+    const indexFilePath = await resolvePath(join(libDir, compDir, "index"), { extensions: [".ts", ".js"] });
+    const content = await readFile(indexFilePath, { encoding: "utf8" });
+    const ast = parseSync(indexFilePath, content, { sourceType: "module" });
+    const componentPrefix = prefix ? toPascalCasePrefix(prefix) : "";
+    ast.program.body.filter((node) => node.type === "ExportNamedDeclaration").filter((node) => node.exportKind !== "type").flatMap((node) => node.specifiers.filter((specifier) => specifier.exportKind !== "type").map((specifier) => getModuleExportName(specifier.exported))).forEach((key) => {
+      if (COMPONENT_EXPORT_NAME_RE.test(key)) {
+        addComponent({
+          name: `${componentPrefix}${key}`,
+          export: key,
+          filePath: resolve(indexFilePath),
+          priority: 1
+        });
+      } else if (key.startsWith(composablePrefix)) {
+        addImports({
+          name: key,
+          from: resolve(indexFilePath),
+          priority: 1
+        });
+      }
+    });
+  };
+}
+
+const module$1 = defineNuxtModule({
+  meta: {
+    name: "nuxt-imc",
+    configKey: "imc",
+    compatibility: {
+      nuxt: ">=3.0.0"
+    }
+  },
+  defaults: {
+    libraries: []
+  },
+  async setup(moduleOptions, nuxt) {
+    const { resolve, resolvePath } = createResolver(nuxt.options.rootDir);
+    if (moduleOptions.libraries.length === 0) {
+      return;
+    }
+    const libDirs = await obtainLibDirs(resolve)(moduleOptions.libraries);
+    const ignoredDirs = obtainIgnoredDirs(resolve)(moduleOptions.libraries);
+    nuxt.hook("components:dirs", (dirs) => {
+      dirs.unshift(
+        ...ignoredDirs.map((path) => ({
+          path,
+          extensions: [".xx"],
+          priority: 1
+        })),
+        ...libDirs.map((dir) => ({
+          path: dir.fullPath,
+          extensions: [".xx"],
+          priority: 1
+        }))
+      );
+    });
+    const appendLibraryComponents = appendComponents(resolve, resolvePath);
+    await Promise.all(libDirs.flatMap(
+      (libDir) => libDir.componentDirs.map((compDir) => appendLibraryComponents(
+        libDir.fullPath,
+        compDir,
+        libDir.prefix,
+        libDir.composablePrefix
+      ))
+    ));
+  }
+});
+
+export { module$1 as default };

package/dist/types.d.mts

@@ -0,0 +1,3 @@
+export { default } from './module.mjs'
+
+export { type ComponentLibrary, type ComponentLibraryConfig, type IgnoredComponentLibraryDirectory, type ModuleOptions } from './module.mjs'

package/package.json

@@ -0,0 +1,76 @@
+{
+  "name": "nuxt-imc",
+  "version": "0.1.0",
+  "description": "Register named component-library exports as Nuxt components and auto-imported composables.",
+  "repository": {
+    "type": "git",
+    "url": "github:hzgotb/nuxt-imc"
+  },
+  "homepage": "https://github.com/hzgotb/nuxt-imc#readme",
+  "bugs": "https://github.com/hzgotb/nuxt-imc/issues",
+  "license": "MIT",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/types.d.mts",
+      "import": "./dist/module.mjs"
+    },
+    "./types": {
+      "types": "./dist/types.d.mts",
+      "import": "./dist/module.mjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "main": "./dist/module.mjs",
+  "types": "./dist/types.d.mts",
+  "typesVersions": {
+    "*": {
+      ".": [
+        "./dist/types.d.mts"
+      ],
+      "types": [
+        "./dist/types.d.mts"
+      ]
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "sideEffects": false,
+  "workspaces": [
+    "playground"
+  ],
+  "dependencies": {
+    "@nuxt/kit": "^4.5.0",
+    "oxc-parser": "^0.141.0"
+  },
+  "devDependencies": {
+    "@nuxt/devtools": "^3.2.4",
+    "@nuxt/eslint-config": "^1.16.0",
+    "@nuxt/module-builder": "^1.0.3",
+    "@nuxt/schema": "^4.5.0",
+    "@nuxt/test-utils": "^4.0.3",
+    "@types/node": "^24.0.0",
+    "changelogen": "^0.6.2",
+    "eslint": "^10.7.0",
+    "nuxt": "^4.5.0",
+    "typescript": "~5.9.3",
+    "vitest": "^4.1.10",
+    "vue-tsc": "^3.3.7"
+  },
+  "engines": {
+    "node": ">=20.19.0"
+  },
+  "scripts": {
+    "dev": "pnpm dev:prepare && nuxt dev playground",
+    "dev:build": "nuxt build playground",
+    "dev:prepare": "nuxt-module-build build --stub && nuxt-module-build prepare && nuxt prepare playground",
+    "lint": "eslint .",
+    "test": "vitest run",
+    "test:peers": "pnpm peers check",
+    "test:unit": "vitest run test/helper.test.ts",
+    "test:watch": "vitest watch",
+    "test:types": "vue-tsc --noEmit && pnpm --dir playground exec vue-tsc --noEmit",
+    "release": "pnpm lint && pnpm test && pnpm test:types && pnpm prepack && changelogen --release && pnpm publish && git push --follow-tags"
+  }
+}