# Quickstart

> Install @n3wth/ui 2.x. Build a React page with shared components and native controls.

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:

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

```tsx
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](/ui/troubleshooting#font-resolution-fails). This is a source-level packaging limitation, not evidence that the React props are wrong.

## Choose the entry point

| Import | Purpose |
| --- | --- |
| `@n3wth/ui/site` | Provider, page headers, containers, navigation, footer, reading outline |
| `@n3wth/ui/primitives` | Native Astryx exports through the package-owned dependency |
| `@n3wth/ui/site.css` | Generated theme, component, site, and visual styles |
| `@n3wth/ui` | Compatibility adapters, hooks, tokens, and brand utilities |
| `@n3wth/ui/styles` | Compatibility CSS plus the shared site foundation |

Continue with [site compositions](/ui/site-compositions) and [primitives and themes](/ui/primitives-and-themes). Use [API recipes](/ui/api-and-recipes) for router and Open Graph integrations.

## Sources

- [Package exports, engines, and peers](https://github.com/n3wth/n3wth/blob/main/packages/ui/package.json)
- [Packaged Vite starter](https://github.com/n3wth/n3wth/blob/main/packages/ui/v0/n3wth-ui/assets/starter/src/main.tsx)
- [CSS assembly](https://github.com/n3wth/n3wth/blob/main/packages/ui/scripts/build-styles.mjs)
- [Font distribution notes](https://github.com/n3wth/n3wth/blob/main/packages/ui/public/fonts/README.md)