ContentBox.js · Guide

Using ContentBox.js in a Next.js Project

ContentBox.js is a JavaScript library for designing and building complete web pages with simple drag and drop. In this guide we add it to a Next.js app. First we embed the editor, then we add saving, uploads and a page that shows the saved page to visitors.

ContentBox comes in two parts:

ContentBox

The editor, used on the page where pages are built.

ContentBox Runtime

Renders the saved page on your site. It makes interactive blocks (sliders, counters, charts, accordions and more) work, both while editing and when viewing.

In this guide

  1. Set up the project
  2. Embed the editor
  3. Add saving and uploads
  4. Show the page to visitors
  5. Try it

Step 1

Set up the project

Create a Next.js project and install ContentBox and the Runtime:

npx create-next-app@latest my-app --ts --app --src-dir --eslint --no-tailwind --import-alias "@/*" --yes
cd my-app
npm install @innovastudio/contentbox @innovastudio/contentbox-runtime

The editor needs its assets (sections, snippets, icons, fonts, plugins). They are in the ContentBox.js ZIP package, which you can download from your user area. Copy these into your project's public/ folder:

public/
├── assets/      # sections, snippets, fonts, plugins
├── runtime/     # runtime files, used by blank.html and preview.html
├── blank.html   # the page you edit, shown inside the editor
└── preview.html # Page Preview

Step 2

Embed the editor

One thing first: the starter's globals.css removes the margin and padding of every element, which would change how your pages look. In src/app/layout.tsx, remove this line:

import "./globals.css";

Now create src/app/edit/page.tsx:

'use client'

import { useEffect } from 'react'
import ContentBox from '@innovastudio/contentbox'
import '@innovastudio/contentbuilder/public/contentbuilder/contentbuilder.css'
import '@innovastudio/contentbox/public/contentbox/contentbox.css'

export default function EditPage() {
    useEffect(() => {
        // Create the editor
        const builder = new ContentBox({
            controlPanel: true,
            iframeSrc: '/blank.html', // the page you edit
            snippetUrl: '/assets/minimalist-blocks/content-plugins.js', // the blocks users can drag in
        })

        // Load the page to edit
        builder.loadHtml(`
            <div class="is-section is-box type-system-ui">
                <div class="is-overlay"></div>
                <div class="is-container v2 leading-14 size-18">
                    <div class="row">
                        <div class="column">
                            <h1>Hello World</h1>
                            <p>Start editing your page here.</p>
                        </div>
                    </div>
                </div>
            </div>`)

        return () => builder.destroy()
    }, [])

    return null // ContentBox adds its own interface to the page
}

'use client' makes the page run in the browser, where the editor works. Keep the two stylesheets in this order: contentbuilder.css first, then contentbox.css.

The page you edit is shown inside the editor from blank.html. It already starts the runtime, so interactive blocks work while you edit.

Run it:

npm run dev

Open http://localhost:3000/edit. You have a working editor: click the text to edit it, add sections with the + button on the left, and drag in blocks from the Blocks button below it, including interactive ones like a countdown or a chart.

The ContentBox.js editor in a Next.js app after step 2, with Hello World

The editor after step 2. Click the text to edit it, add sections with + and blocks from the Blocks panel.

Step 3

Add saving and uploads

Now let's add saving and uploads. The editor saves to the server through three small API routes. In this guide the page is kept in a JSON file, data/content.json, so you can run it without a database.

A page has three parts: the content (html), the styles used on the page (mainCss) and the styles of each section (sectionCss). The routes save and load all three.

Create src/app/api/load/route.ts:

import { readFile } from 'fs/promises'

export async function GET() {
    try {
        return Response.json(JSON.parse(await readFile('data/content.json', 'utf8')))
    } catch {
        return Response.json({ html: '', mainCss: '', sectionCss: '' }) // nothing saved yet
    }
}

Create src/app/api/save/route.ts:

import { mkdir, writeFile } from 'fs/promises'

export async function POST(request: Request) {
    const { html, mainCss, sectionCss } = await request.json()
    await mkdir('data', { recursive: true })
    await writeFile('data/content.json', JSON.stringify({ html, mainCss, sectionCss }))
    return Response.json({ ok: true })
}

Create src/app/api/upload/route.ts, and an empty public/uploads/ folder for the files:

import path from 'path'
import { writeFile } from 'fs/promises'

export async function POST(request: Request) {
    const formData = await request.formData()
    const file = formData.get('file') as File | null
    if (!file) return Response.json({ error: 'No file received.' }, { status: 400 })

    const filename = path.basename(file.name).replaceAll(' ', '_')
    await writeFile(path.join('public/uploads', filename), Buffer.from(await file.arrayBuffer()))

    return Response.json({ url: '/uploads/' + filename }) // ContentBox needs { url }
}

Then replace src/app/edit/page.tsx:

'use client'

import { useEffect, useRef } from 'react'
import ContentBox from '@innovastudio/contentbox'
import '@innovastudio/contentbuilder/public/contentbuilder/contentbuilder.css'
import '@innovastudio/contentbox/public/contentbox/contentbox.css'

const DEFAULT_CONTENT = `
<div class="is-section is-box type-system-ui">
    <div class="is-overlay"></div>
    <div class="is-container v2 leading-14 size-18">
        <div class="row">
            <div class="column">
                <h1>Hello World</h1>
                <p>Start editing your page here.</p>
            </div>
        </div>
    </div>
</div>`

