如何在Ruby on Rails引擎Gem中引入并管理NPM依赖？

在Rails引擎Gem里管理NPM依赖确实是个容易卡壳的点，我给你整理几个社区里常用的可行方案，你可以根据自己的场景选：

这是最直接的方式，通过引擎的安装生成器，把引擎需要的NPM依赖自动添加到宿主应用的package.json里，同时提示用户完成安装。

步骤如下：

1. 在引擎根目录创建package.json：
   把引擎需要的NPM包都列在这里，比如：

   {
     "dependencies": {
       "axios": "^1.5.0",
       "vue": "^3.3.4"
     }
   }
   

2. 编写安装生成器：
   在lib/generators/your_engine/install_generator.rb中添加逻辑，读取引擎的package.json并合并到宿主的文件中：

   require 'rails/generators'
   require 'json'
   
   module YourEngine
     module Generators
       class InstallGenerator < Rails::Generators::Base
         source_root File.expand_path('templates', __dir__)
   
         def merge_npm_dependencies
           # 读取引擎的依赖配置
           engine_package_path = File.expand_path('../../../../package.json', __dir__)
           engine_deps = JSON.parse(File.read(engine_package_path))['dependencies']
   
           # 读取宿主的package.json
           host_package_path = Rails.root.join('package.json')
           host_package = JSON.parse(File.read(host_package_path))
           host_package['dependencies'] ||= {}
   
           # 合并依赖（避免覆盖已存在的包）
           engine_deps.each do |pkg, version|
             unless host_package['dependencies'].key?(pkg)
               host_package['dependencies'][pkg] = version
               say "Added #{pkg}@#{version} to your package.json"
             end
           end
   
           # 写回更新后的package.json
           File.write(host_package_path, JSON.pretty_generate(host_package))
   
           # 提示用户完成安装
           say "\nDon't forget to run `npm install` or `yarn install` to set up the new dependencies!"
         end
       end
     end
   end
   

3. 用户安装流程：
   宿主应用安装引擎后，只需运行rails generate your_engine:install，生成器就会自动处理依赖合并，然后提示执行包安装命令。

如果你的目标宿主应用用的是jsbundling-rails或者webpacker，可以让引擎直接对接这些工具的配置，让宿主的构建流程自动识别引擎的NPM依赖。

比如针对jsbundling-rails，在引擎的engine.rb里添加：

module YourEngine
  class Engine < ::Rails::Engine
    # 让宿主的资产管道识别引擎的JS目录
    initializer 'your_engine.assets' do |app|
      app.config.assets.paths << root.join('app/javascript')
    end

    # 告知jsbundling-rails包含引擎的node_modules（如果引擎本地安装了依赖）
    config.before_configuration do
      if defined?(JsBundling)
        Rails.application.config.js_bundling.node_modules_paths << root.join('node_modules')
      end
    end
  end
end

同时在引擎的package.json里声明依赖，然后在README里说明：宿主安装引擎后，需要执行npm install来安装这些依赖，引擎的JS文件会被自动纳入构建流程。

如果你的引擎依赖的NPM包体积小、版本稳定，可以直接把编译后的JS/CSS文件打包到引擎的app/assets目录里，这样宿主应用不需要额外安装NPM包，直接通过资产管道加载即可。

比如你可以本地运行npm install，把node_modules里需要的文件复制到app/assets/javascripts/your_engine/vendor/目录下，然后在引擎的engine.rb里添加：

module YourEngine
  class Engine < ::Rails::Engine
    initializer 'your_engine.assets.precompile' do |app|
      app.config.assets.precompile += %w( your_engine/vendor/axios.min.js your_engine/vendor/vue.global.prod.js )
    end
  end
end

这个方案的好处是零宿主配置，但缺点是无法自动更新NPM包，适合依赖固定的小引擎。

• 版本冲突处理：在生成器里最好加入版本检查逻辑，如果宿主已经安装了同个包但版本不兼容，要提示用户手动确认。
• 文档说明：不管用哪种方案，一定要在引擎的README里写清楚NPM依赖的安装步骤，避免用户踩坑。
• 测试兼容性：在不同版本的Rails应用（比如Rails 6 vs Rails 7）里测试你的依赖集成逻辑，确保兼容性。

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