在NextJS中引入自托管StencilJS组件库遇模块找不到错误

1. 先确认Stencil组件库的打包配置 #

打开组件库根目录的stencil.config.ts，检查outputTargets配置是否包含正确的输出格式，确保loader文件能正常生成：

export const config: Config = {
  namespace: 'shared-components',
  outputTargets: [
    {
      type: 'dist',
      esmLoaderPath: '../loader', // 确保loader输出路径正确
    },
    {
      type: 'dist-custom-elements',
    },
  ],
};

修改后重新打包组件库，推送到私有GitLab仓库，再在NextJS项目中重新执行npm install或yarn add更新依赖。

2. 调整NextJS中的导入与注册逻辑 #

Stencil自定义元素需要在客户端环境注册，避免SSR阶段加载出错，建议在_app.tsx中使用动态导入+useEffect：

import { useEffect } from 'react';
import type { AppProps } from 'next/app';

export default function MyApp({ Component, pageProps }: AppProps) {
  useEffect(() => {
    // 动态导入loader，确保仅在客户端执行
    import('@mypackage/shared-components/loader').then((module) => {
      module.defineCustomElements(window);
    });
  }, []);

  return <Component {...pageProps} />;
}

3. 配置NextJS转译组件库 #

NextJS默认不会转译node_modules中的第三方包，需在next.config.js中添加transpilePackages配置：

/** @type {import('next').NextConfig} */
const nextConfig = {
  transpilePackages: ['@mypackage/shared-components'],
};

module.exports = nextConfig;

4. 检查组件库package.json的模块解析配置 #

确认组件库的package.json中exports字段配置正确，让NextJS能正确识别loader的CJS/ESM入口：

"exports": {
  ".": {
    "import": "./dist/index.js",
    "require": "./dist/index.cjs"
  },
  "./loader": {
    "import": "./loader/index.js",
    "require": "./loader/index.cjs"
  }
}

5. 验证node_modules中的文件结构 #

手动查看node_modules/@mypackage/shared-components/loader目录，确认实际存在的文件名。如果没有index.cjs，直接导入存在的文件（比如index.js）即可：

import { defineCustomElements } from '@mypackage/shared-components/loader/index.js';

内容的提问来源于stack exchange，提问作者Thomas