# artifact.land

> A publishing platform for self-contained interactive artifacts.
> Upload an HTML or JSX file, get a URL. No build tools, no deployment.

artifact.land hosts self-contained interactive artifacts — tools, visualizations, explanations, creative pieces, prototypes, and anything else that runs in a browser from a single file. Artifacts are created externally (in Claude, Cursor, VS Code, or by hand) and published here.

---

# Overview

artifact.land is a publishing platform for self-contained interactive artifacts. Makers upload an entry HTML or JSX file (plus optional images in `assets/`), and it gets a permanent URL that anyone can visit and interact with. No build tools, no deployment process, no server needed.

## What is an artifact?

An artifact is a self-contained interactive thing that runs in a browser. It could be:

- **A useful tool** — a color picker, regex tester, unit converter, ffmpeg command generator, mortgage calculator
- **A data visualization** — an interactive chart, model explorer, financial dashboard, scenario simulator
- **An interactive explanation** — a concept made tangible with sliders, animations, and explorable examples
- **A creative piece** — generative art, interactive fiction, a music toy, a visual experiment
- **A prototype** — a UI concept, a game mechanic, an interaction pattern
- **Anything else** that's interactive and self-contained in a small bundle of files

There is no prescribed style or genre. If it does something interesting when you open it in a browser, it belongs on artifact.land.

## Single file or small bundle

An artifact is one entry file (`index.html` or `index.jsx`) plus any images it references, packaged together. The two shapes:

- **Single file** — just an entry file, no separate assets. All content inline (base64 data URIs, embedded SVG, CDN scripts). This is what Claude artifact exports look like.
- **Bundle** — an entry file at the root plus images under an `assets/` directory. Reference them with normal relative URLs (`<img src="assets/hero.jpg">`); they're served from the same origin as the entry, so no CORS, no signed URLs in the markup.

Bundles travel over the wire as a single zip file (the CLI and web upload form both build the zip for you). The server unpacks, validates, and serves each file at its bundle-relative path.

