# Devjar

> Live React playgrounds and zero-config static site export. Use the DevJar component for embedded previews, or the CLI to develop and publish a folder of React pages.

## References

- [Migrate from Sandpack or React Live](https://github.com/huozhi/devjar/blob/main/docs/MIGRATION.md)
- [README and API reference](https://github.com/huozhi/devjar/blob/main/README.md)
- [Personal site: playground to static export](https://github.com/huozhi/devjar/tree/main/examples/personal)
- [Minimal website](https://github.com/huozhi/devjar/tree/main/examples/basic)
- [Dashboard](https://github.com/huozhi/devjar/tree/main/examples/dashboard)
- [Source and issues](https://github.com/huozhi/devjar)

## Choose an entry point

- Embed editable code in an app or documentation: install devjar, import DevJar, and pass files as strings.
- Advanced API for owning an iframe: import useDevJar and use its ref, load(files), and error.
- Build a website: create pages/index.tsx and run npx devjar dev. No configuration file is required.

## Live code APIs

npm install devjar

```tsx
import { DevJar } from 'devjar'

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

export default function Preview() {
  return <DevJar files={files} tailwind={false} title="Live preview" />
}
```

To update a preview, replace the edited file's string in a new files object.
Keep files and custom resolver functions stable between unrelated renders.
DevJar reloads current files when options change. Changing transform/compiler URLs
invalidates compiled-source caches; changing dependencies, resolveModule, or
tailwind recreates the iframe runtime and resets its state. Equal dependency and
compiler values do not reload just because their options objects are recreated.
With useDevJar, call load again after options change, or include files and load
in the dependencies of the effect that performs automatic loading.
Updates start immediately, with one active load and only the newest pending edit.
Superseded queued edits are skipped; running compilation/imports finish and stale
results are discarded. This cannot undo module side effects. Incomplete source
reports an error while keeping the last successful preview. Debounce in the host
if desired; load() promises resolve on completion or supersession, with failures
reported through error/onError and status.
DevJar accepts ordinary iframe props and a ref. Relevant options include
onError, onStatusChange, dependencies (package versions), resolveModule (an ESM URL resolver),
tailwind (defaults to true), transform (defaults to true), and compiler
({ workerUrl, bindingUrl, wasmUrl }) for a complete asset URL override.

Prefer DevJar for managed previews. The advanced useDevJar hook returns
{ ref, load, error, status, reset }. Attach ref to an iframe and call
load(files) when the project should run. load returns a promise.
status (or the component's onStatusChange) reports idle, compiling, loading,
ready, or failed. ready means React committed, not that application data is loaded.
Call reset() on the hook or pass apiRef (React.Ref<DevJarHandle>) to DevJar and
call apiRef.current.reset() to restart the current files in a fresh iframe realm.
Reset runs React effect cleanup and clears React state, module instances, and
iframe globals. It preserves the iframe element/ref, source files, browser caches,
and origin storage. It does not restore the editor's initial source.
onError reports compilation, module loading, React render errors, uncaught iframe
errors, and unhandled rejections. A new load clears the previous error.

Embedded previews compile in a browser worker using non-shared WebAssembly.
No cross-origin isolation headers or server-side compiler are required.
Bundlers discover the worker, binding, and WASM through static asset URLs.
Next.js hosts only need a Client Component; no asset copy or resolver patch.
An explicit compiler option bypasses default asset discovery completely.

## CLI

```sh
npx devjar                 # Show help
npx devjar dev             # Develop the current folder
npx devjar build           # Export to dist/
npx devjar build --exclude pages/playground.tsx  # Omit a development-only page
npx devjar start           # Serve the export
npx devjar dev my-site     # Use another project folder
npx devjar dev --host 0.0.0.0  # Preview on another device
```

Requires Node.js 22 or newer. Use --help for flags. Do not create a Devjar
configuration file or a devjar field in package.json. User settings are CLI flags.

## Files and imports

- pages/index.tsx -> /
- pages/about.tsx -> /about
- pages/blog/index.tsx -> /blog
- pages/404.tsx -> custom not-found page
- Underscore-prefixed files and folders inside pages/ are private: they are not routes in dev, builds, or embedded previews, but remain importable.
- Every page default-exports a React component. Shared components are explicitly imported; there is no automatic layout convention.
- JavaScript, TypeScript, JSX, and TSX are supported. Use relative imports for local modules and CSS.
- JSON imports provide a default export. JSON must be valid (double quotes; no comments or trailing commas).
- Any local file can be imported as a string: import text from './notes.md' with { type: 'text' }.
- Text imports work in the live runtime and CLI. They are explicit; shader extensions have no special behavior.
- Use normal anchors such as <a href="/about">About</a>. Virtual projects navigate within the iframe.
- Put <title> and <meta> in page components for document metadata.
- An optional package.json supplies dependencies and devDependencies for CDN versions or local package paths. CDN dependencies need no local install.
- Keep React and React DOM versions compatible across the parent app and preview.
- In the CLI, public/ files are served from the root. Imported image, font, audio, video, and PDF files export asset URLs.
- The virtual files map holds source strings; it does not provide the CLI's public directory or binary-asset pipeline.

## Static export

Use build --exclude <path> to omit a page file or directory from export. Paths
are project-relative and the flag can be repeated. Dev routes are unaffected;
shared imports needed by retained pages, public files, and API files remain.

The build prerenders route HTML, bundles the project modules, and vendors
runtime dependencies into dist/. Deploy dist/ to a static host. It needs no
Node.js server after export. A site that embeds DevJar still needs the browser
compiler assets listed above.

For the personal-site example, run npx devjar dev from its directory. /playground reads the same source files as the real website. Copy the
edited content.json back to disk, build, and preview the exported result.

## Scope and version

This reference tracks the main branch. Check the README and installed CLI's
--help for the version in use; main may include features not yet published.
Devjar is a React static-site builder and live-code runtime, not a full-stack
framework. Do not assume server actions, dynamic server routes, or automatic
layouts. Never put secrets in preview files, browser code, or exported assets.