Unknown input type "q-columns"

This error means that the schema contains a QForm Builder adapter while the application loaded another formkit.config.ts that does not register that type.

QForm Builder now explicitly binds FormKit to the layer configuration:

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

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

Inside the development repository, .playground/formkit.config.ts must only re-export the root file. Never maintain two adapter lists.

Checks:

bun run formkit:check && bun run typecheck

When a host application intentionally overrides formkit.configFile, it must register qformBuilderQuasarPlugin from @vevedh/qform-builder-layer/formkit.config again.

Troubleshooting

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

This error means that the layer stylesheet was declared with an alias owned by the host application. In a published Nuxt Layer, ~ points to the playground or consuming application.

Resolve the stylesheet from the layer configuration file itself:

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',
      ],
    },
  },
})

Then run:

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

TypeScript error Cannot find module 'node:url'

The Node runtime can load node:url, but the generated playground tsconfig may not include direct @types/node declarations. QForm Builder avoids this dependency in nuxt.config.ts and relies only on the standard URL and decodeURIComponent APIs plus Windows path normalization.

Do not reintroduce fileURLToPath in the layer configuration unless Node types are explicitly installed and validated in the consuming project.

Dependencies discovered at runtime by Vite

The layer pre-bundles dependencies directly used by the runtime:

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

The playground keeps DevTools dependencies in its own optimizeDeps.include configuration.

FormBuilder or FormViewer components are not found

Check that the layer is declared in nuxt.config.ts:

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

Also check that the host app has the required modules:

modules: [
  'nuxt-quasar-ui',
  '@pinia/nuxt',
  '@formkit/nuxt',
]

#components imports fail

Run Nuxt prepare:

bunx nuxi prepare

Then restart the development server.

The builder loses state or mixes two forms

Use a stable and unique builder-id for each instance:

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

Autosave does not reload the expected schema

Check the storage-key and builder-id. If you use dynamic ids, local autosave keys will also change.

My existing application uses SSR

Wrap FormBuilder in <ClientOnly>:

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

~/types/form-builder does not work in the host app

Do not import internal layer paths from the host application. Use the public package export:

import type { FormBuilderSchema } from '@vevedh/qform-builder-layer/types'

FormViewer displays nothing

Check that the schema is an array:

const schema = ref<FormBuilderSchema>([])

and that it contains valid FormKit/Quasar field definitions.

The form does not submit

Listen to the submit event:

<FormViewer
  :form-fields="schema"
  v-model="values"
  @submit="handleSubmit"
/>

Global best practice

When an error occurs, isolate the problem in this order:

Nuxt modules
Layer declaration
Types and imports
builder-id
schema shape
runtime values
persistence layer

Blank page on the first Playwright test on Windows

After a full cleanup, Vite may reset its client graph while discovering a FormKit dependency. The project explicitly pre-bundles the FormKit stack in .playground/nuxt.config.ts, removes both root and playground Vite caches with bun run clean, and allows only a bounded retry for Nuxt/Vite modules failing with ERR_ABORTED or ERR_CONNECTION_RESET. HTTP, Quasar and business errors remain fatal.

For global interaction-state assertions, target [data-qform-runtime-shell] rather than [data-qform-interaction-phase] alone because field overlays also expose their phase.