Erreur Unknown input type "q-columns"

Cette erreur indique que le schéma contient un adaptateur QForm Builder, mais que l'application a chargé un autre formkit.config.ts ne contenant pas ce type.

QForm Builder lie désormais explicitement FormKit au fichier du layer :

const layerFormKitConfig = normalizeLayerFileUrl(
  new URL('./formkit.config.ts', import.meta.url),
)

export default defineNuxtConfig({
  formkit: {
    configFile: layerFormKitConfig,
    defaultConfig: true,
    autoImport: false,
  },
})

Dans le dépôt de développement, .playground/formkit.config.ts doit seulement réexporter le fichier racine. Ne maintiens jamais deux listes d'adaptateurs.

Vérifications :

bun run formkit:check && bun run typecheck

Si l'application hôte remplace volontairement formkit.configFile, elle doit réenregistrer qformBuilderQuasarPlugin depuis @vevedh/qform-builder-layer/formkit.config.

Dépannage

Erreur Failed to resolve import "~/assets/scss/index.scss"

Cette erreur signifie que le stylesheet du layer a été déclaré avec un alias appartenant à l'application hôte. Dans un Nuxt Layer publié, ~ pointe vers le playground ou l'application consommatrice.

Le nuxt.config.ts du layer doit utiliser un chemin résolu depuis son propre fichier :

const layerStylesheetUrl = new URL(
  './app/assets/scss/index.scss',
  import.meta.url,
)

const layerStylesheet = decodeURIComponent(layerStylesheetUrl.pathname)
  .replace(/^\/([A-Za-z]:\/)/, '$1')

export default defineNuxtConfig({
  css: [layerStylesheet],

  vite: {
    optimizeDeps: {
      include: [
        '@formkit/core',
        '@formkit/i18n',
        '@formkit/utils',
        'shiki',
      ],
    },
  },
})

Après correction :

bun run clean && bun install --frozen-lockfile && bun run typecheck && bun run dev

Erreur TypeScript Cannot find module 'node:url'

Le runtime Node sait charger node:url, mais le tsconfig généré du playground peut ne pas inclure les déclarations @types/node. QForm Builder évite cette dépendance dans nuxt.config.ts et utilise uniquement les API standards URL, decodeURIComponent et une normalisation Windows.

Ne réintroduis pas fileURLToPath dans le fichier de configuration du layer sans ajouter et valider explicitement les types Node dans le projet consommateur.

Dépendances découvertes à chaud par Vite

Le layer pré-bundle les dépendances utilisées directement par le runtime :

vite: {
  optimizeDeps: {
    include: [
      '@formkit/core',
      '@formkit/i18n',
      '@formkit/utils',
      'shiki',
    ],
  },
}

Le playground conserve séparément les dépendances DevTools dans son propre optimizeDeps.include.

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 :

bun run clean
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 :

bun run clean
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

Le layer racine ne force pas ssr: false. L'application hôte conserve sa stratégie SSR. Comme FormBuilder utilise des API navigateur et le drag-and-drop, encapsule-le avec ClientOnly :

<ClientOnly>
  <FormBuilder builder-id="admin-builder" />
</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.

Page vide au premier test Playwright sous Windows

Après un nettoyage complet, Vite peut réinitialiser son graphe client pendant la découverte d’une dépendance FormKit. Le projet pré-bundle explicitement la pile FormKit dans .playground/nuxt.config.ts, supprime les caches Vite racine et playground avec bun run clean, puis autorise uniquement un retry borné pour les modules Nuxt/Vite échouant avec ERR_ABORTED ou ERR_CONNECTION_RESET. Une erreur HTTP, Quasar ou métier reste fatale.

Pour les assertions d’état global, cibler [data-qform-runtime-shell] et non [data-qform-interaction-phase] seul, car les overlays de champs exposent également leur phase.