QForm Builder Layer

@vevedh/qform-builder-layer est une couche Nuxt 4 réutilisable pour construire, prévisualiser et exécuter des formulaires dynamiques avec Vue 3, Quasar 2, Pinia et FormKit.

Le projet reste volontairement en architecture Nuxt Layer + .playground pour cette phase 1.

Documentation publiée : https://vevedh.github.io/qform-builder-layer/

Documentation languages: French at /, English at /en/.

Objectif de la phase 1

Préparer le projet pour une publication npm comme Nuxt Layer :

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

Cette phase permet d’intégrer rapidement FormBuilder et FormViewer dans NFZ Studio ou dans une autre application Nuxt 4.

Structure du dépôt

qform-builder-layer/
├── app/
│   ├── assets/
│   ├── components/
│   ├── composables/
│   ├── constants/
│   ├── stores/
│   ├── types/
│   └── utils/
├── .playground/
│   └── app/
│       ├── app.vue
│       ├── layouts/
│       └── pages/
├── docs/
├── formkit.config.ts
├── nuxt.config.ts
└── package.json

Les pages de démonstration sont isolées dans .playground/app/pages pour ne pas être injectées dans les applications qui consomment le layer.

Composants principaux

• FormBuilder.vue : builder complet avec drawers, toolbar, canvas, drag-and-drop, autosave, API publique et support multi-instance.
• FormViewer.vue : rendu runtime d’un formulaire à partir du schéma généré.
• FormCanvas.vue : zone de rendu/dépôt réutilisable.
• TheElementsDrawer.vue : catalogue et arborescence.
• TheFormSettingsDrawer.vue : panneau de propriétés.
• components/quasar/*.vue : adaptateurs FormKit vers Quasar.
• components/settings/**/*.vue : panneaux de configuration par type de champ.

Développement local

bun install
bun run dev

Le script démarre .playground, qui étend automatiquement le layer racine.

Routes de test :

/
/autonome
/multi-instance
/viewer

Documentation VitePress

Documentation publiée : https://vevedh.github.io/qform-builder-layer/

bun run docs:dev
bun run docs:i18n:check
bun run docs:build
bun run docs:preview

La documentation est bilingue :

/       Français
/en/    English

Le script docs:i18n:check vérifie qu’à chaque modification de la documentation, chaque page française possède son équivalent anglais sous docs/en/.

Entrées importantes :

• docs/guide/installation-nuxt-new.md
• docs/guide/integration-existing-nuxt.md
• docs/guide/npm-layer-publication.md
• docs/guide/future-nuxt-module.md
• docs/reference/features-vs-vueform-builder.md

Utilisation dans une nouvelle application Nuxt 4

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

Puis :

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

  compatibilityDate: '2026-05-08'
})

Exemple :

<script setup lang="ts">
import type { FormKitSchemaDefinition } from '@formkit/core'

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

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

<template>
  <ClientOnly>
    <FormBuilder
      builder-id="contact-form-builder"
      v-model:schema="schema"
      v-model:values="values"
      autosave
      storage-key="contact-form-builder"
    />
  </ClientOnly>
</template>

Publication de la documentation sur GitHub Pages

Le dépôt contient un workflow prêt à l’emploi :

.github/workflows/docs.yml

Il construit la documentation VitePress avec Bun puis publie docs/.vitepress/dist sur GitHub Pages.

À configurer une seule fois dans GitHub :

Settings → Pages → Build and deployment → Source: GitHub Actions

Le workflow définit automatiquement le base VitePress à partir du nom du dépôt :

VITEPRESS_BASE: '/${{ github.event.repository.name }}/'

En local, la documentation garde base: '/'. La page détaillée se trouve dans :

docs/guide/github-pages.md

Publication npm

Contrôles avant publication :

bun run docs:build
bun run typecheck:nuxt
bun run pack:dry-run

Publication scoped public :

npm login
npm publish --access public

Le package contient déjà :

{
  "publishConfig": {
    "access": "public"
  }
}

Choix importants de packaging

Les démos ne sont pas publiées dans le layer runtime

Les fichiers suivants ont été déplacés dans .playground :

.playground/app/app.vue
.playground/app/layouts/default.vue
.playground/app/pages/index.vue
.playground/app/pages/autonome.vue
.playground/app/pages/multi-instance.vue
.playground/app/pages/viewer.vue

Cela évite d’injecter des routes de démonstration dans l’application hôte.

Le layer ne force plus ssr: false

Le choix SSR appartient à l’application consommatrice.

Pour FormBuilder, l’usage recommandé dans une app SSR est :

<ClientOnly>
  <FormBuilder builder-id="admin-builder" />
</ClientOnly>

Les dépendances sont déclarées en peerDependencies

L’application hôte reste maître de ses versions de Nuxt, Vue, Quasar, Pinia et FormKit.

Statut Community finalisé

Cette archive correspond à la préparation de l’édition Community comme package npm Nuxt Layer.

Le contrat Community est documenté dans :

COMMUNITY_EDITION.md
RELEASE_CHECKLIST.md
CHANGELOG.md
SECURITY.md
docs/guide/community-edition.md
docs/guide/release-checklist.md
docs/reference/package-contract.md

Contrôles recommandés avant publication :

bun run release:doctor
bun run release:publish:dry-run

Le package est volontairement limité à la Community. Les futures fonctionnalités Pro doivent être placées dans un package séparé plutôt qu’intégrées dans Community avec un simple contrôle frontend.

Types publics

Dans une application consommatrice, les types publics peuvent être importés via :

import type {
  FormBuilderSchema,
  FormBuilderValues,
  FormBuilderSavePayload,
  FormBuilderPublicApi,
} from '@vevedh/qform-builder-layer/types'

Test consommateur minimal

<script setup lang="ts">
import type { FormBuilderSchema, FormBuilderValues } from '@vevedh/qform-builder-layer/types'

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

<template>
  <ClientOnly>
    <FormBuilder
      builder-id="consumer-test-builder"
      v-model:schema="schema"
      v-model:values="values"
      autosave
    />
  </ClientOnly>
</template>

Roadmap

Phase 1 — Nuxt Layer npm

• package scoped npm ;
• .playground isolé ;
• routes de démo non publiées ;
• files sécurisé ;
• peerDependencies explicites ;
• documentation VitePress complète.

Phase 2 — Module Nuxt 4

Objectif futur :

export default defineNuxtConfig({
  modules: ['@vevedh/nuxt-qform-builder'],

  qformBuilder: {
    prefix: '',
    installPinia: true,
    installFormKit: true,
    installQuasar: true,
    injectCss: true
  }
})

La trajectoire est documentée dans :

docs/guide/future-nuxt-module.md

Note licence

La licence de travail est MIT. À remplacer avant publication si tu souhaites une licence propriétaire ou une licence commerciale spécifique.

GitHub Pages workflow compatibility

The documentation workflow uses the current GitHub Pages actions and opts into the Node.js 24 JavaScript actions runtime to avoid Node.js 20 deprecation warnings.