Dokumentation
Installation
StabilDie Library in eine React-Anwendung einbinden: GitHub-Packages-Token, Styles, Provider und Peer-Abhängigkeiten.
@neodin-eu/ui liegt in GitHub Packages. Die Anwendung braucht dafür drei
Dinge: die Registry in einer eingecheckten .npmrc, ein persönliches Token in
der Benutzer-Konfiguration und danach den normalen pnpm add. Diese Seite
führt einmal durch die Einrichtung und zeigt, wie Styles und Provider ins
Root-Layout kommen.
Voraussetzungen
- Node.js 24 und pnpm 12 (über Corepack:
corepack enable). - React 19.3 mit React DOM 19.3.
- Tailwind CSS 4; die Tokens und Basis-Styles kommen als CSS-Datei mit dem Paket.
Registry eintragen
Ins Repository gehört genau eine Zeile, die den Scope auf GitHub Packages zeigt. Sie enthält kein Token:
@neodin-eu:registry=https://npm.pkg.github.comDiese Zeile steht in der eingecheckten .npmrc der Anwendung. Mehr braucht es
dort nicht; alle Zugangsdaten bleiben außerhalb des Repositories.
Token in der Benutzer-Konfiguration
pnpm 12 ignoriert Zugangsdaten aus einer eingecheckten .npmrc. Das ist
Absicht: Ein Token in einer Repo-Datei könnte an eine fremde Registry gelangen.
Deshalb legst du einmalig pro Rechner ein Token nur mit read:packages an
(GitHub → Settings → Developer settings → Personal access tokens) und
speicherst es in der Benutzer-Konfiguration von pnpm:
pnpm config set "//npm.pkg.github.com/:_authToken" "<token>"Ein Token sieht aus wie ghp_…; es gehört in deine Benutzer-Konfiguration und
nie in das Repository, in eine .env-Datei oder in ein Docker-Image. Für CI
übergibst du es als Variable, die pnpm unter dem Schlüssel
npm_config_//npm.pkg.github.com/:_authToken liest:
env "npm_config_//npm.pkg.github.com/:_authToken=$NODE_AUTH_TOKEN" pnpm install --frozen-lockfileDocker-Builds
Im Image darf kein Token liegen. Der Build holt es einmalig über ein
BuildKit-Secret, pnpm bekommt es für diesen einen RUN-Schritt über die
npm_config_…-Variable. Das Dockerfile beginnt dafür mit der Zeile
# syntax=docker/dockerfile:1; der entscheidende Abschnitt sieht so aus wie in
der Support-App:
RUN --mount=type=secret,id=node_auth_token,env=NODE_AUTH_TOKEN \
env "npm_config_//npm.pkg.github.com/:_authToken=$NODE_AUTH_TOKEN" \
pnpm install --frozen-lockfileDas Secret kommt beim Build von außen, nicht aus dem Dockerfile:
docker build --secret id=node_auth_token,env=NODE_AUTH_TOKEN .ARG und ENV sind dafür tabu: Beide bleiben im Image und in der
Build-Historie sichtbar.
Paket installieren
pnpm add @neodin-eu/uiFrisch veröffentlichte Versionen des Scopes sind von pnpms Wartezeit
ausgenommen; dafür steht in pnpm-workspace.yaml:
minimumReleaseAgeExclude: ["@neodin-eu/*"]Styles einbinden
Die Design-Tokens, Schriften und Basis-Styles liegen in
@neodin-eu/ui/styles.css. In der Anwendung reichen zwei Importe in der
globalen CSS-Datei:
@import "tailwindcss";
@import "@neodin-eu/ui/styles.css";Das mitgelieferte CSS bringt seine eigene @source-Zeile für die gebauten
Komponenten mit; die Anwendung muss das Paket nicht zusätzlich scannen.
Eigene Dateien erkennt Tailwind 4 automatisch, weitere Pfade ergänzt du mit
@source. Die Schriften Manrope und JetBrains Mono sind selbst gehostet und
kommen über @fontsource mit – ein CDN ist nicht nötig.
Provider im Root-Layout
ThemeProvider, NeodinProvider, TooltipProvider und Toaster sitzen
einmal im Root-Layout. suppressHydrationWarning auf <html> ist nötig, weil
next-themes die Theme-Klasse vor der Hydration setzt:
import { NeodinProvider, ThemeProvider, Toaster, TooltipProvider } from "@neodin-eu/ui";
export default function RootLayout({ children }: { children: React.ReactNode }) {
return (
<html lang="de" suppressHydrationWarning>
<body className="min-h-dvh bg-page text-foreground antialiased">
<ThemeProvider>
<NeodinProvider locale="de-AT">
<TooltipProvider>{children}</TooltipProvider>
<Toaster />
</NeodinProvider>
</ThemeProvider>
</body>
</html>
);
}Mehr zu Sprache und Dichte steht unter NeodinProvider, das Umschalten zwischen hell und dunkel unter Hell und dunkel.
Peer-Abhängigkeiten
React und React DOM sind Pflicht. Die drei weiteren Pakete sind optionale
Peers: Du installierst sie nur, wenn du die zugehörigen Komponenten nutzt. Die
Versionen stammen unverändert aus packages/ui/package.json.
| Paket | Version | Pflicht | Nötig für |
|---|---|---|---|
react | ^19.3 | Pflicht | alle Komponenten |
react-dom | ^19.3 | Pflicht | alle Komponenten |
next-themes | ^0.4 | optional | ThemeProvider, ThemeToggle, useTheme |
react-hook-form | ^7.92 | optional | Form, FormField, FormItem, FormLabel, FormControl, FormDescription, FormMessage |
@tanstack/react-table | ^9.3 | optional | DataTable, DataTableColumnHeader, DataTablePagination, DataTableToolbar |
Ein Beispiel: Eine Anwendung ohne Formulare und ohne Tabellen braucht nur
react und react-dom; für das Formular
kommt react-hook-form dazu, für die
Tabelle @tanstack/react-table.
Nächste Schritte
- Design-Tokens: Flächen, Statusfarben, Dichte und Schriften in beiden Themes.
- Hell und dunkel: ThemeProvider und die Regel, dass Produktoberflächen nur semantische Utilities verwenden.
- Schaltfläche (Button): die erste Komponente zum Ausprobieren.