Support selecting component package files

Author: samuel-williams-shopify

bake/utopia/components.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Samuel Williams.
+
+NPM = ENV["NPM"] || "npm"
+
+# Update public components from production JavaScript packages.
+#
+# Packages are copied from their `dist` directory when present, or otherwise
+# from the package root. The `utopia.components` section of `package.json` can
+# specify per-package `include` patterns to select only required files.
+#
+# @parameter root [String] The project root directory.
+def update(root: context.root)
+	require "json"
+	require "open3"
+	require "utopia/components"
+	
+	components = Utopia::Components.new(root)
+	production_packages = fetch_production_packages(components.package_root)
+	
+	components.update(production_packages)
+end
+
+private
+
+def fetch_production_packages(package_root)
+	stdout, _status = Open3.capture2(NPM, "ls", "--production", "--json", chdir: package_root.to_s)
+	json = JSON.parse(stdout)
+	
+	flatten_package_dependencies(json).sort.uniq
+end
+
+def flatten_package_dependencies(json, into = [])
+	if json["dependencies"]
+		json["dependencies"].each do |name, details|
+			into << name
+			flatten_package_dependencies(details, into)
+		end
+	end
+	
+	return into
+end

bake/utopia/node.rb

@@ -17,7 +17,7 @@ $ npm install jquery
 Copy the distribution files to `public/_components`:
 
 ```bash
-$ bundle exec bake utopia:node:update
+$ bundle exec bake utopia:components:update
 ```
 
 This will copy the library's distribution files (typically from `node_modules/*/dist/`) to your `public/_components/` directory, making them available for local serving.

context/integrating-with-javascript.md

@@ -17,7 +17,7 @@ $ npm install jquery
 Copy the distribution files to `public/_components`:
 
 ```bash
-$ bundle exec bake utopia:node:update
+$ bundle exec bake utopia:components:update
 ```
 
 This will copy the library's distribution files (typically from `node_modules/*/dist/`) to your `public/_components/` directory, making them available for local serving.

guides/integrating-with-javascript/readme.md

@@ -0,0 +1,133 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Samuel Williams.
+
+require "fileutils"
+require "json"
+require "pathname"
+
+module Utopia
+	# Installs JavaScript packages into the public components directory.
+	class Components
+		# Initialize a component installer for the given project root.
+		#
+		# @parameter root [String | Pathname] The project root directory.
+		def initialize(root)
+			@root = Pathname.new(root)
+			@package_root = @root + "node_modules"
+			
+			# This is a legacy path:
+			unless @package_root.directory?
+				@package_root = @root + "lib/components"
+			end
+			
+			@install_root = @root + "public/_components"
+			@configuration = load_configuration
+		end
+		
+		attr :package_root
+		
+		# Update the specified packages in the public components directory.
+		#
+		# @parameter package_names [Array(String)] The production package names to install.
+		def update(package_names)
+			expand_package_paths(@package_root).each do |package_path|
+				package_name = package_path.relative_path_from(@package_root).to_s
+				
+				if package_names.include?(package_name)
+					install(package_name, package_path)
+				end
+			end
+		end
+		
+		private
+		
+		def load_configuration
+			package_path = @root + "package.json"
+			return {} unless package_path.file?
+			
+			configuration = JSON.parse(package_path.read).dig("utopia", "components") || {}
+			
+			unless configuration.is_a?(Hash)
+				raise ArgumentError, "utopia.components must be an object!"
+			end
+			
+			return configuration
+		end
+		
+		def install(package_name, package_path)
+			install_path = @install_root + package_name
+			dist_path = package_path + "dist"
+			source_path = dist_path.directory? ? dist_path : package_path
+			
+			if configuration = @configuration[package_name]
+				install_selected(package_name, source_path, install_path, configuration)
+			else
+				FileUtils::Verbose.rm_rf(install_path)
+				FileUtils::Verbose.mkpath(install_path.dirname)
+				FileUtils::Verbose.cp_r(source_path, install_path)
+			end
+		end
+		
+		def install_selected(package_name, source_path, install_path, configuration)
+			unless configuration.is_a?(Hash) && configuration["include"].is_a?(Array) && configuration["include"].any?
+				raise ArgumentError, "utopia.components.#{package_name}.include must be a non-empty array!"
+			end
+			
+			paths = configuration["include"].flat_map do |pattern|
+				included_paths(package_name, source_path, pattern)
+			end.uniq.sort
+			
+			FileUtils::Verbose.rm_rf(install_path)
+			
+			paths.each do |relative_path|
+				source_file = source_path + relative_path
+				install_file = install_path + relative_path
+				
+				FileUtils::Verbose.mkpath(install_file.dirname)
+				FileUtils::Verbose.cp(source_file, install_file)
+			end
+		end
+		
+		def included_paths(package_name, source_path, pattern)
+			unless pattern.is_a?(String) && relative_pattern?(pattern)
+				raise ArgumentError, "Invalid include pattern for #{package_name}: #{pattern.inspect}"
+			end
+			
+			paths = Dir.glob(pattern, base: source_path.to_s).select do |relative_path|
+				(source_path + relative_path).file?
+			end
+			
+			if paths.empty?
+				raise ArgumentError, "Include pattern for #{package_name} matched no files: #{pattern.inspect}"
+			end
+			
+			return paths
+		end
+		
+		def relative_pattern?(pattern)
+			path = Pathname.new(pattern)
+			
+			return false if path.absolute?
+			return false if path.each_filename.any?{|component| component == ".."}
+			
+			return true
+		end
+		
+		def expand_package_paths(root, into = [])
+			root.children.select(&:directory?).each do |path|
+				basename = path.basename.to_s
+				
+				# Handle organisation sub-directories which start with an '@' symbol:
+				if basename.start_with?("@")
+					expand_package_paths(path, into)
+				else
+					into << path
+				end
+			end
+			
+			return into
+		end
+	end
+end

