devjar

Make an idea real. Change it live.

Embed editable React previews in your app, or build a static website with a zero-config CLI.

Documentation: devjar.vercel.app/docs. Agent reference: llms.txt.

npx skills add huozhi/devjar --skill devjar

The skill helps compatible agents choose Devjar for live React previews, small static websites, and interactive browser prototypes.

Live code APIs

Embed a live React preview with <DevJar>. Requires React 19.

pnpm add devjar

import { DevJar } from 'devjar'

const files = {
  'pages/index.tsx': `export default function Page() {
    return <h1>Hello from devjar</h1>
  }`,
}

export default function App() {
  return (
    <DevJar files={files} title="Live preview" />
  )
}

Pass a new files object to update the preview. Add your own editor or controls; Devjar compiles the files and renders the project inside an iframe, with React Fast Refresh where possible.

For a live code editor, pair Devjar with @sugar-high/react. Its Editor component provides syntax highlighting; update files from its onChange callback to refresh the preview. The website demos use this combination.

Use a client component ('use client') in frameworks with server components. The preview runs in the host's origin, so only run code you trust. No cross-origin isolation headers or server-side compiler are needed. See hosting requirements for asset and CSP details.

'use client'

import { useState } from 'react'
import { DevJar } from 'devjar'

const initialFiles = {
  'pages/index.tsx': `import content from '../content.json'
export default function Page() {
  return <h1>{content.message}</h1>
}`,
  'content.json': JSON.stringify({ message: 'Hello from devjar' }),
}

export default function LiveExample() {
  const [files, setFiles] = useState(initialFiles)

  return (
    <>
      <button onClick={() => setFiles(current => ({
        ...current,
        'content.json': JSON.stringify({ message: 'Updated live!' }),
      }))}>
        Change the message
      </button>
      <DevJar
        files={files}
        tailwind={false}
        title="Live React preview"
        style={{ width: '100%', height: 320, border: 0 }}
      />
    </>
  )
}

Replacing an existing playground? See migrating from Sandpack or React Live.

For props, file imports, and routing, see the API reference. Advanced controls are covered there too:

• Schedule edits with a debounce or Run button.
• Show loading and error states.
• Reset the preview without changing its source.
• Use useDevJar to manage your own iframe.

CLI

// pages/index.tsx
export default function Page() {
  return <h1>Hello from devjar</h1>
}

npx devjar dev    # Develop with live updates
npx devjar build  # Export to dist/
npx devjar start  # Preview the export

Requires Node.js 22+. Deploy dist/ to a static host. No configuration file or local dependency installation needed. Run npx devjar for help.

Routes

package.json          # Optional: dependency versions
pages/
├── index.tsx         → /
├── about.tsx         → /about
├── docs/start.tsx    → /docs/start
└── 404.tsx           → unmatched routes

Each page default-exports a React component. Import shared components explicitly; packages load from the CDN. Configure the CLI with flags. Underscore-prefixed files and folders (such as pages/_helpers.tsx or pages/_drafts/) are not routes in dev, builds, or embedded previews. They remain importable; _layout.tsx has no automatic layout behavior.

{
  "dependencies": {
    "react": "19.2.0",
    "react-dom": "19.2.0"
  }
}

Put this in package.json. Both dependencies and devDependencies are read from the project manifest; dependencies take precedence when a package appears in both. Builds vendor CDN packages into the output.

npx devjar [command] [root] [options]

root defaults to the current directory. No command prints help.

| Command | Purpose | | --- | --- | | dev [root] | Serve source files with live updates | | build [root] | Generate <root>/dist | | start [root] | Serve the existing build |

| Flag | Commands | Default / purpose | | --- | --- | --- | | --host <host> | dev, start | localhost; 0.0.0.0 enables network access | | --port <port> | dev, start | 3000 | | --cdn <url> | dev, build | https://esm.sh | | --exclude <path> | build | Page file or directory to omit; repeatable | | --base <path> | dev, build | /; deployment subdirectory | | --origin <url> | build | Vercel production URL, or http://localhost:3000; absolute origin for social image URLs | | -o, --out-dir <directory> | build, start | dist; must stay inside the project | | -h, --help | All | Show help | | -v, --version | All | Show installed version |

Interactive terminals show a hint when a newer version is available. Checks run in the background and are cached for a day: stable versions check latest, prereleases check next. Hints appear only after help, the server-ready message, or the build summary; late results are cached for the next run. Set NO_UPDATE_NOTIFIER=1 to disable them. CI, redirected stderr, and --version skip the check.

