Bien démarrer

À la fin de cette page, vous aurez un formulaire construit visuellement, affiché dans votre framework et validé sur votre serveur — le tout depuis le même fichier. Cela demande une installation et une vingtaine de lignes de code.

Installation

Choisissez le package correspondant à votre application. Les wrappers de framework embarquent les Web Components et le core transitivement.

React

npm

npm install @streamline-pulse/formkrafter-react

bun

bun add @streamline-pulse/formkrafter-react

pnpm

pnpm add @streamline-pulse/formkrafter-react

yarn

yarn add @streamline-pulse/formkrafter-react

Vue

npm

npm install @streamline-pulse/formkrafter-vue

bun

bun add @streamline-pulse/formkrafter-vue

pnpm

pnpm add @streamline-pulse/formkrafter-vue

yarn

yarn add @streamline-pulse/formkrafter-vue

Web Components

npm

npm install @streamline-pulse/formkrafter-wc

bun

bun add @streamline-pulse/formkrafter-wc

pnpm

pnpm add @streamline-pulse/formkrafter-wc

yarn

yarn add @streamline-pulse/formkrafter-wc

Astuce

N’installez @streamline-pulse/formkrafter-core seul que là où il n’y a pas d’UI — un backend Node ou Bun qui valide les payloads soumis. Voir packages pour le contenu de chacun.

Construire et afficher un formulaire

Le builder produit un spec ; le renderer le consomme. Brancher les deux ensemble, c’est toute l’intégration :

1. Montez le builder et conservez le spec qu’il émet. Chaque édition déclenche specChange avec le nouveau spec — plus les patches RFC 6902 qui l’ont produit, si vous voulez de l’undo/redo ou une piste d’audit.

2. Passez ce spec au renderer. C’est du JSON pur : stockez-le, versionnez-le, récupérez-le plus tard.

3. Importez la feuille de style une fois. Elle est opt-in et pèse environ 6 Ko — ignorez-la et stylez vous-même les classes .fk-* si vous préférez.

React

FormStudio.tsx

import { useState } from 'react'
import { FkFormBuilder, FkFormRender } from '@streamline-pulse/formkrafter-react'
import '@streamline-pulse/formkrafter-wc/styles.css'
import type { BrickSpec } from '@streamline-pulse/formkrafter-core'

export function FormStudio() {
  const [spec, setSpec] = useState<BrickSpec>()

  return (
    <>
      <FkFormBuilder onSpecChange={(e) => setSpec(e.detail.spec)} />

      {spec && (
        <FkFormRender
          spec={spec}
          onFormSubmit={(e) => console.log(e.detail.data)}
        />
      )}
    </>
  )
}

Vue

FormStudio.vue

<script setup lang="ts">
import { ref } from 'vue'
import { FkFormBuilder, FkFormRender } from '@streamline-pulse/formkrafter-vue'
import '@streamline-pulse/formkrafter-wc/styles.css'
import type { BrickSpec } from '@streamline-pulse/formkrafter-core'

const spec = ref<BrickSpec>()

function onSubmit(data: Record<string, unknown>) {
  console.log(data)
}
</script>

<template>
  <FkFormBuilder @spec-change="spec = $event.detail.spec" />

  <FkFormRender
    v-if="spec"
    :spec="spec"
    @form-submit="onSubmit($event.detail.data)"
  />
</template>

Web Components

index.html

<fk-form-builder></fk-form-builder>
<fk-form-render></fk-form-render>

<script type="module">
  import '@streamline-pulse/formkrafter-wc/dist/formkrafter-wc/formkrafter-wc.esm.js'
  import '@streamline-pulse/formkrafter-wc/styles.css'

  const builder = document.querySelector('fk-form-builder')
  const preview = document.querySelector('fk-form-render')

  builder.addEventListener('specChange', (e) => {
    preview.spec = e.detail.spec
  })

  preview.addEventListener('formSubmit', (e) => {
    console.log(e.detail.data)
  })
</script>

Valider côté serveur

Le verdict du navigateur est un confort pour vos utilisateurs ; le verdict du serveur est celui qui compte. Les deux viennent du même spec :

server/submit.ts

import { validateFormData } from '@streamline-pulse/formkrafter-core'
import type { BrickSpec } from '@streamline-pulse/formkrafter-core'

export async function submit(spec: BrickSpec, payload: unknown) {
  const { valid, errors } = validateFormData(spec, payload, 'fr')

  if (!valid) {
    // { fullName: 'Ce champ est obligatoire', 'contacts[0].email': 'Email invalide' }
    return { status: 422, errors }
  }

  return { status: 200, data: payload }
}

Attention

Les champs cachés par une règle sont exclus de la validation des deux côtés, et les chaînes vides comptent comme manquantes. C’est pourquoi réimplémenter ce contrôle à la main sur le backend finit généralement par diverger du frontend — utilisez validateFormData.

Étapes suivantes

Specs de formulaireLa forme d'un BrickSpec, les ops qui l'éditent et les patches pour l'undo/redo.

BricksLes 30 bricks intégrées, et comment enregistrer les vôtres.

Référence des composantsToutes les props, tous les événements et toutes les méthodes du builder et du renderer.

Règles dynamiquesVisibilité conditionnelle et valeurs calculées, sans eval.

Démo liveLe vrai builder qui tourne dans la page, plus les applications de démo complètes.

Vous venez de Form.ioConvertir des définitions existantes et voir ce que la migration vous apporte.