Skip to content
n3wth docs

Troubleshooting

Start with the installed version and the import path. Native primitives and root compatibility adapters have different APIs and styling requirements. Run these read-only checks from the consuming application:

Terminal window
node --version
npm ls @n3wth/ui react react-dom
node --input-type=module -e "console.log(import.meta.resolve('@n3wth/ui/site'))"

The package declares Node 24 and React/React DOM 18 or 19. If a monorepo app resolves a nested registry package instead of the workspace package, check its dependency range against the workspace version and use the repository’s root install procedure.

Version mismatch across a monorepo

If components behave differently in different apps, or types do not match the source, a workspace app may be resolving a nested registry copy instead of the workspace package.

Check:

Terminal window
npm ls @n3wth/ui

Resolution: Align the workspace version in packages/ui/package.json with the app’s dependency range. In the monorepo, use the root lockfile and avoid installing a second registry copy. Build UI before consuming apps if dist is missing.

CSS not loading

Components render without shared styling, colors, or spacing.

Check: Verify that @n3wth/ui/site.css is imported once at the app root, and that an ancestor N3wthProvider is mounted above the page.

Resolution:

import '@n3wth/ui/site.css'
// In your app root:
<N3wthProvider mode="dark">{children}</N3wthProvider>

If you use compatibility adapters, import @n3wth/ui/styles instead and add a Tailwind source scan. Do not import both styles and site.css; both include the shared foundation.

Font resolution fails

The bundler reports an unresolved font URL, or the theme falls back to system fonts.

Check: Confirm whether the missing path is one of the excluded SuisseIntl-* assets. The npm files allowlist deliberately excludes those commercial font binaries. The release package check removes excluded Suisse font rules from the staged CSS.

Resolution: External consumers use the theme’s system-ui, -apple-system, sans-serif fallback. If you need Suisse Intl, supply the licensed font files locally in your workspace app and override the CSS variable. Do not copy commercial font binaries into a public package.

If an older artifact still names a Suisse font, validate the corrected tarball before publishing. Record the UI version, bundler, and exact unresolved URL when opening a package issue.

Wrong Button API

TypeScript errors or runtime warnings when using Button props.

Check: Whether Button comes from @n3wth/ui/primitives or @n3wth/ui (root).

Resolution:

  • Native primitives use label and onClick.
  • Root adapters require children and support props like variant="glass", leftIcon, and responsive size objects.

Match props to the entry point’s declarations. Do not move imports between entry points without checking types.

Theme not applied

Theme toggle changes only part of the page, or colors flash on load.

Check: Provider mode and document theme state. useTheme uses defaultTheme during server rendering, but reads local storage and system preferences in the browser.

Resolution: Pass the same useTheme().theme value to N3wthProvider. Keep any before-paint initialization aligned with the hook’s storage key (n3wth-theme) and data-theme attribute. The current UI docs app also sets data-astryx-theme="n3wth" before React starts.

Test a saved light preference, no saved preference, and disabled storage. A before-paint script addresses initial document colors; theme-dependent server markup still needs a consistent rendering strategy in the application.