Blackwork

Migrate from 0.11 to 0.12

Upgrade an existing Blackwork 0.11 app to 0.12.

Migrate from 0.11 to 0.12

Follow the changes in this order: upgrade the packages, update the style entry, move form state to TanStack Form, then replace removed icon imports. Run the app after each group so a styling issue is not confused with an API change.

Upgrading from Blackwork 0.11 requires changes to Tailwind styles, form dependencies, and icon imports. For a new project, start with Getting Started.

Upgrade Blackwork and Tailwind CSS first:

Bash
pnpm add blackwork@^0.12 tailwindcss@^4

If the app uses blackwork/form, also install TanStack Form:

Bash
pnpm add @tanstack/react-form

Composition

Triggers such as DialogTrigger and SheetTrigger still accept asChild. Use a <button> or Button as the child and apply styles directly to it. Extra wrapping elements can interfere with the trigger.

Button still supports loading. SheetContent still supports closeButtonVisible.

Forms

blackwork/form is built on TanStack Form.

  1. Install @tanstack/react-form.
  2. Remove react-hook-form once no other code in the project depends on it.
  3. Use useAppForm, Form, and FieldGroup as shown in Form.

Field layout (Field, FieldLabel, FieldGroup) can still be used without any form library.

Icons

The blackwork/icons subpath is removed. Import generic icons from lucide-react. See Icons for the name mapping.

Styles

Blackwork 0.12 requires Tailwind CSS v4. Remove blackwork/tailwind-config and the legacy Tailwind plugin setup, then import:

CSS
@import 'tailwindcss';
@import 'blackwork/tailwind.css';

After the migration, check the root layout in both themes and verify any asChild trigger still passes props to a real button or link.