Start with the installed version and the import path. Native primitives and root compatibility adapters have different APIs and styling requirements.
Inspect the installation#
Run these read-only checks from the consuming application:
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.
| Symptom | Check | Resolution |
|---|---|---|
@n3wth/ui/site cannot resolve | Installed version and export map; whether workspace dist exists | Use a version with the site export. Workspace maintainers build UI before consuming apps. |
| Components render without shared styling | Global CSS import and provider ancestry | Import site.css and mount N3wthProvider; see quickstart. |
| Compatibility controls lose spacing or colors | Root adapter import, compatibility CSS, Tailwind source scanning | Follow the compatibility setup in primitives and themes. |
| Button props fail TypeScript checks | Whether Button comes from root or primitives | Native examples use label; root adapters require children. Match props to that entry's declarations. |
| Theme toggle changes only part of the page | Provider mode and document theme state | Pass the same useTheme().theme value to N3wthProvider. |
| Legal links disappear from the footer | Custom links prop | Include legal links inside the custom group; legalLinks only extends the default group. |
| Programmatic navigation keeps scroll position | How navigation was triggered | useRouteScrollReset handles qualifying anchor clicks, not every route update. |
Font resolution fails#
The source theme selects Suisse Intl. The npm files allowlist deliberately excludes those commercial font binaries. Licensed workspace sites retain the files and their font rules.
The release package check uses scripts/pack-ui.mjs to remove excluded Suisse font rules from the staged CSS. Shipped font URLs use package-relative paths. External consumers use the theme's system-font fallback. The release workflow publishes the exact tarball that passes the consumer checks.
If an older artifact still names a Suisse font:
- Confirm whether the missing path is one of the excluded
SuisseIntl-*assets. - Record the UI version, bundler, and exact unresolved URL for a package issue.
- Check that the artifact came from the release package check, not a direct pack of workspace output. Validate the corrected tarball before publishing it.
Do not copy the repository's commercial font binaries into a public package as a workaround. Importing both styles and site.css does not fix absent assets; both include the shared foundation.
Theme flashes or hydration differs#
useTheme uses defaultTheme during server rendering, but reads local storage and system preferences in the browser. Avoid assuming those initial values match. Keep any before-paint initialization aligned with the hook's storage key and data-theme attribute. The current UI docs app also sets data-astryx-theme="n3wth" before React starts.
A before-paint script addresses initial document colors. Theme-dependent text or icons rendered by the server still need a consistent rendering strategy in the application. Test a saved light preference, no saved preference, and disabled storage.
How 2.x is released#
Starting with 2.0.0, packages/ui in n3wth/n3wth is the publishing authority. The former n3wth/ui release workflow is historical. Do not publish locally.
For maintainers, the normal process is:
- Open one PR that bumps
versioninpackages/ui/package.json, sets the same version in the starter's@n3wth/uidependency, adds aCHANGELOG.mdentry, and runsnpm install --package-lock-only --ignore-scripts. - Merge the PR after a successful Site CI run on
main. - Push a tag
ui-v<version>on the merge commit, matching the version inpackages/ui/package.json. This triggers Release UI. - With
UI_NPM_PUBLISH_ENABLED=true, the publish job checks UI, validates a packed consumer, and publishes that exact tarball with provenance. - Verify the registry version and a clean consumer install before declaring the release available.
The workflow can also be dispatched manually on main. Publishing requires npm trusted-publisher configuration for owner n3wth, repository n3wth, and workflow publish-ui.yml. The publish script skips an already-published version and fails on unexpected registry lookup errors.
| Maintainer command | Purpose and side effects |
|---|---|
npm run check --workspace @n3wth/ui | Lint, build, inspect build output, and run unit tests; writes build output |
npm run check:package | Pack UI, install and build a temporary consumer, exercise browsers, save tarball and screenshots under .release |
Package publication and site deployment are separate operations. Current site configuration enables automatic Vercel Git deployments; older notes that call the UI docs deployment manual are stale. Publishing a package is not confirmation that a site deployment succeeded.