SuperAPI AI Directory
Partner中文AI newsFavorites
Skillsuiux-react-jsx-packager

uiux-react-jsx-packager

Frontend & websites

View repository

Updated 10-16 08:49

About this skill

uiux-react-jsx-packager

Output Contract

  • Create one new *.jsx file (do not overwrite existing files unless explicitly requested).
  • Export the root component via export default.
  • Keep runtime dependencies to React only (no react-router, lucide-react, echarts, classnames, zustand, etc.).
  • Keep styles in-file via <style> injection and/or inline style={{...}}.
  • Replace icon libraries with inline SVG components.
  • Replace images with base64-inlined data URLs or deterministic placeholders.
  • Implement navigation via component state (optionally sync to location.hash for shareable URLs).
  • Preserve all interactions/animations/state logic; do not simplify behavior.
  • Prefer embedding the compiled CSS (if available) to preserve spacing/colors/shadows.

About "pixel-perfect" (optional enhancement, not a default gate)

"Pixel-perfect" must have its conditions constrained in engineering terms, otherwise it is not verifiable.Only when you want to claim pixel-perfect externallydo you need to do pixel diff acceptance:

  • The same machine, the same OS and the same browser version (recommended to pin the Chrome version)
  • Fixed viewport (width and height) and deviceScaleFactor（DPR）
  • Fonts must be consistent (including font weight): do not rely on system font differences; if necessary, inline the font files into CSS as @font-face (base64 data URL)
  • When taking screenshots for comparison, it must be in a "stable state": avoid in-progress animations/transitions affecting the pixel diff (see Verification)

The strong gate for default delivery is "portable and runnable, no white screen, navigation usable" (see Verification Gate).

Workflow (do in order)

1) Discover structure and runtime surface

  • Find and follow any AGENTS.md instructions that apply to the target directory tree.
  • Locate the actual app entry (src/main.*, src/index.*, App.*) and identify:
    • Router entrypoints (hash router / react-router / custom)
    • Pages and module switch logic
    • Global providers (theme/style/toast/auth)
    • Global CSS + theme tokens (CSS variables, dark mode attribute, etc.)
    • Third-party runtime deps that must be removed (icons, charts, router, utilities)
  • Prefer reading the demo source plus the built output CSS (if it exists) to lock visuals.

2) Choose a “visual parity” strategy for styles (pick one)

  • Preferred: Embed production/built CSS (e.g. dist/assets/index-*.css) into const APP_CSS = String.raw\...`;and inject via`.
    • Keep existing className strings unchanged.
    • This is the most reliable way to keep spacing/colors/shadows identical without Tailwind tooling.
  • Otherwise: Inline/merge source CSS files into one <style> block (still in-file).

Pixel-perfect strongly depends on styles and fonts, please additionally confirm:

  • CSS variables / theme tokens (dark mode attribute/class) are consistent with the original project
  • All external font/icon resources are localized/inlined (do not rely on remote URLs)
  • Use the same set of reset / box-sizing rules for screenshot comparison (recommended to use the built CSS directly)

3) Create the merge target file

  • Create YourNameMerged.jsx with:
    • A single React import (import React, { ... } from 'react';)
    • APP_CSS string + a AppStyleTag() that injects exactly one <style> node
    • Helpers you will need (clamp, download, clipboard, etc.)

4) Merge code into one file (no module imports)

  • Copy code for components/pages/hooks/utils into the single file.
  • Remove all non-React imports; replace with local definitions.
  • Remove TypeScript syntax:
    • Delete interface, type, generics (useState<string>()), and annotations (x: string)
    • Remove as T assertions
  • Keep behavior identical:
    • Same default state values
    • Same reducers/actions
    • Same animations (CSS-based or requestAnimationFrame-based)

5) Replace third-party runtime dependencies (patterns)

Router → state router

  • Implement a tiny state router (context + navigate(module, subPath)).
  • Optionally keep hash sync for shareable URLs, but the source of truth must be React state.

Minimal pattern (adapt, do not paste blindly):

const RouterContext = React.createContext();
function RouterProvider({ children }) {
  const [route, setRoute] = React.useState({ module_key: 'text_workbench', subPath: '' });
  const navigate = React.useCallback((module_key, subPath = '') => setRoute({ module_key, subPath }), []);
  return <RouterContext.Provider value={{ route, navigate }}>{children}</RouterContext.Provider>;
}
function useRouter() { return React.useContext(RouterContext); }

