Cloudwick Form Builder

Form Builder for Cloudwick

Version - 1.0.9

Installation

Option 1: CLI Installation (Recommended)

Install individual components using our CLI tool, similar to shadcn/ui:

# Initialize in your project
npx @cloudwick-formick/cli init

# Add specific components
npx @cloudwick-formick/cli add form-builder
npx @cloudwick-formick/cli add form-previewer

# Or use the short alias
npx cloudwick-ui add form-builder

Option 2: Package Installation

Install the entire package in your project directory with:

# With npm:
npm i @cloudwick-formick/core

# With yarn:
yarn add @cloudwick-formick/core

Requirements

This package has the following peer dependencies:

• React ^18.3.1
• React DOM ^18.3.1
• Node ^20.16.0
• Tailwind CSS ^3.4.13

Available Components

Package provides the following components:

• FormBuilder - Complete form building interface with drag-and-drop
• Form - Preview and render forms
• FormTheme - Theme customization components
• shared - Shared utility components

CLI Commands

init

Initialize Cloudwick FormBuilder support files, Tailwind hooks, utilities, and config.

npx cloudwick-ui init

This command:

• Writes/updates cloudwick-ui.json
• Ensures src/components, src/lib, src/constants, src/utils, src/hooks, src/mocks, and src/assets exist
• Generates the cn, generateId, and generateIdWithPrefix helpers under src/lib/utils.ts
• Copies all supporting constants, hooks, theme helpers, and schema utilities from the registry
• Adds Astral UI CSS imports to your main entry file when present
• Attempts to inject alias configuration into vite.config.(ts|js) and tsconfig.json
• Installs core dependencies: @cloudwick/astral-ui, @dnd-kit/*, use-immer, zod, tailwind-merge, clsx, react-signature-canvas, and libphonenumber-js

| Option | Alias | Description | |--------|-------|-------------| | --yes | -y | Skip prompts and use defaults | | --cwd <dir> | -c | Run initialization in another directory |

add

Add one or more components (including FormBuilder) to your project.

npx cloudwick-ui add formbuilder
npx cloudwick-ui add formbuilder form-previewer form-theme

Behavior:

• Auto-runs init if cloudwick-ui.json is missing
• Resolves component dependencies (for example, formbuilder brings shared utilities and supporting UI wrappers)
• Copies files into the alias-backed src/components tree, preserving nested directories
• Transforms import paths to respect your alias preferences (@formickComponents, @formickUtils, etc.)
• Installs any external npm packages declared by the component
• Creates missing index.ts barrels and stub folders for FormBuilder internals

| Option | Alias | Description | |--------|-------|-------------| | --yes | -y | Bypass overwrite prompts | | --overwrite | -o | Force-write files even if they exist | | --cwd <dir> | -c | Target another working directory | | --path <path> | -p | Place the component in a custom folder |

Tip: Running npx cloudwick-ui add without arguments opens an interactive multi-select list of available components.

list

Display every component bundled with the registry, including FormBuilder and its companions.

npx cloudwick-ui list

Output includes the file count, npm dependencies, and internal dependencies so you know what will be installed before running add.

Quick Start

# 1. Initialize (creates cloudwick-ui.json, aliases, utilities, and Tailwind glue)
npx cloudwick-ui init

# 2. Add FormBuilder and any related components
npx cloudwick-ui add formbuilder form-previewer form-theme

# 3. Confirm Astral UI CSS imports were injected
npx cloudwick-ui init --yes   # reruns setup, safe if you need to reapply styles

# 4. Start building
import FormBuilder from '@formickComponents/formbuilder/FormBuilder';

Recommended Workflow

1. Initialize once per repo – runs scaffolding, ensures src/constants, src/utils, src/hooks, and Astral UI CSS imports exist.
2. Review cloudwick-ui.json – adjust Tailwind paths or alias targets if your layout differs.
3. Add components – formbuilder, form-previewer, form-theme, and shared helpers as needed.
4. Wire aliases – verify tsconfig.json/vite.config.* picked up the @formick* prefixes or add them manually.
5. Import & customize – hook the FormBuilder context to your data layer, extend field definitions, or align styles with your Tailwind token strategy.

FormBuilder Component Overview

The FormBuilder component provides a comprehensive drag-and-drop form building experience with:

• Drag-and-drop layouting via @dnd-kit/core with contextual spacer logic for precise placement
• Multi-page orchestration with automatic page splitting, page-break layouts, and dynamic renumbering
• Field, layout, header, and page inspectors tied to the shared formPagesContext
• Conditional logic editors, modal UX, and validation builders powered by zod schemas
• Theme management through the embedded FormTheme component (colors, typography, spacing) plus live preview
• Runtime rendering by delegating to @components/shared/FormRenderer, ensuring parity between builder and embed experience
• Notification hooks using the Astral UI Toast

Basic Usage

import React from 'react';
import FormBuilder, { formPagesContext } from '@formickComponents/formbuilder/FormBuilder';
import { DEFAULT_FORM_CONFIG } from '@formickConstants';

export default function FormBuilderScreen() {
  return (
    <formPagesContext.Provider value={{ initialConfig: DEFAULT_FORM_CONFIG }}>
      <FormBuilder />
    </formPagesContext.Provider>
  );
}

Previewing a Saved Form

import FormRenderer from '@formickComponents/shared/FormRenderer';
import type { IFormConfig } from '@formickComponents/formbuilder/types';

export function LivePreview({ config }: { config: IFormConfig }) {
  return <FormRenderer formConfig={config} readOnly />;
}

Documentation

Import Paths

Using CLI (Recommended)

When using the CLI, components are copied to your project and you import them locally:

// After running: npx cloudwick-ui add form-builder
import { FormBuilder } from '@/components/ui/form-builder';

Using Package Installation

You can import components from the main package:

// Import from the main package
import { FormBuilder } from '@cloudwick-formick/core';

Configuration (cloudwick-ui.json)

Created during init and located at the project root:

{
  "style": "default",
  "rsc": false,
  "tsx": true,
  "tailwind": {
    "config": "tailwind.config.js",
    "css": "src/app/globals.css",
    "baseColor": "slate",
    "cssVariables": true,
    "prefix": ""
  },
  "aliases": {
    "components": "@formickComponents",
    "utils": "@formickUtils",
    "ui": "@formickComponents"
  }
}

You can tailor the Tailwind config path, CSS entry, color strategy, or alias names. Re-run npx cloudwick-ui init --yes anytime to regenerate supporting files without losing manual tweaks.

Path Aliases & Utilities

init attempts to register the following aliases in both tsconfig.json and vite.config.* (if present):

• @formickComponents → src/components
• @formickUtils → src/utils
• @formickConstants → src/constants
• @formickHooks, @formickAssets, @formickMocks, and @formickTypes

If your framework uses a different config (e.g., Next.js app dir, CRA with jsconfig.json, Angular's tsconfig.app.json), replicate the mappings manually.

The generated src/lib/utils.ts exposes the cn, generateId, and generateIdWithPrefix helpers that the builder relies on—import them via @formickUtils.

Styling & Tailwind Integration

• init injects Astral UI CSS imports into your main entry file so every copied component renders with the correct base styles and fonts
• Tailwind tokens (colors, spacing, typography) are referenced throughout the builder. Keep the generated CSS variables in your global stylesheet or map them to your design system
• FormTheme writes updates to the contextual theme object—use useThemeStyles to read/write theme overrides or persist them to your backend
• If you already have a tailor-made Tailwind setup, disable automatic CSS variables during init and wire the generated CSS_DEFAULTS, STYLE_UTILS, and color maps to your palette

Troubleshooting

• Path alias errors – rerun npx cloudwick-ui init --yes or manually add the aliases to your bundler and TypeScript config. Confirm your IDE picks up cloudwick-ui.json for guidance
• Missing styles or fonts – ensure the Astral UI CSS imports live in your entry file and that Tailwind processes the generated CSS file. Remember to restart the dev server after init
• Dependency conflicts – the CLI installs the minimum versions required by FormBuilder. If your workspace already has newer versions, prefer letting your package manager dedupe; otherwise, pin them in package.json
• Overwrite prompts – pass --yes --overwrite to re-sync the component files when you pull new updates from the registry

Why Use the CLI?

• Own Your Code: Components are copied to your project, so you can modify them
• No Lock-in: You're not dependent on our package versions
• Better Performance: No external dependencies in production
• Customizable: Modify components to fit your exact needs
• Type Safety: Full TypeScript support with your project's configuration