Quickstart

Use @n3wth/ui/site for page structure and @n3wth/ui/primitives for controls. These instructions target version 2.0.0, available on npm, and the matching source in the n3wth monorepo.

Prerequisites#

• Node.js 24, as declared by the package.
• An existing React application with React and React DOM 18 or 19.
• A bundler that resolves ESM, package CSS imports, and font URLs. The package includes a Vite starter.

The example below assumes a React TypeScript app with src/main.tsx and an HTML element with id="root". For Next.js, put the interactive component in a client module and import the CSS through your application's global stylesheet entry.

Install#

From your application directory:

npm install @n3wth/ui@^2.0.0

React and React DOM are peer dependencies. GSAP is an optional peer; the site and button example below does not use animation hooks that require it. In this monorepo, use the root lockfile and keep workspace UI dependency versions aligned rather than installing a second registry copy.

Render a page#

Replace src/main.tsx with:

import { useState } from 'react'import { createRoot } from 'react-dom/client'import {  N3wthProvider,  PageHeader,  SiteContainer,  SiteSection,  SiteText,} from '@n3wth/ui/site'import { Button } from '@n3wth/ui/primitives'import '@n3wth/ui/site.css'function App() {  const [count, setCount] = useState(0)  return (    <N3wthProvider mode="dark">      <SiteContainer as="main">        <PageHeader          title="Component sandbox"          description="Try a native control in the shared site theme."        />        <SiteSection aria-label="Counter">          <Button label="Increment" onClick={() => setCount(value => value + 1)} />          <SiteText as="div">            <output aria-live="polite">Count: {count}</output>          </SiteText>        </SiteSection>      </SiteContainer>    </N3wthProvider>  )}const root = document.getElementById('root')if (!root) throw new Error('Missing #root element')createRoot(root).render(<App />)

Start the app with its existing development command, such as npm run dev in a Vite app. The page should display a heading and counter; selecting Increment increases the count.

N3wthProvider supplies the theme context. site.css supplies the generated theme and component CSS. Both are needed. This example does not require Tailwind utility generation.

Font packaging caveat#

The theme currently names Suisse Intl for body and headings, but its commercial font files are deliberately excluded from the npm package. The CSS still references those files. A browser may use system fallbacks; a bundler may instead reject the unresolved package URLs. If installation succeeds but CSS compilation fails, follow font troubleshooting. This is a source-level packaging limitation, not evidence that the React props are wrong.

Choose the entry point#

Continue with site compositions and primitives and themes. Use API recipes for router and Open Graph integrations.

Sources#

• Package exports, engines, and peers
• Packaged Vite starter
• CSS assembly
• Font distribution notes