// Sends the file to the upload route, which returns { url }
async function upload(file: File) {
    const formData = new FormData()
    formData.append('file', file)
    const response = await fetch('/api/upload', { method: 'POST', body: formData })
    return response.json()
}

export default function EditPage() {
    const builderRef = useRef<ContentBox | null>(null)

    useEffect(() => {
        let cancelled = false

        // Create the editor
        const builder = new ContentBox({
            controlPanel: true,
            iframeSrc: '/blank.html', // the page you edit
            snippetUrl: '/assets/minimalist-blocks/content-plugins.js', // the blocks users can drag in
            topSpace: true,           // leaves room at the top for our toolbar
            upload,                   // handles image, video, audio and file uploads
        })
        builderRef.current = builder

        // Load the saved page, or the default the first time
        fetch('/api/load')
            .then((response) => response.json())
            .then((data) => {
                if (cancelled) return
                builder.loadHtml(data.html || DEFAULT_CONTENT)
                builder.loadStyles(data.mainCss || '', data.sectionCss || '')
            })

        return () => {
            cancelled = true
            builder.destroy()
            builderRef.current = null
        }
    }, [])

    const save = async () => {
        const builder = builderRef.current
        if (!builder) return
        await fetch('/api/save', {
            method: 'POST',
            headers: { 'Content-Type': 'application/json' },
            body: JSON.stringify({
                html: builder.html(),
                mainCss: builder.mainCss(),       // styles used on the page
                sectionCss: builder.sectionCss(), // styles of each section
            }),
        })
    }

    return (
        <div style={{
            position: 'fixed', top: 0, left: 0, right: 0, height: 55, zIndex: 10,
            display: 'flex', alignItems: 'center', justifyContent: 'flex-end', gap: 8,
            padding: '0 20px', background: '#fff', borderBottom: '1px solid #eee',
        }}>
            <button onClick={() => builderRef.current?.openPagePreview()}>Preview</button>
            <button onClick={async () => { await save(); window.open('/view', '_blank') }}>View page</button>
            <button onClick={async () => { await save(); alert('Page saved!') }}>Save</button>
        </div>
    )
}

What's new

  • Saving: html(), mainCss() and sectionCss() return the three parts of the page, which are sent to the save route. The next time, loadHtml() and loadStyles() load them back from the load route.
  • Uploads: upload is one function for all media. It sends the file to the upload route, which returns { url }.
  • Toolbar: topSpace leaves room at the top for it. Preview shows the page at any screen width (using public/preview.html), Save saves, and View page saves and opens the viewing page, which we add next.
The ContentBox.js editor in a Next.js app, with a saved page loaded back in

A saved page, with its styles, loads back into the editor the next time you open it.

Step 4

Show the page to visitors

The viewing page is rendered on the server, so the page is already in the HTML that browsers and search engines receive. This is good for SEO. The page needs only the runtime, not the editor.

Create src/app/view/page.tsx:

import { Suspense } from 'react'
import { connection } from 'next/server'
import { readFile } from 'fs/promises'
import Runtime from './runtime'
import '@innovastudio/contentbox-runtime/dist/contentbox-runtime.css'

async function Content() {
    await connection() // render on every request, so the latest saved page shows

    let page = { html: '', mainCss: '', sectionCss: '' }
    try {
        page = JSON.parse(await readFile('data/content.json', 'utf8'))
    } catch {
        // nothing saved yet
    }

    return (
        <>
            {/* The saved styles (mainCss and sectionCss), then the content */}
            <div
                className="is-wrapper" // required for page styling
                dangerouslySetInnerHTML={{
                    __html: page.mainCss + page.sectionCss + (page.html || '<p>No content available.</p>'),
                }}
            />
            <Runtime />
        </>
    )
}

export default function ViewPage() {
    return (
        <Suspense>
            <Content />
        </Suspense>
    )
}

The runtime runs in the browser, so it goes in a small client component. Create src/app/view/runtime.tsx:

'use client'

import { useEffect } from 'react'
import ContentBoxRuntime from '@innovastudio/contentbox-runtime'

// Activates interactive blocks in the page rendered by the server
export default function Runtime() {
    useEffect(() => {
        const runtime = new ContentBoxRuntime({
            pluginFolder: window.location.origin + '/assets/plugins/',
        })
        runtime.init()
        return () => runtime.destroy()
    }, [])

    return null
}

The server puts the page in the HTML, and then the runtime makes the interactive blocks work. pluginFolder tells the runtime where the plugins are. A plugin's files are loaded only when the page uses it.

Important: the viewing container must have the is-wrapper class.

Step 5

Try it

With npm run dev running, open http://localhost:3000/edit, add some sections and blocks, and click Save. Click View page to see the saved page.

The Next.js viewing page showing a page saved with ContentBox.js

The viewing page, rendered on the server, shows the saved page to visitors.

Going to production

  • Saving: replace the JSON file in the load and save routes and the viewing page with your database or CMS. Save all three parts: the content, mainCss and sectionCss.
  • Uploads: send files to your storage (S3 or any other) and return { url }. After next build, Next.js serves only the files that were in public/ at build time, so new uploads saved there don't show.
  • Security: add authentication to the API routes, so only your editors can save and upload.

Resources

  • ContentBox.js innovastudio.com/contentbox
  • Documentation on GitHub github.com/innovastudio-dev/contentbox
  • In the package: the same documentation is in its docs/ folder (docs/README.md to get started, docs/reference.md for all options)

© 2026 InnovaStudio

This site is built with Site Builder Kit