Skip to content

Exporting and wrapping recipes

A library of components often keeps a recipe in one module and composes it in others. For example, a base look for every button-like element lives in one module, and the button, the toggle, and the link compose it. Each module then exports a recipe, and the library’s declarations hold its type. A library may also create its recipes with a function of its own, which passes each config on to cva or sva.

A module that exports a recipe needs nothing more than "declaration": true. TypeScript writes the type of the recipe with the types that class-recipe exports, such as RecipeComposition. The library depends on @lynstack/class-recipe only, even when its package manager, such as pnpm, keeps @lynstack/recipe out of its reach.

If such a module fails with TS2883 (TS2742 before TypeScript 7), which says that the inferred type of the recipe cannot be named without a reference to @lynstack/recipe, update class-recipe to 1.6.0 or newer.

With "isolatedDeclarations": true, TypeScript requires that the declarations of each file can be written from that file alone, as oxc and the tools built on it, such as tsdown, write them. Such a tool cannot know what a call returns, so each recipe that a module exports needs a type annotation; without one, TypeScript reports TS9010.

SlotRecipeOf and RecipeOf give that type from the type of the config. Declare the config as const, which isolated declarations can read, and annotate the recipe with typeof the config:

import type { SlotRecipeOf } from "@lynstack/class-recipe";
import { sva } from "@lynstack/class-recipe";
const lookConfig = {
slots: ["root"],
base: { root: "inline-flex items-center rounded-md border" },
variants: {
size: { sm: { root: "h-8 px-2" }, md: { root: "h-10 px-4" } },
},
defaultVariants: { size: "md" },
} as const;
export const look: SlotRecipeOf<typeof lookConfig> = sva(lookConfig);
look()→ { root: "inline-flex items-center rounded-md border h-10 px-4" }look({ size: "sm" })→ { root: "inline-flex items-center rounded-md border h-8 px-2" }

SlotRecipeOf<typeof lookConfig> is the type that sva(lookConfig) returns, the same that TypeScript infers. The modules that use look see its slots, its variants, and its defaults.

For a recipe of cva, use RecipeOf in the same way:

import { cva } from "@lynstack/class-recipe";
import type { RecipeOf } from "@lynstack/class-recipe";
const pillConfig = {
base: "rounded-full px-2 text-xs",
variants: { tone: { neutral: "bg-gray-100", danger: "bg-red-100" } },
} as const;
export const pill: RecipeOf<typeof pillConfig> = cva(pillConfig);

A recipe that a module keeps to itself needs no annotation.

Isolated declarations cannot read the type of a recipe that a config lists, so leave composes out of the config. Spread the config into the call with composes, and pass the types of the recipes it composes, in the same order, as the second type parameter:

import type { SlotRecipeOf } from "@lynstack/class-recipe";
import { sva } from "@lynstack/class-recipe";
import { look } from "./look.ts";
const toggleConfig = {
slots: ["icon"],
variants: {
pressed: {
false: { icon: "opacity-50" },
true: { root: "bg-gray-100", icon: "opacity-100" },
},
},
} as const;
export const toggle: SlotRecipeOf<typeof toggleConfig, readonly [typeof look]> =
sva({ ...toggleConfig, composes: [look] });
toggle({ pressed: true })→ {    root: "inline-flex items-center rounded-md border h-10 px-4 bg-gray-100",    icon: "opacity-100",  }toggle({ size: "sm" })→ {    root: "inline-flex items-center rounded-md border h-8 px-2",    icon: "opacity-50",  }

toggle accepts the variants of look and its own, and has the slots of both. RecipeOf and SlotRecipeOf reject a config that lists composes, so that the type cannot leave out the recipes it composes.

A function of yours that creates recipes, such as a helper that a library gives its users, is generic over the variants of the config, not over the whole config. RecipeOf and SlotRecipeOf do not apply in such a function: they need a config whose type is known where the recipe is declared, and TypeScript cannot infer the variants of a config whose type is a type parameter.

Type the variants and the names with a default as const type parameters, and the recipe as a Recipe of their RecipeProps:

import { cva } from "@lynstack/class-recipe";
import type {
Recipe,
RecipeConfig,
RecipeProps,
RecipeVariants,
} from "@lynstack/class-recipe";
function define<
const Variants extends RecipeVariants,
const DefaultedName extends keyof Variants = never,
>(
config: RecipeConfig<Variants, DefaultedName>,
): Recipe<RecipeProps<Variants, DefaultedName>> {
return cva(config);
}

A slot recipe’s helper does the same with SlotRecipeConfig, and returns a SlotRecipe<Slot, SlotRecipeProps<Slot, Variants, DefaultedName>>.

define takes no composes: its Recipe has the variants of its own config only, and other recipes cannot compose it. A helper whose configs compose recipes takes the recipes as a third type parameter, and returns the type of cva for its type parameters, which has the variants and defaults of the recipes it composes:

import { cva } from "@lynstack/class-recipe";
import type {
ComposableKindRecipe,
ComposedVariants,
RecipeConfig,
RecipeVariants,
} from "@lynstack/class-recipe";
function defineComposed<
const Variants extends RecipeVariants,
const DefaultedName extends keyof ComposedVariants<Composed, Variants> =
never,
const Composed extends readonly ComposableKindRecipe<string>[] = readonly [],
>(
config: RecipeConfig<Variants, DefaultedName, Composed>,
): ReturnType<typeof cva<Variants, DefaultedName, Composed>> {
return cva(config);
}

A slot recipe’s helper does the same with SlotRecipeConfig, ComposableKindSlotRecipe<string>, and ReturnType<typeof sva<Slot, Variants, DefaultedName, Composed>>.

A function that takes a recipe rather than a config, such as one that lists the options of each variant for a story, is typed in A function that takes any recipe.

Write the return type of a helper, as define and defineComposed do, rather than leaving it to TypeScript. TypeScript can write the declaration of a helper without one, but it then spells out the type of the recipe, whose size depends on the recipes that the config composes and on the version of TypeScript that writes it. A declaration that names the return type stays small. For example, when TypeScript 5.8 writes the declaration of a helper that composes a recipe of its library, a project on TypeScript 5.8 that calls the helper fails with TS2589, “Type instantiation is excessively deep and possibly infinite.”