GitHub. Website.

Status: Experimental.

Quick start

StackBlitz demo

Scaffold your app

If you have an existing Next.js app, you can skip this step.

Create a new Next.js project with:

$ npx create-next-app@latest

cd into your project directory and install dependencies with npm install.


whyframe comes in two packages, the core library and the UI framework integration.

# Install the core library
$ npm install -D @whyframe/core

# Install the JSX integration
$ npm install -D @whyframe/jsx


whyframe works on the bundler level, so the packages are simply Webpack plugins and loaders. You can initialize these plugins in your next.config.js:

import { WhyframePlugin } from '@whyframe/core/webpack'

/** @type {import('next').NextConfig} */
export default {
  webpack(config) {
      new WhyframePlugin({
        defaultSrc: '/frames/default' // provide our own html
      // Set `/\.[jt]sx?$/` if you want to process .js files as .jsx
      test: /\.[jt]sx$/,
      exclude: /node_modules/,
      use: [
          loader: '@whyframe/jsx/loader',
          options: {
            defaultFramework: 'react'
    return config

As whyframe’s default HTML doesn’t work in Next.js, a custom HTML source is required. See HTML source for more information.

To setup /frames/default, or in other words http://localhost:3000/frames/default, create a src/pages/frames/default/index.jsx file:

import { createApp } from 'whyframe:app'

export default function DefaultFrame() {
  return <div ref={(el) => createApp(el)}></div>

And done! You can also add more code and styles to src/pages/frames/default/index.js if you prefer.


You can edit src/pages/index.jsx to start creating an iframe. For example:

<iframe data-why>
  Hello world!

Start your app with npm run dev and watch Hello world! rendered within the iframe as-is!

Check out Features for more things you can do with whyframe.