Installation

Check repository access #

Installation requires read access to the private coreuxio/ui repository. The package is not published to npm. Browsing this site, trying previews, and copying source are public and require no sign-in.

Use a GitHub account with repository access and an SSH key registered to that account. Before installing, verify that the same machine can read the repository:

git ls-remote git@github.com:coreuxio/ui.git HEAD

A successful command prints the remote HEAD revision. If you cannot read the repository, ask a CoreUX repository owner for access. A successful GitHub login alone does not grant access to this repository.

CI also needs read access: configure a repository deploy key or an HTTPS Git credential with repository read permission in the runner’s secret storage. Keep credentials out of package.json, Git URLs committed to source, and browser-exposed environment variables.

Install the pinned package #

The package requires react >=18 as a peer dependency and a Tailwind v4 build. It brings no second React copy and requires no provider. Use the React version supported by your framework: this guide is verified with Node.js 24, pnpm 11.17.0, Next.js 16.3.5, React and React DOM 19.3.0, and Tailwind 4.3.3.

In an existing compatible app, add the reviewed Git revision and Tailwind’s PostCSS integration:

pnpm add github:coreuxio/ui#06f42fd532ec03a8fa80a320398cd7f006d89dec
pnpm add -D tailwindcss@4.3.3 @tailwindcss/postcss@4.3.3

For a minimal Next.js App Router app, create an empty project directory and use this complete package file. Existing apps should merge these dependencies with their own scripts and framework configuration.

{
  "name": "stat-block-consumer",
  "private": true,
  "type": "module",
  "packageManager": "pnpm@11.17.0",
  "scripts": { "build": "next build" },
  "dependencies": {
    "@coreux/ui": "github:coreuxio/ui#06f42fd532ec03a8fa80a320398cd7f006d89dec",
    "next": "16.3.5",
    "react": "19.3.0",
    "react-dom": "19.3.0"
  },
  "devDependencies": {
    "@tailwindcss/postcss": "4.3.3",
    "@types/node": "24.13.4",
    "@types/react": "19.3.0",
    "@types/react-dom": "19.3.0",
    "tailwindcss": "4.3.3",
    "typescript": "6.0.3"
  }
}

The Git package’s prepare step automatically builds its JavaScript and declarations into dist/ during installation. There is no separate library build command for consumers. The public stylesheet remains Tailwind source CSS, even though the package also builds an internal compiled stylesheet.

pnpm 11 requires approval for dependency build scripts. Run pnpm install; if it reports blocked builds, run pnpm approve-builds, review the displayed package entries, approve the pinned CoreUX package and the build dependencies used by your app, then rerun pnpm install. The following approvals are the ones used by this guide’s minimal app:

packages:
  - '.'

allowBuilds:
  '@coreux/ui@git+ssh://git@github.com/coreuxio/ui.git#06f42fd532ec03a8fa80a320398cd7f006d89dec': true
  '@tailwindcss/oxide': true
  sharp: true

Review and commit the generated pnpm-lock.yaml and build approvals. Keep the full Git revision pinned instead of following a branch. For subsequent clean installs and CI, use pnpm install --frozen-lockfile.

Configure styles once #

Add Tailwind v4’s PostCSS plugin at your app root:

const config = { plugins: { '@tailwindcss/postcss': {} } };

export default config;

Use the package stylesheet as your only Tailwind entry point. It already imports Tailwind, the brand theme, and fonts, and scans the library’s own component source. Remove any second @import 'tailwindcss' from this global stylesheet.

@import '@coreux/ui/styles.css';
@source '../';

The @source '../' directive scans your app’s own source for complete utility class names. From app/globals.css it covers the project; from src/app/globals.css it covers src/. Add explicit sources if your components live elsewhere. Do not link this source CSS as an unprocessed static asset.

Import the global stylesheet once in the root layout. This complete layout remains a Server Component:

import './globals.css';

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return <html lang="en"><body><main>{children}</main></body></html>;
}

Keep the 'use client' directive in each copied component example. At this revision, the package root imports GroupFrame, which creates a React context on import, so a client boundary is required even for static components and the cn utility. Next.js still prerenders these examples into HTML. Your surrounding page, layout, and documentation can stay on the server.

Render your first component to add app/page.tsx and start the app. Next.js generates its default TypeScript configuration on first build if it is missing.

Use the bundled fonts #

Switzer and The Seasons are bundled as local OpenType assets and load through @font-face in the package stylesheet. Switzer provides weights 400, 500, 600, and 700; The Seasons provides 400 and 700. Use font-sans for Switzer, font-display for The Seasons, and font-mono for the mono stack. No extra font download or next/font setup is needed for the bundled faces.

The package licenses its bundled fonts for internal CoreUX brand use in CoreUX-owned projects only. Public readers can study the examples, but must not extract or redistribute these font files outside that scope.

JetBrains Mono is different: the stylesheet imports weights 400 and 500 from Google Fonts. If that request is blocked or offline, labels fall back to the configured system monospace stack. Local Switzer and The Seasons do not depend on Google Fonts. Keep that external font request in mind when configuring your app’s network policy.

Source: package installation and font notes, bundled font declarations, and style entry point (repository access required).

Troubleshooting #

Repository not found or Permission denied (publickey)

Run the git ls-remote command above in the same terminal or CI runner that installs dependencies. Check the account’s repository permission and that its SSH key is loaded. For an HTTPS configuration, check the credential’s repository read scope. Retry pnpm install only after the Git read succeeds.

Cannot resolve the package or its dist files

Read the install log for a blocked or failed prepare step. Review the requested build approval with pnpm approve-builds, then rerun pnpm install with network and repository access. Do not work around a failed build by importing private src/ or dist/ subpaths: only the package root and @coreux/ui/styles.css are public entry points.

createContext is not a function or a client-boundary error

Put 'use client' at the top of the file that imports package values, before its imports. Preserve the directive in copied examples. An import type is erased by TypeScript and does not require this runtime boundary.

The component is unstyled, or my wrapper utilities do nothing

Check that the root layout imports globals.css, that PostCSS uses @tailwindcss/postcss, and that the stylesheet imports @coreux/ui/styles.css exactly once. Remove a duplicate Tailwind import. If only your wrapper is affected, verify the @source path and use complete class strings such as p-6, not constructed fragments. Rebuild the app after changing its configuration.

The typography is using a fallback

In browser developer tools, check font network requests for successful local .otf responses and inspect the element’s computed font family and weight. Ensure your app’s build resolves the stylesheet’s relative asset URLs and that its asset base path or security policy is not blocking them. Check that a separate body font rule is not overriding Switzer. Test supported weights; the package disables synthetic font weights. A blocked Google Fonts request explains a monospace fallback, but does not explain a missing local brand font.

If the setup still fails, include the pinned revision, app/framework versions, and the failing install or browser request when reporting it to the repository maintainers. Do not include credentials.