lib/utopia/components.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Samuel Williams.
+
+require "fileutils"
+require "json"
+require "tmpdir"
+
+require "utopia/components"
+
+describe Utopia::Components do
+	def write(path, content)
+		FileUtils.mkdir_p(File.dirname(path))
+		File.write(path, content)
+	end
+	
+	it "copies selected files from a package distribution" do
+		Dir.mktmpdir do |root|
+			package = File.join(root, "node_modules/mermaid/dist")
+			write(File.join(package, "mermaid.esm.min.mjs"), "entry")
+			write(File.join(package, "chunks/mermaid.esm.min/diagram.mjs"), "chunk")
+			write(File.join(package, "chunks/mermaid.esm.min/diagram.mjs.map"), "map")
+			write(File.join(package, "mermaid.js"), "unused")
+			
+			write(File.join(root, "public/_components/mermaid/stale.mjs"), "stale")
+			write(File.join(root, "package.json"), JSON.generate(
+				"utopia" => {
+					"components" => {
+						"mermaid" => {
+							"include" => [
+								"mermaid.esm.min.mjs",
+								"chunks/mermaid.esm.min/**/*.mjs",
+							],
+						},
+					},
+				},
+			))
+			
+			subject.new(root).update(["mermaid"])
+			install = File.join(root, "public/_components/mermaid")
+			
+			expect(File.read(File.join(install, "mermaid.esm.min.mjs"))).to be == "entry"
+			expect(File.read(File.join(install, "chunks/mermaid.esm.min/diagram.mjs"))).to be == "chunk"
+			expect(File).not.to be(:exist?, File.join(install, "chunks/mermaid.esm.min/diagram.mjs.map"))
+			expect(File).not.to be(:exist?, File.join(install, "mermaid.js"))
+			expect(File).not.to be(:exist?, File.join(install, "stale.mjs"))
+		end
+	end
+	
+	it "copies unconfigured scoped packages using the existing behavior" do
+		Dir.mktmpdir do |root|
+			write(File.join(root, "package.json"), "{}")
+			write(File.join(root, "node_modules/@socketry/syntax/Syntax.js"), "syntax")
+			
+			subject.new(root).update(["@socketry/syntax"])
+			
+			installed = File.join(root, "public/_components/@socketry/syntax/Syntax.js")
+			expect(File.read(installed)).to be == "syntax"
+		end
+	end
+	
+	it "validates patterns before removing existing components" do
+		Dir.mktmpdir do |root|
+			write(File.join(root, "node_modules/mermaid/dist/mermaid.esm.min.mjs"), "entry")
+			write(File.join(root, "public/_components/mermaid/existing.mjs"), "existing")
+			write(File.join(root, "package.json"), JSON.generate(
+				"utopia" => {
+					"components" => {
+						"mermaid" => {"include" => ["missing/**/*.mjs"]},
+					},
+				},
+			))
+			
+			expect do
+				subject.new(root).update(["mermaid"])
+			end.to raise_exception(ArgumentError, message: be =~ /matched no files/)
+			
+			existing = File.join(root, "public/_components/mermaid/existing.mjs")
+			expect(File.read(existing)).to be == "existing"
+		end
+	end
+end