Skip to content

Exporting and wrapping recipes

A library of components often keeps a recipe in one module and composes it in others. 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 the recipe creator.

A module that exports a recipe needs nothing more than "declaration": true. TypeScript writes the type of the recipe with the types that native-recipe exports, such as RecipeComposition. The library depends on @lynstack/native-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 native-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.

StyleRecipeOf and SlotStyleRecipeOf 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 { StyleRecipeOf } from "@lynstack/native-recipe";
import { createStyleRecipe } from "@lynstack/native-recipe";
const boxConfig = {
base: { borderRadius: 8 },
variants: {
size: { sm: { padding: 4 }, md: { padding: 8 } },
},
defaultVariants: { size: "md" },
} as const;
export const box: StyleRecipeOf<typeof boxConfig> =
createStyleRecipe(boxConfig);
box()→ { borderRadius: 8, padding: 8 }box({ size: "sm" })→ { borderRadius: 8, padding: 4 }

StyleRecipeOf<typeof boxConfig> is the type that createStyleRecipe(boxConfig) returns, the same that TypeScript infers, with the style it returns. SlotStyleRecipeOf does the same for createSlotStyleRecipe. 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 { StyleRecipeOf } from "@lynstack/native-recipe";
import { createStyleRecipe } from "@lynstack/native-recipe";
import { box } from "./box.ts";
const cardConfig = {
variants: { raised: { true: { elevation: 2 } } },
} as const;
export const card: StyleRecipeOf<typeof cardConfig, readonly [typeof box]> =
createStyleRecipe({ ...cardConfig, composes: [box] });
card({ raised: true })→ { borderRadius: 8, padding: 8, elevation: 2 }

StyleRecipeOf and SlotStyleRecipeOf reject a config that lists composes, so that the type cannot leave out the recipes it composes.

ThemedStyleRecipeOf and ThemedSlotStyleRecipeOf take the type of a themed recipe’s config function, and read the theme type from its parameter. So a declared config function takes (theme: Theme) and reads the tokens from theme, not from themeToken, which is for configs written in the call (see Writing the config function). Isolated declarations cannot infer a value read from the theme, so assert the type of each one, and return the config as const:

import { createThemedRecipes } from "@lynstack/native-recipe";
import type { ThemedStyleRecipeOf } from "@lynstack/native-recipe";
import type { Theme } from "./theme";
const { createStyleRecipe } = createThemedRecipes<Theme>();
const chipConfig = (theme: Theme) =>
({
base: { borderRadius: theme.radius as Theme["radius"] },
variants: {
tone: {
primary: { backgroundColor: theme.primary as Theme["primary"] },
muted: { opacity: 0.6 },
},
},
}) as const;
export const chip: ThemedStyleRecipeOf<typeof chipConfig> =
createStyleRecipe(chipConfig);

A themed recipe composes the recipe of its theme, which withTheme returns. Spread the config into a function that adds composes, and pass the themed recipes it composes as the second type parameter:

const badgeConfig = (theme: Theme) =>
({
variants: { size: { sm: { padding: theme.gap as Theme["gap"] } } },
}) as const;
export const badge: ThemedStyleRecipeOf<
typeof badgeConfig,
readonly [typeof chip]
> = createStyleRecipe((theme: Theme) => ({
...badgeConfig(theme),
composes: [chip.withTheme(theme)],
}));

A lint rule such as no-unnecessary-type-assertion may report these assertions as unneeded, since the type checker knows the type of each token. Isolated declarations need them: keep them, and turn the rule off for the files that declare themed recipes.

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. StyleRecipeOf and the other …Of types 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.

Take the parts of the config that TypeScript infers as const type parameters, pass them on to StyleRecipeConfig, and return the type that createStyleRecipe returns for them:

import { createStyleRecipe } from "@lynstack/native-recipe";
import type {
NativeStyle,
StyleCompoundVariant,
StyleRecipeConfig,
StyleRecipeVariants,
} from "@lynstack/native-recipe";
function define<
const Variants extends StyleRecipeVariants,
const Base extends NativeStyle = never,
const Compounds extends readonly StyleCompoundVariant<NoInfer<Variants>>[] =
readonly [],
const DefaultedName extends keyof Variants = never,
>(
config: StyleRecipeConfig<Variants, Base, Compounds, DefaultedName>,
): ReturnType<
typeof createStyleRecipe<Variants, Base, Compounds, DefaultedName>
> {
return createStyleRecipe(config);
}

Base and Compounds are the types of base and compoundVariants. Passing them on keeps the properties of the style that the recipe returns, so TypeScript still checks that a text style goes only to a Text (see The style a recipe returns).

A slot recipe’s helper does the same with SlotStyleRecipeConfig, whose first type parameter is Slot, SlotStyleCompoundVariant, and ReturnType<typeof createSlotStyleRecipe<Slot, Variants, Base, Compounds, DefaultedName>>, with Base extends SlotStyles<string>.

define takes no composes: its recipe has the variants of its own config only. A helper whose configs compose recipes takes them as a last type parameter, Composed. The defaults and the compound variants may name the variants of the recipes it composes, so they take ComposedVariants<Composed, Variants>:

import { createStyleRecipe } from "@lynstack/native-recipe";
import type {
ComposableKindRecipe,
ComposedVariants,
NativeStyle,
StyleCompoundVariant,
StyleRecipeConfig,
StyleRecipeVariants,
} from "@lynstack/native-recipe";
function defineComposed<
const Variants extends StyleRecipeVariants,
const Base extends NativeStyle = never,
const Compounds extends readonly StyleCompoundVariant<
NoInfer<ComposedVariants<Composed, Variants>>
>[] = readonly [],
const DefaultedName extends keyof ComposedVariants<Composed, Variants> =
never,
const Composed extends readonly ComposableKindRecipe<NativeStyle>[] =
readonly [],
>(
config: StyleRecipeConfig<Variants, Base, Compounds, DefaultedName, Composed>,
): ReturnType<
typeof createStyleRecipe<Variants, Base, Compounds, DefaultedName, Composed>
> {
return createStyleRecipe(config);
}

A slot recipe’s helper does the same with SlotStyleRecipeConfig, ComposableKindSlotRecipe<NativeStyle>, and ReturnType<typeof createSlotStyleRecipe<Slot, Variants, Base, Compounds, 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.