Icons (lucide-react etc.) → inline SVG

  • Replace icon imports with local React components that return <svg ...> + <path ...>.
  • Keep size/stroke defaults consistent with the original icon system.

Charts (echarts etc.) → SVG/Canvas + fallback table

  • Re-implement charts with pure SVG/Canvas.
  • Preserve:
    • Tooltips
    • Click/hover actions (emit the same callbacks)
    • Accessible labels (aria where relevant)
    • Data table fallback (for regressions and accessibility)

6) Images and external assets

  • Replace runtime-loaded images with:
    • data:image/...;base64,... (preferred when you need fidelity)
    • Or deterministic placeholders (solid blocks, initials avatars, etc.)
  • Never leave remote URLs in the final file unless explicitly allowed.

7) Wire the root component to real pages

  • Ensure the default export renders the real module pages (not placeholders).
  • Wrap providers in the same order as the original app (style/theme/toast/auth).
  • Keep module-level side effects intact (e.g. console events, reducers, mock async flows).

8) Verification (must run before “done”)

Verification Gate (required by default)

Must be verified in order; if any step fails, it does not count as "packaging complete":

  1. Static gate (required)

    • Keep only 1 import ... from 'react'
    • Has export default
    • No require() / import()
    • No asset imports (.css/.svg/.png/...）
    • Run:python3 scripts/verify_singlefile_jsx.py /path/to/Merged.jsx

  2. Runtime gate (required)

    • Use a "temporary preview project" to load the .jsx, ensureno white screen on first paint, and can complete the minimal interaction smoke:
      • Sidebar (or top bar) switches main modules/pages (at least one round of clicking can switch content)
      • location.hash switching (if you implemented hash sync)
    • Recommended to use the script bundled with this skill:bash scripts/preview_single_jsx_vite.sh /path/to/Merged.jsx

Common misjudgment: when the port is occupied, Vite will output Port XXXX is in use, trying another one... and automatically switch ports.Must use the Local: URL output by the terminal as the standard, do not fixate on a fixed port.

  1. Portability gate (required)
    • Does not depend on remote resources (do not use https://...）
    • Do not leak absolute paths in the UI/comments (e.g., local username/directory structure)

Optional enhancement (only required when you claim pixel-perfect)

  • Use screenshot diff for pixel-level comparison (fixed browser/viewport/DPR, disable animations/transitions).
  • Optionally do bundle sanity:
    • npx esbuild merged.jsx --bundle --format=esm --external:react --outfile=/tmp/merged.js

Use the bundled verifier:

python3 scripts/verify_singlefile_jsx.py /path/to/YourMerged.jsx

Pixel-perfect visual regression (recommended, required if you claim pixel-perfect)

The most reliable way is to put YourMerged.jsx back into the original demo project temporarily, render it using the original project's build pipeline (to ensure the font/CSS environment is consistent), and then use screenshots for pixel diff:

  1. Add a "comparison page/comparison route" in the original project (only for local verification):
    • OriginalApp: original page
    • MergedApp: render YourMerged.jsx 's default export
  2. Run screenshots with the same Playwright configuration:
    • Fixed viewport / deviceScaleFactor
    • prefers-reduced-motion: reduce
    • Inject a snapshot CSS (test environment only) to disable transitions and animations, for example:
      • *,*::before,*::after{animation:none!important;transition:none!important;}
  3. Compare using a pixel-level threshold of 0 (or a very small threshold); if there are differences, go back and investigate the CSS/font/layout sources.

Note:npx playwright install and similar commands may download browser binaries (supply chain and network risks). If your environment requires offline/fixed versions, use the installed Playwright with a fixed browser version.

Bundled Scripts

  • scripts/verify_singlefile_jsx.py: Heuristic gate to catch non-React imports, require(), missing default export, and common TS residue.
  • scripts/preview_single_jsx_vite.sh: Spin up an isolated Vite dev server under /tmp and preview a single .jsx file with an ErrorBoundary and reliable URL output.

References

  • references/preview-and-smoke.md: Preview pitfalls (port switching, cache reuse), smoke checklist, and troubleshooting playbook.