Dépannage

Les composants FormBuilder ou FormViewer ne sont pas trouvés

Vérifie que le layer est bien déclaré dans nuxt.config.ts :

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

Puis relance la génération Nuxt :

bunx nuxi cleanup
bunx nuxi prepare
bun run dev

Les imports #components échouent

#components est généré par Nuxt. Si l’erreur apparaît, c’est souvent que .nuxt est obsolète ou que le layer n’a pas été correctement chargé.

Commande conseillée :

bunx nuxi cleanup
bun install
bun run dev

Sous Windows, en cas d’artefacts persistants :

Remove-Item -Recurse -Force .nuxt, .output, node_modules\.cache\vite, node_modules\.vite -ErrorAction SilentlyContinue
bun install
bunx nuxi prepare

Le builder perd son état ou mélange deux formulaires

Chaque instance doit avoir un builder-id unique et stable :

<FormBuilder builder-id="service-users-form" />
<FormBuilder builder-id="service-projects-form" />

Évite les identifiants dynamiques instables :

<!-- À éviter -->
<FormBuilder :builder-id="Date.now().toString()" />

L’autosave ne recharge pas le schéma attendu

Si tu fournis v-model:schema, le schéma contrôlé par le parent est prioritaire. L’autosave hydrate surtout les usages non contrôlés ou les états internes.

Pour une restauration maîtrisée, charge explicitement le schéma depuis ton store ou ton API avant d’afficher le builder :

<FormBuilder
  v-if="loaded"
  :builder-id="builderId"
  v-model:schema="schema"
  v-model:values="values"
/>

Mon application existante utilise SSR

La version actuelle du layer définit ssr: false, car le builder repose sur des API navigateur et des interactions drag and drop.

Pour une app SSR, stratégies possibles :

1. isoler le builder dans une app admin séparée ;
2. accepter que le layer force le mode SPA ;
3. prévoir un futur patch pour rendre la config SSR neutre et encapsuler le builder avec ClientOnly.

Les types ~/types/form-builder ne marchent pas dans l’application hôte

Dans une application qui consomme un layer, ~/ pointe vers l’application hôte, pas forcément vers le layer. Utilise plutôt des types locaux minimaux :

import type { FormKitSchemaDefinition } from '@formkit/core'

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

FormViewer n’affiche rien

Vérifie que :

1. form-fields est un tableau ;
2. chaque champ possède un name unique ;
3. les composants FormKit custom comme q-input, q-select, q-checkbox sont bien enregistrés par le layer ;
4. le schéma contient au moins un champ visible.

Exemple minimal :

const schema = [
  {
    $formkit: 'q-input',
    name: 'firstname',
    label: 'Prénom',
    inputType: 'text',
  },
]

Le formulaire ne se soumet pas

Ajoute un bouton submit dans le schéma :

const schema = [
  {
    $formkit: 'q-input',
    name: 'email',
    label: 'E-mail',
    inputType: 'email',
    validation: 'required|email',
  },
  {
    $formkit: 'q-btn',
    name: 'submit',
    buttonLabel: 'Envoyer',
    type: 'submit',
    color: 'primary',
    ignore: true,
  },
]

Bonne pratique globale

Quand un bug apparaît, teste d’abord dans .playground puis dans l’application consommatrice. Si le bug existe uniquement dans l’application consommatrice, il vient généralement de la configuration Nuxt, d’un conflit de dépendances ou d’un double module Quasar/FormKit.