See [HTML Artifacts](https://artifact.land/docs/llms/html-artifacts) for the canonical bundle structure and reference patterns.

## Two publishing paths

### JSX path (easiest for React components)

Write a React component with standard imports. artifact.land transpiles JSX, resolves imports to a pre-configured runtime (React 18, Tailwind CSS, and a curated library set), and wraps everything in an HTML shell that renders your component.

This is designed so that **Claude artifact exports work with zero modification** — copy the JSX, upload it, publish.

**Use the JSX path when:**
- You're writing a React component
- The libraries you need are in the supported set (React, Recharts, D3, Three.js, Lucide, etc.)
- You want the simplest possible publishing flow

See [JSX Runtime](https://artifact.land/docs/llms/jsx-runtime) for the full library list and details.

### HTML path (full control)

Upload a complete `.html` file. It's served exactly as-is — no compilation, no modification, no wrapping. Use any framework, any CDN libraries, any approach.

**Use the HTML path when:**
- You need libraries outside the JSX runtime's supported set
- You're not using React (vanilla JS, Vue, Svelte, Preact, Alpine, etc.)
- You want full control over the document structure
- You're bundling a more complex project into a single file

See [HTML Artifacts](https://artifact.land/docs/llms/html-artifacts) for details and allowed CDN domains.

## Key constraints

All artifacts run in a **sandboxed iframe** on a per-artifact subdomain. Each artifact gets its own unique origin, isolated from the main app and from every other artifact. Key limits:

- **No network requests** — `fetch()`, `XMLHttpRequest`, and WebSocket are all blocked
- **No external images** — `img-src 'self' data: blob:` blocks remote image URLs; bundle the image instead
- **No parent navigation** — cannot redirect the parent page (but `target="_blank"` links and popups open in a new tab normally)
- **Bundle caps** — Free tier: 5 MB / 50 files. Pro tier: 25 MB / 200 files.
- **Entry file types** — `.html` or `.jsx`
- **Bundled asset types** — raster images only for v1 (`.png`, `.jpg`, `.jpeg`, `.gif`, `.webp`, `.avif`). Fonts, audio, and data files are inline-only for now (base64 / inline JSON still works in the entry file).

Each artifact has its own subdomain origin, so `localStorage`, `sessionStorage`, `IndexedDB`, and cookies all work and are scoped to that one artifact. There's no cloud sync — storage is per-device, per-browser.

See [Constraints](https://artifact.land/docs/llms/constraints) for the full list of what's blocked and what works.


---

# JSX Runtime Reference

When you upload a `.jsx` file to artifact.land, it's compiled into a self-contained HTML page using a pre-configured runtime. This is designed so that Claude artifact exports and similar React components work with zero modification.

## How compilation works

1. You write a `.jsx` file with standard React imports
2. artifact.land transpiles JSX to JavaScript using SWC
3. `import` statements for known libraries are replaced with CDN-loaded globals
4. Named imports (e.g., `{ useState }` from `"react"`) are destructured from the library global
5. The code is wrapped in an HTML shell with `<div id="root">`
6. Your default export is auto-detected and rendered into `#root`

## Available libraries

| Library | Version | Import | Global |
|---------|---------|--------|--------|
| react | 18.3.1 | `react` | `React` |
| react-dom | 18.3.1 | `react-dom` | `ReactDOM` |
| recharts | 2.12.7 | `recharts` | `Recharts` |
| d3 | 7.9.0 | `d3` | `d3` |
| lucide-react |  | `lucide-react` | `lucideReact` |
| three | r128 | `three` | `THREE` |
| lodash | 4.17.21 | `lodash` | `_` |
| chart.js | 4.4.1 | `chart.js` | `Chart` |
| tone | 14.7.77 | `tone` | `Tone` |
| papaparse | 5.4.1 | `papaparse` | `Papa` |
| mathjs | 12.4.0 | `mathjs` | `math` |

**Tailwind CSS** is always included via the Play CDN (`https://cdn.tailwindcss.com`). All utility classes are available.

## Component mounting

Your component is automatically mounted into `<div id="root">`. The runtime detects your component in this order:

1. The name of your `export default` (whatever you named it)
2. `App`
3. `Main`
4. `Component`
5. `Dashboard`

## Minimal example

```jsx
import React, { useState } from "react";

export default function App() {
  const [count, setCount] = useState(0);
  return (
    <div className="min-h-screen flex items-center justify-center bg-gray-50">
      <div className="text-center p-8">
        <h1 className="text-4xl font-bold mb-4">Count: {count}</h1>
        <button
          className="px-6 py-3 bg-blue-500 text-white rounded-lg hover:bg-blue-600"
          onClick={() => setCount(c => c + 1)}
        >
          Increment
        </button>
      </div>
    </div>
  );
}
```

## Using additional libraries

Import supported libraries as you normally would:

```jsx
import React from "react";
import { BarChart, Bar, XAxis, YAxis, Tooltip, ResponsiveContainer } from "recharts";

const data = [
  { name: "Jan", value: 400 },
  { name: "Feb", value: 300 },
  { name: "Mar", value: 600 },
  { name: "Apr", value: 800 },
];

export default function App() {
  return (
    <div className="p-8">
      <h1 className="text-2xl font-bold mb-4">Monthly Data</h1>
      <ResponsiveContainer width="100%" height={400}>
        <BarChart data={data}>
          <XAxis dataKey="name" />
          <YAxis />
          <Tooltip />
          <Bar dataKey="value" fill="#3b82f6" />
        </BarChart>
      </ResponsiveContainer>
    </div>
  );
}
```

## Unsupported imports

If your JSX file imports a library not in the supported list, artifact.land returns an error at publish time:

> Unknown import(s): some-library. artifact.land supports these libraries: [list]. For other libraries, bundle your code as a self-contained HTML file.

For libraries outside the supported set, use the HTML path instead and load them from a CDN or inline the code.


---

# HTML Artifacts

Upload a `.html` file and it's served exactly as-is. No compilation, no modification, no wrapping. You have full control over the document.

The entry file can stand alone (everything inline), or it can be paired with images in an `assets/` directory and shipped as a bundle. Either shape works for the HTML path.

## When to use HTML

- You need libraries outside the JSX runtime's supported set
- You're not using React (vanilla JS, Vue, Svelte, Preact, Alpine, etc.)
- You want full control over the HTML structure and `<head>` contents
- You're packaging a more complex project into a single file using a build tool

## Bundle structure

A bundle is one entry file at the root plus any images it references under `assets/`:

```
my-artifact/
├── index.html         ← entry file (HTML or JSX) at the root
└── assets/
    ├── hero.jpg
    ├── thumbnail.png
    └── icons/
        └── star.webp
```

Nested subdirectories under `assets/` are fine. Anything outside this shape (a file at the root that isn't the entry, an asset above `assets/`) is rejected at upload time.

Reference assets with normal relative URLs — each artifact lives on its own subdomain, so bundled files are same-origin with the entry:

```html
<img src="assets/hero.jpg">
<source srcset="assets/photo-2x.webp 2x, assets/photo.webp 1x">
```

CSS `background: url(assets/...)` and `<a href="assets/file.png">` work too — same-origin, no CORS, no signed-URL gymnastics in your markup. (CSS files themselves can't be bundled in v1; inline your `<style>` block in the entry file.)

**Allowed bundled file types (v1):** raster images only — `.png`, `.jpg` / `.jpeg`, `.gif`, `.webp`, `.avif`. Each file's magic bytes are validated against its extension at upload (a `.png` whose contents aren't actually a PNG is rejected). Fonts, audio, data files, SVG, and video are deferred — inline them in the entry file (`@font-face` with base64, inline `<svg>`, inline JSON in a `<script type="application/json">`, etc.).

**Bundle caps:**

| Tier | Total bundle size | File count |
|---|---|---|
| Free | 5 MB | 50 files |
| Pro | 25 MB | 200 files |

The cap applies to the post owner — if a free user forks a Pro user's bundle that fits within 5 MB, the fork is fine; if the bundle is 12 MB, the fork fails until they upgrade or trim.

Lint a bundle before uploading with `aland validate <directory>` — it checks structure, file types, reference integrity (every `src=`, `href=`, `url(…)` in the entry resolves to a file in the bundle), and warns on oversized images. `aland push` runs validate automatically as the first step.

## Allowed CDN domains

Artifacts are served with a Content Security Policy that allows scripts, styles, and fonts from these hosts:

| CDN | Domain | Use for |
|-----|--------|---------|
| CDNJS | `https://cdnjs.cloudflare.com` | Most JavaScript libraries |
| Tailwind | `https://cdn.tailwindcss.com` | Tailwind CSS Play CDN |
| unpkg | `https://unpkg.com` | npm packages served as UMD/ESM |
| Google Fonts | `https://fonts.googleapis.com` | Font stylesheets |
| Google Fonts | `https://fonts.gstatic.com` | Font files (woff2) |

Scripts and styles loaded from other domains will be blocked by CSP. If you need a library that isn't available on these CDNs, inline the code directly in your HTML file.

## Minimal example

```html
<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <title>My Artifact</title>
  <script src="https://cdn.tailwindcss.com"></script>
  <style>
    body { margin: 0; min-height: 100vh; }
  </style>
</head>
<body class="bg-gray-50 flex items-center justify-center min-h-screen">
  <div class="text-center p-8">
    <h1 class="text-4xl font-bold mb-4">Hello, artifact.land</h1>
    <p class="text-gray-600 mb-6">A self-contained HTML artifact.</p>
    <button
      class="px-6 py-3 bg-blue-500 text-white rounded-lg hover:bg-blue-600"
      onclick="this.textContent = 'Clicked!'"
    >
      Click me
    </button>
  </div>
</body>
</html>
```

## Example with a CDN library (D3)

```html
<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <script src="https://cdnjs.cloudflare.com/ajax/libs/d3/7.9.0/d3.min.js"></script>
  <style>
    body { margin: 0; display: flex; justify-content: center; padding: 2rem; }
    svg { max-width: 100%; height: auto; }
  </style>
</head>
<body>
  <div id="chart"></div>
  <script>
    const data = [30, 80, 45, 60, 20, 90, 55];
    const svg = d3.select("#chart").append("svg")
      .attr("width", 400).attr("height", 200);
    svg.selectAll("rect").data(data).join("rect")
      .attr("x", (d, i) => i * 55)
      .attr("y", d => 200 - d * 2)
      .attr("width", 45)
      .attr("height", d => d * 2)
      .attr("fill", "steelblue");
  </script>
</body>
</html>
```

## Tips

- **Set the viewport meta tag** — `<meta name="viewport" content="width=device-width, initial-scale=1">` ensures proper scaling on mobile
- **Style the body** — set `margin: 0` and `min-height: 100vh` for full-bleed layouts
- **Use `<script type="module">`** for modern JavaScript (top-level await, import/export between inline modules)
- **Embed data inline** — since `fetch()` is blocked, put data directly in the file (JSON in a `<script>` tag, JavaScript constants, data attributes)
- **Be responsive** — the iframe can be any width, from mobile to desktop
- **Inline large dependencies** if they're not on an allowed CDN — copy-paste minified library code into a `<script>` tag (stays under the bundle cap)
- **Bundle images instead of base64'ing them** when you have more than a couple — base64 inflates by ~33% and bloats the entry file; bundled assets compress better at the network layer and are reusable across views in the same artifact
- **Compress images before uploading** — `cwebp -q 80 hero.png -o hero.webp`, ImageOptim, or squoosh.app. `aland validate` warns on any image over 500 KB.


---

# Artifact Constraints

All artifacts run in a sandboxed iframe on a per-artifact subdomain of `artifactlandcdn.com` (each artifact gets its own unique origin), isolated from the main application AND from every other artifact. This provides strong security but imposes constraints on what artifacts can do.

## File limits

| Constraint | Free | Pro |
|-----------|------|-----|
| Bundle size | 5 MB | 25 MB |
| Files per bundle | 50 | 200 |

| Constraint | Limit |
|-----------|-------|
| Entry file types | `.html` or `.jsx` |
| Bundled asset types | `.png`, `.jpg` / `.jpeg`, `.gif`, `.webp`, `.avif` |

Caps apply to the post owner, not the uploader — if a free user forks a Pro user's bundle, the cap that matters is the **free** cap on the new fork. The original Pro-sized bundle keeps working on the original post.

## Bundle structure + assets

An artifact can be a single file or a small bundle of files. The canonical bundle shape:

```
my-artifact/
├── index.html         ← entry file (HTML or JSX) at the root
└── assets/
    ├── hero.jpg
    ├── thumbnail.png
    └── icons/
        └── star.webp
```

Rules enforced at upload time:

- **Entry file at the root.** `index.html` if present, else `index.jsx`, else the single HTML/JSX file in the bundle.
- **Everything else lives under `assets/`.** Nested subdirectories are fine (`assets/photos/hero.jpg`, `assets/icons/star.png`). Anything outside this shape is rejected.
- **Raster images only for v1.** PNG, JPG, GIF, WebP, AVIF. Each file's magic bytes are validated against its extension — the "PNG that's actually HTML" polyglot attack is rejected.
- **Path traversal is blocked.** Any entry whose normalized path contains `..`, starts with `/`, or is a symlink → bundle rejected.

Reference bundled assets with normal relative URLs in the entry file — each artifact has its own subdomain, so bundled files are **same-origin** with the entry. No CORS, no signed URLs in your markup:

```html
<img src="assets/hero.jpg">
```

CSS `background: url(assets/...)`, `<source srcset="assets/...">`, and `<a href="assets/file.png">` all work the same way.

**Deferred to follow-up epics** (currently inline-only): SVG (inline `<svg>` in the entry file still works), fonts (use `@font-face` with base64), audio, data files (use inline `<script type="application/json">`), video. The no-network rule below still applies — external image / font / data URLs are blocked at runtime regardless of bundling.

## Sandbox restrictions

The iframe uses `sandbox="allow-scripts allow-downloads allow-popups allow-popups-to-escape-sandbox allow-same-origin"`. `allow-same-origin` is safe because each artifact has a unique subdomain — no two artifacts can read each other's storage.

| Blocked | Details |
|---------|---------|
| Network requests | `fetch()`, `XMLHttpRequest`, WebSocket, and `navigator.sendBeacon()` are all blocked by `connect-src: 'none'` |
| Top navigation | Cannot navigate or redirect the parent page (no `allow-top-navigation`) |
| Forms to external URLs | Form submissions to external endpoints are blocked |
| Geolocation | Blocked by `Permissions-Policy` |
| External images | `img-src` is restricted to `'self' data: blob:` — no external image URLs |
| Service / Shared Workers | Blocked by `worker-src 'none'` — registering a SW is rejected |
| Arbitrary hardware | Web USB / Bluetooth / HID / Serial are blocked by `Permissions-Policy` |
| Screen capture | `display-capture` (the `getDisplayMedia` API) is blocked |
| Payment Request API | Blocked by `Permissions-Policy` |

External links work: `<a href="..." target="_blank">` opens a new tab, and `window.open()` is permitted (subject to the browser's popup blocker, which requires a user gesture). `allow-popups-to-escape-sandbox` means the new tab loads normally — the destination site isn't itself sandboxed.

A small allowlist of third-party iframe embeds is permitted: YouTube (`youtube.com`, `youtube-nocookie.com`), Vimeo (`player.vimeo.com`), and Spotify (`open.spotify.com`). Use the provider's `/embed/` URL directly; the script-based "paste this blockquote + script tag" flow from social platforms won't work because `script-src` doesn't include those hosts.

## Device APIs available with user permission

These APIs require an explicit browser permission prompt the first time they're used. Network exfiltration is blocked (`connect-src: 'none'`), so any captured data — audio, video, motion, gamepad state — can only be processed locally inside the artifact.

| API | Use cases |
|-----|-----------|
| `getUserMedia` (microphone) | Voice memos, mic-driven visualizers, instrument tuners, speech-to-something |
| `getUserMedia` (camera) | Photo booths, video filters, AR-style overlays, motion detection |
| Web MIDI (`navigator.requestMIDIAccess`) | MIDI controller-driven music, sequencers, synth interfaces |
| Gamepad API (`navigator.getGamepads`) | Game controller input — perfect for game artifacts |
| Device motion / orientation | Tilt-reactive art, accelerometer-driven physics on mobile |
| Screen Wake Lock (`navigator.wakeLock.request('screen')`) | Keep screen on for visualizers, long timers, ambient pieces |
| `<video autoplay>` / `AudioContext` autostart | Audio/video that plays on load (still subject to browser autoplay rules) |
| Fullscreen (`element.requestFullscreen()`) | Full-bleed experiences triggered by a user gesture |
| Picture-in-Picture | Floating video player for `<video>` elements |

## Per-artifact origin: storage works

Because each artifact has a unique subdomain origin, browser storage APIs work normally and are scoped to that one artifact:

| Available | Details |
|---------|---------|
| `localStorage` | Persists across sessions, scoped to this artifact only |
| `sessionStorage` | Per-tab, scoped to this artifact only |
| `IndexedDB` | Full database, scoped to this artifact only |
| Cookies | Scoped to this artifact (rarely needed; usually use localStorage instead) |

Storage is per-device and per-browser — there's no cloud sync. If a user opens the same artifact on their phone after using it on their laptop, they'll see a fresh state.

## What works

These APIs and features are fully available:

| Category | Details |
|----------|---------|
| DOM | Full DOM manipulation, dynamic element creation |
| Canvas | Canvas 2D and WebGL for graphics, games, visualizations |
| SVG | Inline SVG, dynamically created SVG elements |
| CSS | All CSS features including animations, transitions, custom properties, grid, flexbox |
| Animation | `requestAnimationFrame` for smooth 60fps animation loops |
| Input events | Pointer, mouse, touch, keyboard, scroll, resize events |
| Web Audio | AudioContext and Web Audio API (Tone.js is available in the JSX runtime) |
| Inline workers | Web Workers via `new Worker(URL.createObjectURL(new Blob([code])))` |
| Timers | `setTimeout`, `setInterval`, `requestIdleCallback` |
| Media | `<video>` and `<audio>` with inline data URI or blob sources |
| Clipboard | `navigator.clipboard` for copy-to-clipboard features (user gesture required) |
| URL/Blob | `URL.createObjectURL`, Blob, FileReader for in-memory file handling |

## Content Security Policy

The full CSP applied to artifact content:

```
default-src 'self' https://cdnjs.cloudflare.com https://cdn.tailwindcss.com https://unpkg.com;
script-src 'self' 'unsafe-inline' 'unsafe-eval' https://cdnjs.cloudflare.com https://cdn.tailwindcss.com https://unpkg.com;
style-src 'self' 'unsafe-inline' https://cdnjs.cloudflare.com https://cdn.tailwindcss.com https://unpkg.com https://fonts.googleapis.com;
img-src 'self' data: blob:;
media-src 'self' data: blob:;
connect-src 'none';
font-src 'self' data: https://fonts.gstatic.com;
frame-src https://www.youtube.com https://www.youtube-nocookie.com https://player.vimeo.com https://open.spotify.com;
object-src 'none';
base-uri 'none';
worker-src 'none';
```

## No server-side execution

At no point does your uploaded code run on a server. This is a load-bearing security property — anyone reasoning about the attack surface should be able to confirm it at each lifecycle stage:

| Phase | What runs | Where |
|---|---|---|
| Upload | Trusted JSX compiler (entry file only); magic-byte validation on bundled images | Rails server runs *our* code, not yours |
| Storage | Files sit at rest in R2 | Nothing executes |
| Serve | Cloudflare Worker reads bytes from R2 and returns the response | Worker is a static-file proxy — no parsing, no rendering |
| View | HTML/JS executes in the iframe | Viewer's browser, sandboxed, per-artifact origin |

Bundled images are pass-through bytes. The Worker doesn't decode them. The Rails scanner validates magic bytes but doesn't parse pixel data. The compiled HTML is generated once at upload and served as static content forever after.

## Best practices

- **Be responsive** — the artifact renders in an iframe that can be any width, from narrow mobile to wide desktop
- **Set the viewport** — always include `<meta name="viewport" content="width=device-width, initial-scale=1">`
- **Zero-margin body** — set `body { margin: 0; min-height: 100vh; }` for full-bleed layouts
- **Embed your data** — since network requests are blocked, put all data directly in the file (JSON constants, inline arrays, data attributes)
- **Bundle images instead of base64** when you have more than a couple — keeps the entry file small and the bundle compresses better at the network layer
- **Compress before uploading** — `cwebp -q 80`, ImageOptim, or squoosh.app. `aland validate` warns on any image over 500 KB.
- **Mind the cap for your tier** — 5 MB / 50 files free, 25 MB / 200 files Pro. Cap applies to the post owner.
- **Handle missing APIs gracefully** — if your artifact uses an API that might be blocked, check for availability and show a helpful message rather than breaking silently