alepha@docs:~/docs/packages$
cat 2-@alepha-ui.md | pretty
3 min read
Last commit:

#@alepha/ui

Shared shadcn Base UI Nova components for Alepha apps. Edited directly; bugfixes propagate via normal dep updates.

#Installation

npm install @alepha/ui

#Overview

@alepha/ui is the shared component library for Alepha applications: a shadcn collection in the base-nova style, built on Base UI and Tailwind, with lucide icons.

Unlike the rest of the framework, these components are meant to be edited directly. The package ships src/ only — no dist/, no build step. Copy a component into your app and change it, or depend on the package and let bugfixes arrive through normal dependency updates.

#Import paths

Every component lives in its own directory, so the import path repeats the name:

ts 
1import { Button } from "@alepha/ui/components/ui/button";2import { AutoForm } from "@alepha/ui/components/auto-form/auto-form";3import { useToast } from "@alepha/ui/components/use-toast/use-toast";4import { cn } from "@alepha/ui/lib/utils";

Load the stylesheet once, at your app's entry point:

ts 
1import "@alepha/ui/styles.css";

#What's inside

components/ui/* — the shadcn primitives, unmodified in spirit: button, input, card, badge, dialog, sheet, tooltip, label, accordion, avatar, and the rest. Reach for these first.

Schema-driven forms — auto-form renders a complete form from a z.object() schema, driven by the $control metadata on each field. control, control-array, control-object, control-date, control-number, control-select, control-password, and control-upload are the per-type field renderers it dispatches to; use them directly when you want to lay a form out by hand.

alepha-table — data table wired for server-side pagination, sorting and filtering.

Application shells — app-shell and nav-shell for page scaffolding, app-actions for toolbars, plus ready-made auth, account, settings, and admin screens.

Hooks — use-toast and use-dialog (imperative toasts and modals) live under components/; use-mobile lives under hooks/.

lib/* — utils exports cn(), the clsx + tailwind-merge helper every component uses. Also resize-image, rehype-safe-img, and i18n-fr.

#Example

AutoForm pairs with useForm from alepha/react/form. The schema is the single source of truth — field types, validation, and layout hints all come from it:

tsx 
 1import { AutoForm } from "@alepha/ui/components/auto-form/auto-form"; 2import { z } from "alepha"; 3import { useForm } from "alepha/react/form"; 4  5const profileSchema = z.object({ 6  username: z.string().min(2).max(32).meta({ $control: { icon: "user" } }), 7  email: z.string(), 8  newsletter: z.boolean(), 9});10 11export const ProfilePage = () => {12  const form = useForm({13    schema: profileSchema,14    defaultValues: { username: "", email: "", newsletter: false },15    handler: (values) => save(values),16  });17 18  return (19    <AutoForm20      form={form}21      icon="cog"22      title="Account profile"23      autoGroup24      disabledIfPristine25    />26  );27};

autoGroup derives field groups from the schema shape; pass groups instead to lay them out yourself.

#Settings cards

layout="row" renders the same shape as the SettingsSection / SettingsRow kit rather than an approximation of it: each group becomes a bordered card of divided rows, label and help on the left, control on the right, and the action bar is the card's own last row. Each group carries its own title and description, rendered through the same SettingsHeading the kit uses.

tsx 
 1<AutoForm 2  form={form} 3  layout="row" 4  disabledIfPristine 5  groups={[ 6    { 7      title: "Name", 8      description: "How you are identified to other people.", 9      fields: ["username", "firstName", "lastName"],10    },11  ]}12/>

So a settings card whose rows are all form fields should be an AutoForm. Reach for SettingsSection directly for the rows that are not fields — an avatar picker, a read-only value, a lone button.

Add autoSave to commit on change instead, which hides the action bar. Text fields still never commit on keystroke: they commit on Enter, or on the inline tick that appears in the input once the field is dirty.

#Adding a shadcn component

components.json is configured for this package, so the shadcn CLI drops new components in the right place with the right aliases:

npx shadcn@latest add <component>