Zum Inhalt springen
Dokumentation

Dokumentation

Installation

Stabil

Die 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:

ini
@neodin-eu:registry=https://npm.pkg.github.com

Diese 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:

bash
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:

bash
env "npm_config_//npm.pkg.github.com/:_authToken=$NODE_AUTH_TOKEN" pnpm install --frozen-lockfile

Docker-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:

dockerfile
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-lockfile

Das Secret kommt beim Build von außen, nicht aus dem Dockerfile:

bash
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

bash
pnpm add @neodin-eu/ui

Frisch veröffentlichte Versionen des Scopes sind von pnpms Wartezeit ausgenommen; dafür steht in pnpm-workspace.yaml:

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:

css
@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:

tsx
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.

PaketVersionPflichtNötig für
react^19.3Pflichtalle Komponenten
react-dom^19.3Pflichtalle Komponenten
next-themes^0.4optionalThemeProvider, ThemeToggle, useTheme
react-hook-form^7.92optionalForm, FormField, FormItem, FormLabel, FormControl, FormDescription, FormMessage
@tanstack/react-table^9.3optionalDataTable, 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.