Documentation

Render a project with DevJar

Pass your files as strings to files. Devjar runs them in an iframe and updates when they change.

import { DevJar } from 'devjar'const files = {  'pages/index.tsx': `export default function Page() {    return <h1>Hello from devjar</h1>  }`,}function Preview() {  return (    <DevJar files={files} title="Live preview" />  )}

Requires React 19+. Install with npm install devjar. No special hosting headers needed.

Need an editor? Use the Editor from @sugar-high/react. Update files in its onChange to refresh the preview.

Example: edit in a playground, then export the site →

Advanced API: control your own iframe

Use useDevJar to render into your own iframe and choose when code runs.

import { useDevJar } from 'devjar'function Preview({ files }) {  const { ref, load, error } = useDevJar({ tailwind: false })  return (    <>      <button onClick={() => void load(files)}>Run</button>      {error != null && <pre>{String(error)}</pre>}      <iframe ref={ref} title="Live preview" />    </>  )}

Routes from files

Each file in pages/ becomes a route.

Packages load from a CDN, so there is nothing to install. Pin versions in an optional package.json.

package.json          # optional: dependency versionspages/├── index.tsx         → /├── about.tsx         → /about├── docs/start.tsx    → /docs/start└── 404.tsx           → unmatched routes

Files and folders starting with _ are not routes. You can still import them.

Markdown pages

Put .md files in pages/. They build to plain HTML with no JavaScript. Pick a theme with --theme: minimal, github, editorial, or academic. Add --math for LaTeX.

npx devjar dev --theme editorialnpx devjar build --theme editorial --math

Compare themes · Markdown guide

Tailwind CSS

Add tailwindcss or @tailwindcss/browser to your dependencies. Builds output plain CSS. Write full class names, not ones built from strings.

Only utility classes work. @theme, @apply, and @utility are not supported. For custom styles, use CSS variables and plain classes. Import each stylesheet from JS/TS, not with CSS @import.

Imports 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 imports as data. type: 'text' imports as a string. Images, fonts, media, and PDFs import as URLs.

Public files and static APIs

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

Files in public/ are copied as is. api/ serves static JSON or text only.

Page metadata

Add an icon and a share image to the project root. Devjar adds them to every page. No code needed.

icon.svg              # browser tab and bookmark iconopengraph-image.png    # link preview imagepages/└── index.tsx

Devjar adds these tags to each page:

<link rel="icon" href="/icon.svg" type="image/svg+xml"><meta property="og:image" content="https://example.com/opengraph-image.png"><meta name="twitter:image" content="https://example.com/opengraph-image.png"><meta name="twitter:card" content="summary_large_image">

Links then show a large image on X, Slack, Discord, LinkedIn, Facebook, iMessage, WhatsApp, and Telegram. Use a 1200 × 630 image.

Build with --origin set to your site URL, so image links are absolute. Without it, Devjar uses your Vercel URL or http://localhost:3000.

Set each page’s title and description in the page itself:

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

Include the og: tags. Some platforms, like X, ignore <title>. Markdown pages take their title and description from frontmatter.

Sitemap

Add --sitemap to build to write sitemap.xml. Set --origin to your site URL.

npx devjar build --origin https://example.com --sitemapnpx devjar build --origin https://example.com --base /blog/ --sitemap=site-map.xml

It lists every built page except 404 and excluded pages. A custom filename must end in .xml.

Base path

Use --base to host the site in a subdirectory. Pass it to both dev and build.

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

Exclude pages

Leave drafts or playgrounds out of the build. They still work in dev. Repeat the flag for more paths.

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

Local packages

Point a dependency at a local folder. Devjar compiles it, watches for edits, and bundles it in builds.

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

Static output for any host

Every page is prerendered to HTML, with all dependencies included. Deploy dist/ to any static host.

On Vercel, choose the Other preset. Caching is set up for you.