TypeScript generation

The swirls form gen command generates TypeScript code from the forms defined in your Swirls project. The output provides type-safe Zod schemas, a form registry, and module augmentation so that your application has full type safety when working with Swirls forms.

What gets generated

When you run swirls form gen, the CLI performs the following steps:

1. Reads your configuration from swirls.config.ts in the project root (created by swirls configure).
2. Fetches all forms that have schemas defined for the configured project. This requires an authenticated session -- run swirls auth login first.
3. Generates a TypeScript file at the path specified by genPath (defaults to src/swirls.gen.ts).

The generated file contains four sections:

Zod schemas

A Zod schema is generated for each form based on the form's JSON Schema definition. These schemas provide runtime validation and static type inference.

Form registry

A registry object that maps each form name to its name and schema. This registry is the foundation for type-safe form lookups at runtime.

registerForms() function

A function that registers every form in the registry with the SDK's internal registerForm() method. You call this once at application startup to make all forms available to the SDK hooks and components.

Module augmentation

A TypeScript module augmentation block that extends the FormRegistry interface from @swirls/sdk. This is what gives you autocompletion and type checking when you use form names in useSwirlsFormAdapter().

Integrating generated code

1. Call registerForms() at startup

Import and call registerForms() once in your application's entry point -- for example, in your root layout or main entry file. This registers all form schemas with the SDK before any form-related hooks or components are used.

import { registerForms } from './swirls.gen'

registerForms()

2. Use the SDK with type safety

After registration, the SDK hooks and components are fully typed with your project's form names and field shapes.

useSwirlsFormAdapter(formName, defaultValues) -- A headless hook that returns the form's schema, default values, and a submit function. Wire it into your preferred form library (React Hook Form, TanStack Form, or others).

const { schema, defaultValues, submit } = useSwirlsFormAdapter('contact-form')

Because the generated types are derived directly from your project's forms, formName autocompletes to valid form names and field shapes are checked at compile time. There is no need to duplicate schemas manually.

Configuration

The configuration file swirls.config.ts is created by swirls configure and uses defineConfig from @swirls/sdk/config:

import { defineConfig } from '@swirls/sdk/config'

export default defineConfig({
  projectId: '<your-project-id>',
  genPath: 'src/swirls.gen.ts',
})

Recommended workflow

1. Define forms and schemas in the Swirls Portal (or via the API). Each form should have a JSON Schema attached.
2. Run swirls form gen to fetch the latest form definitions and regenerate the TypeScript output.
3. Call registerForms() in your application entry point.
4. Use useSwirlsFormAdapter with the generated form names for type-safe form rendering and submission.

When you add, remove, or modify forms in the Portal, run swirls form gen again to keep your generated types in sync. The generated file includes a header comment indicating it was auto-generated -- do not edit it manually.

Next steps

• CLI reference -- Full list of CLI commands and options.
• Triggers -- How form triggers and schemas work in Swirls.