Remix Forms

The repository is a monorepo managed with pnpm workspaces and Turborepo. The primary workspaces are:

• apps/web: Contains the website and an example application.
• packages/remix-forms: Contains the core Remix Forms library.

Workspace scripts are executed from the repository root using pnpm run <script>. Common scripts include:

• build: Build the project.
• dev: Start the development server.
• lint: Check code style using Biome.
• lint-fix: Automatically fix Biome linting issues.
• tsc: Run the TypeScript compiler.
• test: Run the test suite.

Remix Forms uses Playwright for testing. Before running tests, you must ensure the Playwright executables are installed.

1. Install Playwright executables: pnpm exec playwright install or pnpm run playwright:ci:install

2. Run the test suite: pnpm run test

$ pnpm exec playwright install
$ pnpm run test

To develop on the Remix Forms repository, clone the repository and use pnpm to install dependencies and start the development server.

Note: It is recommended to use Node 16 for development, as there have been issues running the Turborepo dev command on Node 18.

Running the development command will host the website at http://localhost:5173.

$ cd remix-forms
$ pnpm install
$ pnpm run dev

The react-router.config.ts file defines the server-side rendering (SSR) behavior and the list of routes to be prerendered at build time.

• ssr: A boolean indicating whether Server-Side Rendering is enabled. Set to true to enable SSR.
• prerender: An array of route paths that should be prerendered during the build process. This is useful for static content like landing pages or success pages.

import type { Config } from '@react-router/dev/config'
import { exampleRoutesToPrerender } from './app/routes'

export default {
  ssr: true,
  prerender: ['/', '/get-started', '/success', ...exampleRoutesToPrerender],
} satisfies Config

The generate function is the core programmatic entrypoint for creating new Remix Forms projects. It scaffolds a project directory based on a specified preset and writes the necessary slot files and an index.ts barrel file to the outputDir.

To use this function, you must provide a GenerateOptions object containing:

• preset: A valid PresetName (retrieved via getPreset).
• outputDir: The filesystem path where the project files should be created.

The function returns an array of strings representing the paths of all files created during the generation process.

import { generate, type GenerateOptions } from 'create-remix-forms';

const options: GenerateOptions = {
  preset: 'some-preset-name', // Must be a valid PresetName
  outputDir: './my-new-remix-app'
};

const files = generate(options);
console.log('Created files:', files);

The remix-forms library provides high-level components for building forms driven by a schema.

• SchemaForm: A component used to render a form based on a provided FormSchema.
• makeSchemaForm: A utility function to create a schema-driven form instance.

These components utilize the SchemaFormProps and RenderForm types to define how the form behaves and how its fields are rendered.

import { SchemaForm, makeSchemaForm } from 'remix-forms';

// Example usage pattern
function MyForm({ schema }: { schema: FormSchema }) {
  return <SchemaForm schema={schema} />;
}

The getPreset function allows you to programmatically retrieve a PresetConfig object by providing its PresetName. This is useful if you are extending the CLI or building tools that depend on the preset definitions.

import { getPreset } from 'create-remix-forms/presets';

const config = getPreset('tailwind');

For processing form submissions and data mutations in Remix:

• formAction: A utility for defining the action logic for a form.
• performMutation: A function to execute mutations, typically used within Remix actions or loaders.

These utilities use FormActionProps for configuration and return a MutationResult describing the outcome of the operation. UploadHandler can be used for handling file uploads during mutations.

The following types define the contract for form actions and mutation results.

export type {
  FormActionProps,
  MutationResult,
  UploadHandler,
} from './mutations'

The SlotName type defines the valid identifiers for various form component parts. These names are used to map specific UI elements (like inputs, labels, or buttons) to their corresponding styles or templates within a preset.

type SlotName = 
  | 'form'
  | 'fields'
  | 'field'
  | 'label'
  | 'input'
  | 'multiline'
  | 'select'
  | 'checkbox'
  | 'fileInput'
  | 'radio'
  | 'radioGroup'
  | 'radioLabel'
  | 'checkboxLabel'
  | 'fieldErrors'
  | 'globalErrors'
  | 'error'
  | 'button'
  | 'scalarArrayField'
  | 'scalarArrayItem'
  | 'objectArrayItem'
  | 'arrayArrayItem'
  | 'addButton'
  | 'removeButton'
  | 'arrayEmpty'
  | 'arrayTitle'
  | 'objectTitle'
  | 'objectFields'

The following options are available for the create-remix-forms command:

The following types are used to define schemas and customize the rendering of various field types (scalars, arrays, and objects) within a SchemaForm.

export type {
  AutoInputType,
  SchemaFormProps,
  ScalarFieldType,
  RenderScalarFieldProps,
  RenderScalarField,
  RenderArrayFieldProps,
  RenderArrayField,
  RenderObjectFieldProps,
  RenderObjectField,
  RenderScalarArrayItemProps,
  RenderScalarArrayItem,
  RenderObjectArrayItemProps,
  RenderObjectArrayItem,
  RenderArrayArrayItemProps,
  RenderArrayArrayItem,
  RenderFormProps,
  RenderForm,
  FormSchema,
} from './schema-form'