OpenSearch Dashboards自定义插件SCSS与动态导入报错排查

问题现象 #

浏览器加载插件时触发运行时错误：

TypeError: Cannot read properties of undefined (reading 'call')
at webpack_require (http://localhost:5601/8260/bundles/plugin/swiftDashboard/swiftDashboard.plugin.js:1:923)
at async mount (http://localhost:5601/8260/bundles/plugin/swiftDashboard/swiftDashboard.plugin.js:1:6452)

插件配置 #

使用官方@osd/plugin-helpers构建插件（执行yarn build），依赖包括：

• TypeScript
• React（含react-router-dom）
• SCSS样式表
• 在mount()中通过动态import()实现代码分割

plugin.ts 代码 #

core.application.register({
  id: 'swiftDashboard',
  title: 'SWIFT Dashboard',
  async mount(params: AppMountParameters) {
    const { element } = params;
    try {
      const applicationsModule = await import('./applications');
      const [coreStart, depsStart] = await core.getStartServices();
      return applicationsModule.renderApp(params, coreStart, depsStart);
    } catch (error) {
      element.innerHTML = `<p>Failed to load app: ${error.message}</p>`;
      return () => {};
    }
  }
});

applications.tsx 代码 #

import React from 'react';
import ReactDOM from 'react-dom';
import App from './components/App';
import { BrowserRouter } from 'react-router-dom';
import './styles/main.scss'; // SCSS导入

export const renderApp = (params, coreStart, plugins) => {
  ReactDOM.render(
    <BrowserRouter basename="/app/swiftDashboard">
      <App coreStart={coreStart} plugins={plugins} />
    </BrowserRouter>,
    params.element
  );

  return () => ReactDOM.unmountComponentAtNode(params.element);
};

自定义Webpack SCSS配置（未被@osd/plugin-helpers识别） #

const path = require('path');

module.exports = {
  resolve: {
    extensions: ['.ts', '.tsx', '.js', '.jsx', '.json'],
  },
  module: {
    rules: [
      {
        test: /\.scss$/,
        use: [
          'style-loader',
          'css-loader',
          {
            loader: 'sass-loader',
            options: {
              sassOptions: {
                includePaths: [path.resolve(__dirname, '../../../node_modules')],
              },
            },
          },
        ],
        exclude: /node_modules/,
      },
    ],
  },
};

补充信息 #

• SCSS文件用于组件级样式及全局main.scss
• renderApp已正确导出和导入
• 已安装的开发依赖：
  • "sass-loader": "^12.6.0"
  • "sass": "^1.69.0"
  • "style-loader": "^2.0.0"
  • "css-loader": "^5.2.7"
• 执行yarn build时@osd/plugin-helpers会忽略自定义webpack.config.js

问题解答 #

1. 如何在OpenSearch Dashboards插件中正确使用SCSS，避免触发Webpack运行时错误？ #

错误根源是@osd/plugin-helpers未识别自定义Webpack配置，导致SCSS文件未被正确编译，最终在运行时触发模块加载失败。解决步骤：

• 放弃自定义webpack.config.js，改用OpenSearch Dashboards官方的样式处理方案
• 将SCSS文件后缀改为.module.scss，使用CSS Modules方式导入（官方推荐的隔离样式方案）
• 移除style-loader/css-loader的手动配置，依赖插件助手内置的样式处理逻辑
• 重新执行yarn build，确保样式被正确打包到插件bundle中

示例修改：
将main.scss重命名为main.module.scss，然后在代码中导入：

import styles from './styles/main.module.scss';
// 在组件中使用：className={styles.container}

2. 使用@osd/plugin-helpers时，处理SCSS样式的推荐方式是什么？ #

官方推荐两种方案：

• CSS Modules：将样式文件命名为[name].module.scss，通过ES模块导入使用，插件助手会自动处理编译和样式隔离，无需额外配置
• 全局样式：如果需要全局样式，可将SCSS文件放在public/目录下，在插件的opensearch_dashboards.json中配置uiSettings引用，或通过core.uiSettings.register注册全局样式

另外，无需手动安装sass-loader/css-loader等依赖，@osd/plugin-helpers已内置兼容版本，手动安装可能导致版本冲突。

3. 动态导入或CSS处理是否会干扰OpenSearch Dashboards的构建/运行时系统？ #

• 动态导入：官方支持在mount()中使用动态import()做代码分割，不会干扰构建和运行时，但需确保导入的模块路径正确，且模块内的代码符合OpenSearch Dashboards的插件规范（比如不直接操作全局变量）
• CSS处理：只要遵循官方推荐的样式方案（CSS Modules或全局样式），就不会干扰系统；自定义Webpack配置会被插件助手忽略，反而会导致样式编译失败，触发运行时错误

内容的提问来源于stack exchange，提问作者Suvendran Ajai Intern