@playcode/embed

Embed a live Playcode Cloud project - an AI-built, full-stack website or app - into any web page. Zero dependencies, framework-agnostic, responsive, and lazy-loaded.

Playcode is an AI app builder for non-technical teams: describe the software you want in plain English, Playcode AI builds it, and Playcode Cloud runs it with a real backend, database, HTTPS, and custom domains. Every Cloud project is served at https://{slug}.playcode.ai, so this package wraps it in a clean, responsive iframe for your portfolio, docs, blog, or landing page.

npm install @playcode/embed

Cloud and browser projects are both embeddable. Cloud projects (https://{slug}.playcode.ai) are the default. Browser projects (https://{slug}.playcode.site) also work - pass host: "playcode.site". See Embeddability for the one caveat (an app that sets its own X-Frame-Options / CSP frame-ancestors).

Quick start

Web component (recommended)

<script type="module">
  import { definePlaycodeEmbed } from '@playcode/embed/web-component'
  definePlaycodeEmbed()
</script>

<playcode-embed project="ianberdin" aspect-ratio="16/9"></playcode-embed>

From a CDN, no build step

<script src="https://unpkg.com/@playcode/embed"></script>

<!-- Auto-embedded on load: -->
<div data-playcode="ianberdin" data-aspect-ratio="16/9"></div>

Programmatic API

import { playcodeEmbed } from '@playcode/embed'

playcodeEmbed('#preview', {
  project: 'ianberdin', // slug, numeric id, or uid from the Cloud project URL
  aspectRatio: '16/9',
  lazy: true,
  attribution: true,
})

Build a URL only (SSR / frameworks)

import { buildEmbedUrl } from '@playcode/embed'

buildEmbedUrl({ project: 'ianberdin' })
// "https://ianberdin.playcode.ai"

buildEmbedUrl({ project: 'ianberdin', port: 5432 })
// "https://5432--ianberdin.playcode.ai"  (non-default Cloud port)

buildEmbedUrl({ url: 'https://app.acme.com', params: { theme: 'dark' } })
// "https://app.acme.com/?theme=dark"  (custom domain)

Embeddability

| Project type | URL | Embeddable cross-origin? | |---|---|---| | Cloud (full-stack app) | https://{slug}.playcode.ai | Yes (default) | | Browser (client-only) | https://{slug}.playcode.site | Yes - pass host: "playcode.site" | | Custom domain | your domain | Depends on the app's own headers |

If your own app sets X-Frame-Options or a CSP frame-ancestors directive, those win - the embed will be blocked regardless of this library.

Options

| Option | Type | Default | Description | |---|---|---|---| | project | string | - | Project slug, numeric id, or uid (e.g. "my-app" or "1374"). | | url | string | - | Full URL to embed (custom domains, hand-built preview URLs). Overrides project. | | host | string | "playcode.ai" | Host serving the project. Cloud (playcode.ai) and browser (playcode.site) are both frameable. | | port | number | - | Expose a non-default Cloud port ({port}--{slug}.{host}). | | aspectRatio | string | "16/10" | Responsive CSS aspect ratio, e.g. "16/9". | | height | string | - | Fixed CSS height. Overrides aspectRatio. | | lazy | boolean | true | Load the iframe when it scrolls into view. | | attribution | boolean | true | Show a "Built with Playcode" link below the frame. | | title | string | "Playcode project" | Accessible iframe title. | | params | Record<string,string> | - | Extra query params appended to the embed URL. | | allow | string | sensible default | iframe permissions-policy allow attribute. | | sandbox | string \| null | sensible default | iframe sandbox; pass null to omit. |

Web-component attributes are the kebab-case equivalents (aspect-ratio, data-playcode, ...).

Exports

• @playcode/embed - buildEmbedUrl, playcodeEmbed, autoEmbed.
• @playcode/embed/web-component - definePlaycodeEmbed, PlaycodeEmbedElement.
• @playcode/embed/auto - everything, plus auto-registration on load (the CDN build).

Ships ESM, CommonJS, TypeScript types, and a minified IIFE for <script> tags.

Links

• Playcode - AI Website & App Builder
• Playcode Cloud
• Issues

License

MIT (c) Playcode