Flux

A design editor for your localhost. Point to an element on the UI, tweak visual properties and copy the changes. The copied changes can be sent to any AI agent with the source to make the changes come alive.

React only for now — Flux ships as a React component; Vue, Svelte, and plain HTML apps are not supported yet.

Install

npm install @sanmid/flux -D

Or: pnpm add -D @sanmid/flux · yarn add -D @sanmid/flux

Icons, clsx, and tailwind-merge are dependencies of Flux — you do not install them separately. You only need react and react-dom (18+) in your app (Flux lists them as peer dependencies so one React instance is shared with your UI).

Local development (localhost)

Mount DesignEditor in your app root (providers layout) so it appears over your pages in dev:

"use client";
import { DesignEditor } from "@sanmid/flux";

export function Providers({ children }: { children: React.ReactNode }) {
  return (
    <>
      {children}
      {process.env.NODE_ENV === "development" && <DesignEditor />}
    </>
  );
}

Open your app at http://localhost:3000 (or your dev URL). Toggle the editor with the floating control or ⌘. / Ctrl+.

• force — render in production builds (use only if you accept exposing the overlay to end users).
• blockPageInteractions — optional; blocks clicks on buttons/links on the host page while editing (useful in demos).
• Inline text — double-click the current selection to edit copy in place (plain text nodes, text-like inputs). Blur commits, Escape cancels. Stored with other preview data in localStorage. In React apps, a host re-render can still overwrite DOM text until you wire edits into your source of truth.

Tailwind

Flux injects its own utility CSS for light-DOM UI (floating toggle, panel chrome, etc.), so you do not need to add Flux to your Tailwind content for normal use.

If you fork Flux or build from source and change its class names, add your paths (or the published bundle) to content so your build picks up those utilities.

Next.js

No extra Next config — the published build ships ESM and CJS (package.json exports) and a "use client" banner so the App Router can consume @sanmid/flux like any other dependency. Mount DesignEditor from a client component (as in Local development) and you are done.

If you ever hit a resolution error on an older Next.js release, try adding transpilePackages: ["@sanmid/flux"] to next.config as a fallback.

Security

See SECURITY.md for data handling (clipboard, localStorage, DOM), reporting vulnerabilities, and production considerations.

Publishing to npm (maintainers)

1. Version — bump "version" in package.json (semver).
2. Build — pnpm install && pnpm run build (runs automatically via prepublishOnly).
3. Login — npm login (or your registry).
4. Publish — npm publish --access public (required for scoped public packages like @sanmid/flux).

Optional: enable provenance on supported registries for supply-chain transparency.

Repository layout

| Path | Role | | --- | --- | | src/ | Library source (TypeScript / React). | | dist/ | Build output (not committed). Produced by pnpm run build. | | package.json → files | Only dist, README.md, LICENSE, and SECURITY.md are published to npm — that is what consumers install. | | playground/ | Optional Vite app for local testing; not on npm, but usually kept in git so maintainers can run pnpm run dev:playground without a separate repo. | | scripts/ | Tailwind → CSS strings, tsup, prepend-use-client. |

Playground

This repo includes a private Vite app under playground/ for local demos. It is not part of the published npm artifact. See CONTRIBUTING.md.

pnpm run dev:playground

Contributing

See CONTRIBUTING.md.

License

MIT — see LICENSE. Other packages on npm may use different licenses (for example Polyform Shield); that is independent of Flux’s license.