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.
With declaration
Section titled “With declaration”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
Section titled “With isolatedDeclarations”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.
Compose an exported recipe
Section titled “Compose an exported recipe”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.
Wrap recipes in a function
Section titled “Wrap recipes in a function”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.
A function generic over a config
Section titled “A function generic over a config”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>>.
When the configs compose recipes
Section titled “When the configs compose recipes”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
Section titled “Write the return type”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.”
Next steps
Section titled “Next steps”- Composing recipes explains how the configs of composed recipes merge.
- Typing recipes types component props from a recipe, and a config declared before the call.
- All exports lists every type.