Quickstart

Install one adapter, add a config, then run the CLI. Pick your framework below.

Framework:

Next.js quickstart

1) Install

npm install -D @visualize-library/react

2) Add visualizelibrary.config.ts

import type { Config } from "@visualize-library/core";

const config: Config = {
  framework: "react",
  include: ["./app/components/**/*.tsx", "./components/**/*.tsx"],
  exclude: ["**/*.stories.*", "**/*.test.*"],
  nextAppDir: true,
};

export default config;

3) Run & use

Embed in Next dev server (App Router safe)

nextdev

npx visualizelibrary next

Mounts Visualize at /__visualize/ inside your existing Next dev server so it shares routing, env, and CSS.

Standalone preview server

dev

npx visualizelibrary preview

Runs Visualize on its own Express + Vite server at http://127.0.0.1:7777.

Static export

staticci

npx visualizelibrary export --out visualize-static

Builds a read-only bundle you can host anywhere (similar to build-storybook).

Notes

File: visualizelibrary.config.ts in your repo root.
Add tailwindCss to point at your globals (e.g., ./app/globals.css).
Set designSystem.tailwindConfigPath if you want Tailwind tokens harvested.
Use themeBridgePath if your app ignores prefers-color-scheme and you need our light/dark toggle forwarded.

Configuration reference

A complete visualizelibrary.config.ts you can copy/paste. Layer the playbooks below to fit your stack.

import type { Config } from "@visualize-library/core";

const config: Config = {
  framework: "react",
  include: ["./app/**/*.tsx", "./components/**/*.tsx"],
  exclude: ["**/*.stories.*", "**/*.test.*"],
  tailwindCss: "./app/globals.css",
  themeProviderPath: "./app/providers.tsx",
  themeBridgePath: "./app/themeBridge.ts",
  hostDependencies: ["next/link", "next/image"],
  previewEnv: { NEXT_PUBLIC_API_BASE: "http://localhost:4000" },
  previewEnvPrefixes: ["NEXT_PUBLIC_", "VISUALIZE_"],
  port: 7777,
  host: "127.0.0.1",
  basicAuth: false, // or { user: "admin", pass: "secret" }
  nextAppDir: true,
  supportsRsc: true,
  designSystem: {
    cssTokensPath: "./app/globals.css",
    tailwindConfigPath: "./tailwind.config.ts",
    enableTokens: true,
    libraryUrl: "https://www.figma.com/file/your-library",
  },
};

export default config;

Core essentials

The minimum to index your components and align with App Router + RSC when needed.

framework: "react" | "vue"
include / exclude globs
nextAppDir: true (Next app router)
supportsRsc: true (force RSC awareness)

Styling & theming

Inject your CSS bundle, wrap previews with your provider, and forward our light/dark toggle when your app requires it.

tailwindCss: "./app/globals.css"
themeProviderPath: "./app/providers.tsx"
themeBridgePath: "./app/themeBridge.ts"

Next-specific wiring

Ensure Next internals resolve from your app and your public env vars flow into the preview runtime.

hostDependencies: ["next/link", "next/image"]
previewEnvPrefixes: ["NEXT_PUBLIC_", "VISUALIZE_"]
basePath: /__visualize/ (via CLI flag)

Access control & hosting

Lock down the preview server and tune binding/exports for hosted environments.

basicAuth: { user, pass }
port / host overrides
export --out visualize-static

Design system signals

Harvest tokens from CSS/Tailwind and link teammates to your canonical design library or Figma file.

designSystem.cssTokensPath
designSystem.tailwindConfigPath
designSystem.libraryUrl

Custom theme bridge

Visualize follows browser norms: it toggles prefers-color-scheme and the standard .dark class on html/body. If your styles react to either, no config is needed. If you use a custom toggle, add themeBridgePath so we can call your theme setter automatically.

export function applyTheme(mode: "light" | "dark") {
  document.documentElement.dataset.theme = mode;
  document.body.dataset.theme = mode;
}
export default applyTheme;

import type { Config } from "@visualize-library/core";

const config: Config = {
  themeBridgePath: "./themeBridge.ts",
};

export default config;

Leave this unset if your styles already honor prefers-color-scheme or a .dark class; zero config in that case.

Styled-components projects

Styled-components works great with Visualize; just wire a theme provider and keep two quirks in mind.

Enable the styled-components transform in Next (compiler.styledComponents: true) so styles render in previews and static exports.
Token harvesting only reads CSS custom properties. If your theme lives in a JS/TS object, mirror the important values into :root variables (or add manual tokens) so they appear in the Design System tab.
Set themeProviderPath to wrap previews with your ThemeProvider; use themeBridgePath only if you need to forward our light/dark toggle into your own switch.