@eyedially/cli

Scaffold self-contained, zero-dependency Eyedially visualizations into any web project. No runtime dependencies, no build step, no lock-in.

Install / run

npx @eyedially/cli add <simulation-id> --framework <framework>

Or install globally:

npm install -g @eyedially/cli
eyedially add <simulation-id> --framework react

Commands

| Command | Description | | ------------------ | ------------------------------------------------------------------------ | | add <id> | Fetch and scaffold a visualization into your project. | | sync | Recreate every visualization recorded in eyedially.json. | | init | Write an eyedially.json config (no install) based on auto-detection. |

--framework is optional: when omitted the CLI detects it from your project (React for Next/Vite/Angular/Astro, Vue for Vue/Nuxt, Svelte for SvelteKit). Override with --framework react|vue|svelte|web-component|standalone|all.

Where files go (auto-detection)

The CLI detects your framework and writes into its conventional components directory — so a component never lands outside src when one exists:

| Project type | Components directory | | ----------------------- | ------------------------------------------ | | Vite / Next / Astro | src/components/eyedially/<slug> | | Vue / Nuxt | src/components (Nuxt: top-level components) | | SvelteKit | src/lib/components/eyedially/<slug> | | Angular | not supported (see below) | | Standalone (no src) | components/eyedially/<slug> |

--out <dir> always overrides detection.

Framework support

• React (Vite, Next.js Pages & App Router, CRA, Astro): the generated wrapper is a Client Component — it starts with 'use client', so it works in Next.js App Router (SSR-safe; the canvas only runs in useEffect). TypeScript is auto-detected via tsconfig.json (.tsx instead of .jsx).
• Vue / Nuxt, Svelte / SvelteKit, and Astro (with the matching integration) are supported via their native component files.
• Angular is not supported. There is no Angular wrapper — --framework react emits a React component that Angular cannot consume. For Angular projects, run the CLI with --framework web-component (a framework-agnostic custom element) or standalone instead.

Registry & offline

The CLI fetches from the catalog at https://www.eyedially.dev. Override the endpoint with --registry <url>, the EYEDIALY_REGISTRY environment variable, or a registry field inside eyedially.json (precedence: --registry > env > config > default). Use --verbose to print the resolved root, components directory, and output directory — handy when a second add appears to write to the wrong place.

Output format

Each visualization is emitted as native, framework-idiomatic files plus a shared embedded runtime (index.js):

| --framework | Files | | --------------- | ------------------------------------------------------------ | | react | <Name>.jsx (or .tsx) + index.js | | vue | <Name>.vue + index.js | | svelte | <Name>.svelte + index.js | | web-component | element.js (custom element <sim-<slug>>) | | standalone | index.html + element.js | | all | every framework above |

TypeScript is auto-detected from tsconfig.json; force with --typescript / --no-typescript.

eyedially.json (manifest)

On the first add the CLI writes eyedially.json at your project root and records every install. An existing componentsDir in that file is authoritative and overrides detection, letting you relocate the components folder:

{
  "framework": "react",
  "componentsDir": "src/components",
  "typescript": false,
  "installs": [
    { "id": "clones", "name": "Clones", "slug": "clones", "path": "src/components/eyedially/clones", "addedAt": "…" }
  ]
}

eyedially sync re-fetches every recorded id and rewrites its folder — handy after a fresh clone or to upgrade installed visualizations.

Registry

The CLI fetches simulation source from the Eyedially registry. Override the endpoint with --registry <url> or the EYEDIALY_REGISTRY environment variable (defaults to https://www.eyedially.dev):

npx @eyedially/cli add worm-hole --framework react --registry https://www.eyedially.dev

Example

npx @eyedially/cli add clones --framework react
# writes src/components/eyedially/clones/{index.js,Clones.jsx,README.md}

All generated files are plain ES modules with an embedded canvas runtime, so they work in any modern bundler or even directly in the browser.