fix(icon): resolve per-collection @iconify-json packages

Resolution only understood the monolithic @iconify/json, which ships
every collection in roughly 120MB. Projects overwhelmingly install the
per-collection @iconify-json/<prefix> packages instead, and for those
every <Icon> on every page rendered as an empty string: a nav of blank
buttons with nothing in the markup to explain it.

Both conventions now resolve, per-collection first. The project's own
install is also checked ahead of require.resolve, which resolves
relative to this module and would otherwise let a collection vendored
inside stx shadow the one the app declared.

A missing collection now warns once with the install command instead of
silently rendering nothing.

Author: chrisbbreuer

packages/stx/src/builtins/icon.ts

@@ -23,25 +23,62 @@ type IconCollection = Record<string, { body: string, width?: number, height?: nu
 // Cache loaded icon collections to avoid re-reading JSON files
 const collectionCache = new Map<string, IconCollection>()
 
+/** Prefixes already reported as missing, so the warning fires once per run. */
+const warnedMissingCollections = new Set<string>()
+
 /**
- * Resolve the on-disk path of an icon collection JSON, checking the
- * standard locations: the package resolver, then `node_modules/`, then
- * Stacks-style `pantry/` (which sits parallel to node_modules in apps
- * that use pantry as their vendor directory).
+ * A missing collection used to render as an empty string, so every icon on the
+ * page silently disappeared and the markup gave no hint why. Say it once, with
+ * the install command, rather than leaving a blank UI to diagnose.
  */
-function resolveCollectionPath(prefix: string): string | null {
-  try {
-    return require.resolve(`@iconify/json/json/${prefix}.json`)
-  }
-  catch { /* fall through */ }
+function warnMissingCollection(prefix: string): void {
+  if (warnedMissingCollections.has(prefix)) return
+  warnedMissingCollections.add(prefix)
+  console.warn(
+    `[stx] icon collection "${prefix}" is not installed, so its icons render as nothing. `
+    + `Install it with \`bun add -d @iconify-json/${prefix}\`.`,
+  )
+}
 
+/**
+ * Resolve the on-disk path of an icon collection JSON.
+ *
+ * Two packaging conventions are accepted. `@iconify/json` ships every
+ * collection in one ~120MB dependency; `@iconify-json/<prefix>` ships a single
+ * collection in about a megabyte and is what most projects actually install.
+ * Supporting only the monolith meant an app with `@iconify-json/lucide`
+ * installed rendered nothing at all for every icon on every page, with no
+ * error to explain it.
+ *
+ * Each convention is checked through the package resolver first, then against
+ * `node_modules/` and Stacks-style `pantry/` (which sits parallel to
+ * node_modules in apps that vendor there).
+ */
+export function resolveCollectionPath(prefix: string): string | null {
+  // The consuming project's own install wins. `require.resolve` resolves
+  // relative to THIS module, so it happily returns a collection vendored
+  // inside stx's own dependencies even when the app never installed one —
+  // which silently renders a different icon set than the app declared.
   const cwd = process.cwd()
   for (const candidate of [
+    `${cwd}/node_modules/@iconify-json/${prefix}/icons.json`,
+    `${cwd}/pantry/@iconify-json/${prefix}/icons.json`,
     `${cwd}/node_modules/@iconify/json/json/${prefix}.json`,
     `${cwd}/pantry/@iconify/json/json/${prefix}.json`,
   ]) {
     if (existsSync(candidate)) return candidate
   }
+
+  for (const specifier of [
+    `@iconify-json/${prefix}/icons.json`,
+    `@iconify/json/json/${prefix}.json`,
+  ]) {
+    try {
+      return require.resolve(specifier)
+    }
+    catch { /* try the next convention */ }
+  }
+
   return null
 }
 
@@ -56,7 +93,10 @@ function loadCollectionSync(prefix: string): IconCollection | null {
   if (collectionCache.has(prefix)) return collectionCache.get(prefix)!
 
   const jsonPath = resolveCollectionPath(prefix)
-  if (!jsonPath) return null
+  if (!jsonPath) {
+    warnMissingCollection(prefix)
+    return null
+  }
 
   try {
     const data = JSON.parse(readFileSync(jsonPath, 'utf8'))
@@ -76,7 +116,10 @@ async function loadCollection(prefix: string): Promise<IconCollection | null> {
   if (collectionCache.has(prefix)) return collectionCache.get(prefix)!
 
   const jsonPath = resolveCollectionPath(prefix)
-  if (!jsonPath) return null
+  if (!jsonPath) {
+    warnMissingCollection(prefix)
+    return null
+  }
 
   try {
     const data = await Bun.file(jsonPath).json()

packages/stx/test/icon-collection-resolution.test.ts

@@ -0,0 +1,95 @@
+/**
+ * Tests for locating an icon collection on disk.
+ *
+ * Regression focus: resolution only understood the monolithic `@iconify/json`
+ * package (~120MB, every collection). Projects overwhelmingly install the
+ * per-collection `@iconify-json/<prefix>` packages instead, and for those every
+ * `<Icon>` on every page rendered as an empty string with no error — a blank
+ * nav and blank buttons with nothing in the markup to explain it.
+ */
+
+import { existsSync, mkdirSync, mkdtempSync, realpathSync, rmSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import process from 'node:process'
+import { afterEach, describe, expect, it } from 'bun:test'
+import { resolveCollectionPath } from '../src/builtins/icon'
+
+const originalCwd = process.cwd()
+const roots: string[] = []
+
+// realpath because macOS hands out /var/folders/… which is a symlink to
+// /private/var/folders/…, and `process.cwd()` reports the resolved form.
+function makeRoot(): string {
+  const root = realpathSync(mkdtempSync(join(tmpdir(), 'stx-icons-')))
+  roots.push(root)
+  return root
+}
+
+/** Write a stub collection at `relativePath` under `root`. */
+function writeCollection(root: string, relativePath: string): string {
+  const full = join(root, relativePath)
+  mkdirSync(join(full, '..'), { recursive: true })
+  writeFileSync(full, JSON.stringify({ icons: { play: { body: '<path/>' } } }))
+  return full
+}
+
+afterEach(() => {
+  process.chdir(originalCwd)
+  for (const root of roots.splice(0)) {
+    if (existsSync(root)) rmSync(root, { recursive: true, force: true })
+  }
+})
+
+describe('icon collection resolution', () => {
+  it('finds a per-collection @iconify-json package in node_modules', () => {
+    const root = makeRoot()
+    const expected = writeCollection(root, 'node_modules/@iconify-json/lucide/icons.json')
+    process.chdir(root)
+
+    expect(resolveCollectionPath('lucide')).toBe(expected)
+  })
+
+  it('finds a per-collection package vendored in pantry', () => {
+    const root = makeRoot()
+    const expected = writeCollection(root, 'pantry/@iconify-json/lucide/icons.json')
+    process.chdir(root)
+
+    expect(resolveCollectionPath('lucide')).toBe(expected)
+  })
+
+  it('still finds the monolithic @iconify/json package', () => {
+    const root = makeRoot()
+    const expected = writeCollection(root, 'node_modules/@iconify/json/json/lucide.json')
+    process.chdir(root)
+
+    expect(resolveCollectionPath('lucide')).toBe(expected)
+  })
+
+  it('prefers the per-collection package when both are present', () => {
+    const root = makeRoot()
+    const perCollection = writeCollection(root, 'node_modules/@iconify-json/lucide/icons.json')
+    writeCollection(root, 'node_modules/@iconify/json/json/lucide.json')
+    process.chdir(root)
+
+    expect(resolveCollectionPath('lucide')).toBe(perCollection)
+  })
+
+  it('returns null when the collection is installed under neither convention', () => {
+    const root = makeRoot()
+    process.chdir(root)
+
+    expect(resolveCollectionPath('definitely-not-a-collection')).toBeNull()
+  })
+
+  it("prefers the project's own install over one vendored inside stx", () => {
+    // `require.resolve` resolves relative to the stx module, so without the
+    // cwd check first a collection sitting in stx's own dependencies would
+    // shadow the one the app actually declared.
+    const root = makeRoot()
+    const projectCopy = writeCollection(root, 'node_modules/@iconify-json/hugeicons/icons.json')
+    process.chdir(root)
+
+    expect(resolveCollectionPath('hugeicons')).toBe(projectCopy)
+  })
+})