@techzyapp/ui-library

Techzy UI — a reusable, framework-agnostic React component library and the shared UI foundation for Techzy admin panels. Ships ~80 components plus a batteries-included admin shell (sidebar + header + routing), theming, and built-in UI localization.

• React 19 (peer >=18), TypeScript (strict), CSS Modules, dual ESM/CJS.
• Theming via ConfigProvider — 9 palette colors, light/dark, per-mode accent, custom fonts.
• i18n out of the box — the panel ships translated in 7 languages (en · ka · es · de · it · fr · ru); just list the ones you want.
• Batteries included — Table, RichTextEditor, FileUploader (with a built-in ImageEditor), date/time pickers, the admin shell, and more.

Install

npm i @techzyapp/ui-library

react / react-dom are required peers. The rest are optional peers only in the npm sense (npm won't install them for you): the component barrels import most of them statically, so a missing one breaks the build even if no page uses that component — install them all. Only shiki, libphonenumber-js and qrcode.react load lazily (skip them if you don't use CodeBlock / PhoneField / QrCode), and zod is type-only in the library (skip it if you have no forms). CONSUMER.md §1 has the install commands and known-good versions.

| Feature | Peer dependency | | -------------------------------------- | --------------------------------------------------------------- | | Forms (useForm) | zod | | Admin shell (RootLayout / Sidebar) | @tanstack/react-router | | Table | @tanstack/react-table | | Date/time pickers | dayjs | | RichTextEditor | lexical + @lexical/* | | FileUploader | react-dropzone, @dnd-kit/*, @formkit/auto-animate | | Table row reorder | @dnd-kit/* | | CodeBlock | shiki | | PhoneField | libphonenumber-js | | QrCode | qrcode.react | | LocationPicker | none — loads Google Maps itself (key from config.maps.apiKey) | | ImageEditor | none |

Scaffold a whole project (fastest)

Building a new admin panel from scratch? The repo ships STARTER.md — a step-by-step guide for Claude Code. Drop it into an empty folder (with CONSUMER.md and COMPONENTS.md), tell Claude Code to "build the project from STARTER.md," and it scaffolds a clean Vite + TanStack Router app wired to this library — theming, routing, auth, an API client and a demo Example Page — with the boilerplate removed. Then keep CONSUMER.md at the repo root as CLAUDE.md (the assistant's reference for building pages, forms, and the admin shell) and COMPONENTS.md as docs/ui-library-components.md.

For a manual / existing-project setup, follow the steps below.

Setup

Import the two stylesheets once at your app entry, then wrap the app in ConfigProvider:

// main.tsx
import '@techzyapp/ui-library/css/reset.css'
import '@techzyapp/ui-library/css/styles.css'

import { ConfigProvider, type Config } from '@techzyapp/ui-library/theme'

const config: Config = {
  theme: { mode: 'light' },
  // the panel ships en + ka + es + de + it + fr + ru — listing them is all it takes
  i18n: {
    languages: [
      { code: 'en-US', label: 'English' },
      { code: 'ka-GE', label: 'ქართული' },
    ],
  },
}

export function App() {
  return <ConfigProvider config={config}>{/* your app / router */}</ConfigProvider>
}

ConfigProvider injects the theme's color variables before first paint, so it must wrap anything that uses the components.

Quick example

import { Button, Card, TextField } from '@techzyapp/ui-library/components'
import { Icon } from '@techzyapp/ui-library/icons'

function SignInCard() {
  return (
    <Card title="Sign In" icon="User">
      <TextField label="Email" placeholder="[email protected]" />
      <TextField label="Password" type="password" />
      <Button fullWidth startIcon={<Icon name="Login" />}>
        Continue
      </Button>
    </Card>
  )
}

Localizing your own text

useTranslations() binds your app's copy to the same language switcher the panel uses:

import { useTranslations } from '@techzyapp/ui-library/i18n'

// config.i18n.appMessages = { en: { 'welcome': 'Welcome' }, ka: { 'welcome': 'მოგესალმებით' } }
const t = useTranslations()
;<h1>{t('welcome')}</h1>

Subpath exports

Import from the scoped surfaces (the root . re-exports everything too):

| Import | What's in it | | --------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | | @techzyapp/ui-library/components | every component + the admin shell + Form | | @techzyapp/ui-library/components/<Name> | a single component | | @techzyapp/ui-library/hooks | useForm, useTableQuery, useQueryModal, useDisclosure, useMediaQuery, useBreakpointMatches, useClipboard, useLockBodyScroll, useAccessKeys | | @techzyapp/ui-library/theme | ConfigProvider, useTheme, config types, applyTheme | | @techzyapp/ui-library/i18n | useT, useTranslations, useLanguage + message types | | @techzyapp/ui-library/icons | Icon, IconName, ICON_NAMES, loadIcon / preloadIcons (lazy icons) | | @techzyapp/ui-library/helpers | RBAC + translation + Table query helpers + palette / contrast | | @techzyapp/ui-library/auth | AuthGuard, authLayoutRoute (TanStack-Router auth gating), useAuthRedirect / getAuthRedirect / clearAuthRedirect (back to the page after sign-in) | | @techzyapp/ui-library/app | AdminRoot — the whole admin root route (shell + guard + session gate + Toaster) | | @techzyapp/ui-library/css/reset.css · /css/styles.css | the two stylesheets |

Subpath imports need moduleResolution: "bundler" or "node16" in your tsconfig; the root import works on classic "node" too.

License

MIT © Techzy