Skip to contentAsheeUIAsheeUI

Migrating to the portable umbrella

What left `asheeui` when it became the intersection, where each name went, and how to move a shared file onto the portable surface.

asheeui used to be export * over each renderer. It offered 791 names on the web branch and 1053 on the native branch, and a shared file compiled against whichever branch TypeScript resolved and found undefined on the other. It now offers 182 names — the intersection both renderers publish under the same name and contract — and a web-only or native-only name is a compile error.

This guide is the narrowing, from the consumer's side. The batch plan and the reports are the record; this page is what changes in your code.

The rule

A name is on the umbrella only if PORTABLE_API in @asheeui/core lists it. Everything else stays with the renderer that owns it:

import { Button, Typography, useTheme } from "asheeui";        // portable
import { Breadcrumb } from "@asheeui/web";                     // web-only
import { RowList, TabBar } from "@asheeui/native";             // native-only

To see the exact list, run the guard from a checkout:

node scripts/check-umbrella.mjs --list          # the umbrella's 182 names
node scripts/check-umbrella.mjs                 # the six assertions, blocking

What left the umbrella

Category Examples Where it went
Web-only components Breadcrumb, BreadcrumbItem, BreadcrumbLink, ResizableScreen @asheeui/web
The keyboard family KeyboardProvider, OnScreenKeyboard, useKeyboard, KeyboardLayouts, KEYBOARD_CONTAINER_ATTRIBUTE @asheeui/web (the matrix calls it not-applicable on a device)
Native-only components RowList, TabBar @asheeui/native
Class dictionaries BUTTON_SIZE_CLASS, ALERT_ICON_CLASS, NATIVE_BUTTON_SIZE_CLASS the renderer that compiles them
Per-component fallbacks and defaults FALLBACK_BUTTON_CONFIG, defaultButtonConfig the renderer that states the values
Per-component config and prop types ButtonConfig, ButtonProps, AccordionConfig the renderer that states them (the shared ones are on asheeui or @asheeui/core)
Renderer internals ViewRef, classNames, paletteVariables, colorChannels, verifyNativeWind, Native* aliases the renderer that owns them
The compatibility matrix COMPONENT_SUPPORT, findComponentSupport, PlatformSupport @asheeui/core/dev

If a name you used is in a web-only list, the replacement is the same name from @asheeui/web; the same is true for the native column. The umbrella did not rename anything to make the narrowing work.

The names that changed shape

  • Text and Typography are one component. Both renderers export both names, and so does the umbrella; Text is no longer an alias the umbrella states. TextProps and TypographyProps are the same type.
  • Dropdown and Dropmenu are one component. The matrix classifies Dropmenu; both renderers export Dropdown as the documentation name. Both are portable.
  • ButtonLinkProps / CardLinkProps / SidebarLinkProps are the substitution types; a router substitute is typed by LinkSubstitution from asheeui.

Importing a renderer on purpose

An application that knows its platform may import a renderer directly. The umbrella exists for code that does not know. Two legitimate cases:

// A web-only screen: the skip link and the breadcrumb are web concepts.
import { SkipLink } from "@asheeui/web/section-kit";
import { Breadcrumb } from "@asheeui/web";

// A native-only screen: the platform's row list.
import { RowList } from "@asheeui/native";

A shared package that needs a platform API should not import a renderer. If it must, it opts in with customConditions: ["react-native"] and accepts that it now compiles against one branch:

{ "compilerOptions": { "customConditions": ["react-native"] } }

The install story changed too

  • The renderers are optional peers. npm i asheeui installs @asheeui/core and no renderer; install the renderer you build for.
  • The stylesheet is asheeui/styles (one line, which imports the web renderer's CSS).
  • The section kit is asheeui/section-kit, exporting ActionGroup and SectionHeading. SkipLink stays on @asheeui/web/section-kit.
  • The Tailwind peer range is >=3.4.0; web uses 4, native uses NativeWind on 3.

Checking a migration

pnpm build                       # the umbrella's entries and the renderers' dist
pnpm check:types                 # a shared file that uses a removed name fails here
node scripts/check-umbrella.mjs  # the surface is exactly the portable list

The narrowing is a major release of asheeui. The changelog lists the removed categories; the guard is the exact list.