Utiliser QForm Builder dans une nouvelle application Nuxt 4

Cette page montre comment créer une application Nuxt 4 neuve qui consomme QForm Builder comme layer npm ou comme layer local.

1. Créer l’application Nuxt 4

bunx nuxi init qform-demo
cd qform-demo
bun install

Structure minimale attendue :

qform-demo/
├── app/
│   ├── app.vue
│   └── pages/
└── nuxt.config.ts

2. Ajouter le layer

Mode npm

bun add @vevedh/qform-builder-layer

Puis :

export default defineNuxtConfig({
  extends: ['@vevedh/qform-builder-layer']
})

Mode local pendant le développement

Copie l’archive qform-builder dans un dossier layers :

qform-demo/
├── app/
├── layers/
│   └── qform-builder/
│       ├── app/
│       ├── formkit.config.ts
│       └── nuxt.config.ts
└── nuxt.config.ts

Puis :

export default defineNuxtConfig({
  extends: ['./layers/qform-builder']
})

3. Installer les dépendances nécessaires

Le package déclare ses dépendances principales en peerDependencies. Installe-les explicitement dans l’application hôte pour garder la maîtrise des versions Nuxt, Quasar, Pinia et FormKit.

bun add @vevedh/qform-builder-layer \
  nuxt-quasar-ui @pinia/nuxt @formkit/nuxt \
  quasar @quasar/extras \
  @formkit/core @formkit/i18n @formkit/vue @formkit/utils

4. Configurer nuxt.config.ts

// nuxt.config.ts
export default defineNuxtConfig({
  extends: ['@vevedh/qform-builder-layer'],

  compatibilityDate: '2026-05-08'
})

Le layer apporte déjà la configuration Quasar, Pinia et FormKit. L’application hôte peut ensuite compléter cette configuration si nécessaire.

Pour un test local avant publication, remplace @vevedh/qform-builder-layer par ./layers/qform-builder.

5. Créer une page builder

<!-- app/pages/forms/builder.vue -->
<script setup lang="ts">
import type { FormKitSchemaDefinition } from '@formkit/core'

type FormBuilderSchema = FormKitSchemaDefinition[]
type FormBuilderValues = Record<string, unknown>

type SavePayload = {
  builderId: string
  schema: FormBuilderSchema
  values: FormBuilderValues
  settings: Record<string, unknown>
}

const schema = ref<FormBuilderSchema>([])
const values = ref<FormBuilderValues>({})

function handleSave(payload: SavePayload) {
  if (!import.meta.client) return

  localStorage.setItem(
    `demo:form:${payload.builderId}`,
    JSON.stringify({
      schema: payload.schema,
      values: payload.values,
      settings: payload.settings,
      savedAt: new Date().toISOString()
    })
  )
}
</script>

<template>
  <ClientOnly>
    <FormBuilder
      builder-id="demo-contact-form"
      v-model:schema="schema"
      v-model:values="values"
      title="Formulaire de contact"
      subtitle="Exemple d’intégration dans une nouvelle application Nuxt 4"
      autosave
      height="calc(100vh - 32px)"
      @save="handleSave"
    />
  </ClientOnly>
</template>

6. Lancer l’application

bun run dev

Puis ouvre :

http://localhost:3000/forms/builder

Bonne pratique

Dans une application métier, ne sauvegarde pas directement depuis la page dans localStorage. Utilise plutôt une couche d’accès dédiée, par exemple :

app/services/formsRepository.ts
app/stores/formsStore.ts

Cela permet de remplacer ensuite le stockage local par un service Feathers/NFZ sans modifier les composants UI.