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.
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 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
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.
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.
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 { 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.
Themed recipes
Section titled “Themed recipes”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.
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. 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.
A function generic over a config
Section titled “A function generic over a config”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>.
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. 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
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.
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.