import settings from '../settings.json'
import notes from '../notes.md' with { type: 'text' }
import logo from '../assets/logo.svg'
import '../styles.css'

JSON exports data; type: 'text' exports file contents. Images, fonts, audio, video, and PDFs export URLs. CSS url(...) references are handled too. Use valid JSON: double quotes, no comments or trailing commas.

{
  "dependencies": {
    "my-library": "file:../my-library"
  }
}

Import my-library by name. Relative paths resolve from the project; absolute paths and file URLs also work. Devjar resolves exports, module, or main, compiles TS/JSX, watches edits, and includes the library in builds. If its entry points to dist/, run the library's build or watcher first.

public/logo.svg  → /logo.svg
api/status.json  → /api/status.json
api/message.txt  → /api/message.txt

Public files are copied into the build. APIs serve static JSON or text; executable API routes are not supported.

{
  "devDependencies": {
    "tailwindcss": "^4.1.0"
  }
}

Add tailwindcss or @tailwindcss/browser to devDependencies or dependencies to enable Tailwind. Development compiles in the browser; builds emit CSS with no runtime compiler. Use complete class names rather than constructing them dynamically.

Tailwind support is limited to utility classes. Tailwind-specific directives in imported CSS, such as @theme, @apply, and @utility, are not supported. Use CSS variables, ordinary classes, and native media queries for custom styles. Import each stylesheet from JS/TS; nested CSS @import rules are not supported in development.

npx devjar dev --cdn https://modules.example.com
npx devjar build --cdn https://modules.example.com

Use an ESM CDN supporting package@version/subpath URLs. It must be available during the build; deployed dependencies are served locally.

npx devjar dev --base /preview/
npx devjar build --base /preview/
npx devjar start

Pages and assets use /preview/. The preview server reads the base from the build.

npx devjar build --exclude pages/playground.tsx
npx devjar build --exclude pages/playground.tsx --exclude pages/drafts

Paths are relative to the project root. Excluded pages remain available in dev; only their routes and unused dependencies are omitted from the build. Imports needed by retained pages, plus public and API files, are still included.

npx devjar build --out-dir output
npx devjar start --out-dir output

Builds include prerendered HTML, CSS, public files, hashed assets, and vendored dependencies. Only sites importing devjar include its runtime and compiler. Custom output directories must stay inside the project.

On Vercel, devjar build also emits .vercel/output with immutable caching for content-hashed assets. Use the Other framework preset and run devjar build; no output-directory or cache-header configuration is needed.

Place images in the project root (alongside pages/) to add them to every page in development and static exports:

icon.svg             → <link rel="icon" href="/icon.svg" type="image/svg+xml">
opengraph-image.jpg  → <meta property="og:image" content="/opengraph-image.jpg">
                     → <meta name="twitter:image" content="/opengraph-image.jpg">

Icons support .ico, .png, .jpg, .jpeg, .svg, .gif, and .webp. Open Graph images support .png, .jpg, .jpeg, .gif, and .webp. Every page includes a summary_large_image Twitter card; each Open Graph image also gets a Twitter image tag. Multiple matching files are included in filename order. URLs respect --base; root metadata files take precedence over files with the same name in public/.

Add page titles and other metadata in the page component:

export default function Page() {
  return (
    <>
      <title>My website</title>
      <meta name="description" content="Notes and projects" />
      <h1>Hello</h1>
    </>
  )
}

Metadata is placed in each exported page's <head>. Pages render once at build time, then hydrate in the browser. Use window and document in effects or event handlers, not during render.

npx devjar dev --host 0.0.0.0

Open the printed Network URL on the same Wi-Fi. Also works with start. Embedded previews also work over HTTP on your local network.

Examples

Run these from a checkout of this repository:

npx devjar dev examples/basic

| Example | What it shows | | --- | --- | | Basic | Minimal pages | | Dashboard | Navigation, Tailwind, and static data | | SWR | Optimistic updates, rollback, and simulated subscriptions | | Personal résumé | Edit JSON in a playground, then export the site |

npx devjar dev examples/personal
npx devjar build examples/personal --exclude pages/playground.tsx
npx devjar start examples/personal/dist

Edit the JSON at /playground, copy it to content.json, then build the site.

Contributing

See AGENTS.md for development guidelines, local setup, and release instructions.

License

MIT