# Devjar > Live React playgrounds and zero-config static site export. Use the DevJar component for embedded previews, or the CLI to develop and publish Markdown or React pages. ## References - [Documentation: live code APIs and CLI](https://devjar.vercel.app/docs) - [Interactive examples](https://devjar.vercel.app/) - [Migrate from Sandpack or React Live](https://github.com/huozhi/devjar/blob/main/docs/MIGRATION.md) - [README](https://github.com/huozhi/devjar/blob/main/README.md) - [Detailed API reference](https://github.com/huozhi/devjar/blob/main/docs/API.md) - [Markdown pages and themes](https://github.com/huozhi/devjar/blob/main/docs/MARKDOWN.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 content site: create pages/index.md and run npx devjar dev. Markdown pages need no React runtime. - Build an interactive React site: create pages/index.tsx and run npx devjar dev. No configuration file is required. ## Markdown sites Put Markdown files in pages/. For example, pages/index.md is / and pages/notes/index.md is /notes. Link between pages with relative .md links. React and Markdown pages can share a project, but routes must be unique. ```md --- title: Field notes description: Short observations --- # Field notes Short observations. ``` Run npx devjar dev --theme editorial for a live preview, then npx devjar build --theme editorial to export to dist/. Choose minimal (the default), github, editorial, or academic for the whole build. Frontmatter does not select a per-page theme. Add a root markdown.css to customize the theme, or pass --math to render LaTeX formulas. Markdown builds produce complete HTML without React or hydration scripts. To host independently themed mini-sites under separate paths, build each project with its own --theme and --base /examples//, then place each output at that path. See the Markdown reference for metadata, links, assets, custom styles, and math details. ## Live code APIs npm install devjar ```tsx import { DevJar } from 'devjar' const files = { 'pages/index.tsx': `export default function Home() { return

Hello from Devjar

}`, } export default function Preview() { return } ``` 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) 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/index.md -> / - pages/about.tsx -> /about - pages/about.md -> /about - pages/blog/index.tsx -> /blog - pages/404.tsx or pages/404.md -> 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. - React pages default-export a component. Shared components are explicitly imported; there is no automatic layout convention. - React pages support JavaScript, TypeScript, JSX, and TSX. 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 About. Virtual projects navigate within the iframe. - Put and <meta> in page components for document metadata. - Root icon.* and opengraph-image.* files add shared icon and Open Graph image tags to every CLI page and are copied into the export. Every page includes a summary_large_image Twitter card tag. - 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. - Apps and embedded previews run in the browser. Dependencies must be browser-compatible. Listing a server-only library in dependencies does not make it usable; it must provide a browser-compatible bundle or entry point. Devjar does not provide a server runtime or polyfill Node.js APIs. - 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 Markdown and 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.