@smile-design/inspector

DOM Inspector engine for smile-design — TS / JSX AST property search & replace, Vite + Webpack source-map loaders, and the iframe-side runtime that powers hover / click / Alt+Click selection in the smile-design Web preview.

This package is the superset bundle of @smile-design/inspector-plugin used internally by @smile-design/mcp-server and the smile-design Web UI. End users who only need a Vite plugin to make their own project BYOP-compatible should reach for @smile-design/inspector-plugin instead — it is smaller and has no Babel runtime in its dependency closure when the loader is unused.

When to install which

| You want to… | Use | | --------------------------------------------------------------------- | ------------------------------------------ | | Make your own Vite project work with smile-design BYOP | @smile-design/inspector-plugin (lighter) | | Build something that programmatically rewrites JSX prop values by AST | @smile-design/inspector (this package) | | Wire smile-design's source-map loader into a Next.js (webpack) app | @smile-design/inspector (this package) |

Install

pnpm add @smile-design/inspector

Use

Property search & replace (AST engine)

import { PropertySearchEngine } from '@smile-design/inspector/engine/property-search';
import { PropertyReplaceEngine } from '@smile-design/inspector/engine/property-replace';

const search = new PropertySearchEngine();
const matches = await search.findUniqueProperties({
  projectDir: '/path/to/project',
  property: 'className',
});

const replace = new PropertyReplaceEngine();
await replace.replaceAll({
  projectDir: '/path/to/project',
  property: 'className',
  oldValue: 'bg-blue-500',
  newValue: 'bg-primary',
});

The engines parse .tsx / .jsx files with @babel/parser, walk JSX attributes with @babel/traverse, and rewrite source byte ranges with magic-string so source maps stay accurate.

Webpack loader (Next.js apps)

// next.config.ts
import { assertWebpackNotTurbopack } from '@smile-design/inspector/plugins/webpack-smile-src';

assertWebpackNotTurbopack();

export default {
  webpack(config, { dev }) {
    if (dev) {
      config.module.rules.unshift({
        test: /\.(jsx|tsx)$/,
        exclude: /node_modules/,
        enforce: 'pre',
        use: { loader: require.resolve('@smile-design/inspector/plugins/webpack-smile-src') },
      });
    }
    return config;
  },
};

The loader injects data-smile-src="<file>:<line>:<col>" into every JSX opening tag in dev mode so the iframe runtime can map a clicked DOM node back to a source location. Production builds skip the transform entirely.

Vite plugin & iframe runtime

These are re-exported verbatim from @smile-design/inspector-plugin:

import { smileSrc } from '@smile-design/inspector/plugins/vite-smile-src';
import { autoInstall } from '@smile-design/inspector/runtime/auto-install';

If your project does not need the AST engines or the webpack loader, prefer the smaller @smile-design/inspector-plugin for these.

Subpath exports

| Specifier | Use | | ------------------------------------------------------- | -------------------------------------------------- | | @smile-design/inspector | Type-only barrel placeholder (avoid bundle leak) | | @smile-design/inspector/engine/property-search | PropertySearchEngine — AST-based prop discovery | | @smile-design/inspector/engine/property-replace | PropertyReplaceEngine — AST-based prop rewrite | | @smile-design/inspector/plugins/webpack-smile-src | Webpack loader (Next.js dev) + Turbopack guard | | @smile-design/inspector/plugins/vite-smile-src | Vite plugin (re-exported from inspector-plugin) | | @smile-design/inspector/runtime/inspector-script | Iframe runtime entry (re-exported) | | @smile-design/inspector/runtime/dom-context-extractor | DOM → context serializer (re-exported) | | @smile-design/inspector/runtime/auto-install | Dev-only iframe runtime auto-install (re-exported) |

The package barrel (@smile-design/inspector) deliberately exports only types so consumers cannot accidentally pull @babel/* or DOM globals into their bundle — always import via a subpath.

Requirements

• Node.js ≥ 22 (LTS)
• TypeScript ≥ 5.4 (consumers)
• For the Vite plugin re-exports: Vite ≥ 5
• For the webpack loader: Next.js with the default webpack runtime (Turbopack is unsupported by design — assertWebpackNotTurbopack() throws early with guidance)

License

MIT