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.

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.

Example: update JSON content with React state

'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.

Pin dependency versions

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

Put this in package.json. Only dependencies and devDependencies are read from the project manifest. Builds vendor CDN packages into the output.

All commands and flags

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
-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.

JSON, text, CSS, and assets

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.

Local package development

{
  "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 files and static APIs

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.

Tailwind CSS

{
  "dependencies": {
    "tailwindcss": "^4.1.0"
  }
}

Add tailwindcss or @tailwindcss/browser 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.

Custom module CDN

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.

Deploy under a base path

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.

Exclude development pages from export

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.

Build output

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.

Page metadata and prerendering

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.

Preview on your phone

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

Export the personal website without its playground

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