Skip to main content
This guide walks you through a complete blökkli integration from scratch. By the end, you’ll have the module installed, an adapter wired up, a page with an editable field, and a working block component you can open in the editor.
1

Install the package

Add @blokkli/editor to your project using your preferred package manager.
npm install --save @blokkli/editor
2

Configure the Nuxt module

Register @blokkli/editor in your nuxt.config.ts and set the required itemEntityType option.
nuxt.config.ts
export default defineNuxtConfig({
  modules: ['@blokkli/editor'],
  blokkli: {
    itemEntityType: 'block',
  },
})
itemEntityType is the entity type string blökkli uses to identify individual block items in your backend. Set it to whatever string your data layer uses — 'block', 'paragraph', 'content_block', etc.
3

Create the edit adapter

Create the file app/blokkli.editAdapter.ts. This is where you connect blökkli to your backend by implementing the adapter interface.
app/blokkli.editAdapter.ts
import { defineBlokkliEditAdapter } from '#blokkli/adapter'

export default defineBlokkliEditAdapter((ctx) => {
  return {
    async loadState() {
      // Return initial block state from your backend.
      // ctx gives you access to the current entity context.
      return { /* ... */ }
    },

    async mapState(state) {
      // Transform raw backend state into blökkli's internal format.
      return state
    },

    async getAllBundles() {
      // Return the list of block type definitions available to editors.
      // Each entry describes a bundle: its name, label, and field config.
      return []
    },

    async getFieldConfig() {
      // Return field-level configuration for the current entity.
      return []
    },

    async addNewBlock(options) {
      // Persist a newly added block to your backend.
      // options includes the bundle, field name, and insertion index.
    },

    async moveBlock(options) {
      // Update your backend when an editor moves a single block.
    },

    async moveMultipleBlocks(options) {
      // Update your backend when an editor moves several blocks at once.
    },
  }
})
This is the minimum required adapter. blökkli’s adapter interface includes many more optional callbacks — updateOptions, publish, deleteBlocks, duplicateBlocks, and others. See the adapter reference for the full list.
4

Add BlokkliProvider to your page

Wrap your page template with <BlokkliProvider> to declare the editing context, then place <BlokkliField> wherever you want a list of editable blocks.
pages/[slug].vue
<template>
  <BlokkliProvider
    :entity="{
      entity_type: 'node',
      entity_bundle: 'page',
      entity_uuid: page.uuid,
    }"
    :can-edit="true"
  >
    <BlokkliField :list="page.blocks" name="blocks" />
  </BlokkliProvider>
</template>
  • :entity identifies the content item being edited. blökkli passes this context to your adapter callbacks.
  • :can-edit="true" tells the provider to honor the ?blokkliEditing URL parameter. In a real app, drive this from a session check — e.g., :can-edit="user.canEdit".
  • :list is the array of block objects from your data source. Each item needs at minimum a bundle and a uuid.
  • name is the field identifier — it matches the field name your adapter receives in addNewBlock and moveBlock callbacks.
5

Create a block component

Create components/Blokkli/Text.vue. blökkli automatically maps any block with bundle: 'text' to this component.
components/Blokkli/Text.vue
<template>
  <div class="text-block">
    <p>{{ options.text }}</p>
  </div>
</template>

<script lang="ts" setup>
const { options } = defineBlokkli({
  bundle: 'text',
  options: {
    text: {
      type: 'text',
      label: 'Text content',
      default: '',
    },
  },
})
</script>
defineBlokkli() registers this SFC as the renderer for the 'text' bundle and declares one option — text — that editors can change in the options panel. The returned options object is reactive and always reflects the current value, in both edit mode and production.
Name your component files after the bundle. components/Blokkli/Text.vue handles the text bundle, components/Blokkli/Hero.vue handles hero, and so on. blökkli uses this naming convention to auto-discover your block components.
6

Activate the editor

Start your dev server and navigate to the page you wired up. Append ?blokkliEditing={entity-uuid} to the URL — substituting the actual UUID of your entity — to enter edit mode:
http://localhost:3000/my-page?blokkliEditing=550e8400-e29b-41d4-a716-446655440000
The blökkli editor overlay activates, and you can start adding, dragging, and configuring blocks.
The editor only activates when both conditions are true: the ?blokkliEditing parameter is present in the URL and :can-edit is true on the <BlokkliProvider>. If can-edit is false, the parameter is ignored and the page renders in read-only mode.

Next Steps

Now that you have a working editor, explore the full adapter interface to unlock features like option updates, publishing, duplication, and clipboard support.

Module Configuration

Explore all blokkli config options available in nuxt.config.ts.

Defining Blocks

Learn the full defineBlokkli() API — options schemas, editor metadata, slots, and more.