---
title: Installation
description: Install Moraine, configure atomic styling, and verify your SolidJS
  application setup.
package: moraine
version: 0.11.0
repository: https://github.com/subframe7536/moraine
---

# Installation

> Install Moraine, configure atomic styling, and verify your SolidJS application setup.

## Prerequisites

Start with a SolidJS application and a build pipeline that compiles Solid JSX:

- **SolidJS**: `^1.9.15`, matching Moraine's peer dependency.
- **Build tool**: A Solid/Vite application or SolidStart.
- **Styling**: The [UnoCSS integration](https://moraine.subf.dev/docs/unocss.md) or the [Tailwind CSS v4 integration](https://moraine.subf.dev/docs/tailwind.md).
- **TypeScript**: Recommended for component props and collection types.

## 1. Install the Package

Add the `moraine` package to your project with your preferred package manager:

```shell title="pnpm" group-id="install"
pnpm add moraine
```

```shell title="bun" group-id="install"
bun add moraine
```

```shell title="npm" group-id="install"
npm install moraine
```

```shell title="yarn" group-id="install"
yarn add moraine
```

The main `moraine` entry needs only `solid-js`. Other entries need an optional peer dependency, which you install yourself:

| Import path           | Provides                                            | Peer dependency                       |
| :-------------------- | :-------------------------------------------------- | :------------------------------------ |
| `moraine`             | Components, `MoraineProvider`, `cn`, and `useCn`    | `solid-js`                            |
| `moraine/theme`       | `defineTheme()` and theme types                     | None                                  |
| `moraine/utils`       | Utilities such as `createId` and `createMediaQuery` | `solid-js`                            |
| `moraine/unocss`      | `presetMoraine()`                                   | `@subf/unocss` (`^0.4.0`)             |
| `moraine/tailwind`    | Tailwind CSS v4 plugin                              | `tailwindcss` (`^4.3.5`)              |
| `moraine/data-table`  | `DataTable` and `createDataTable`                   | `@tanstack/table-core` (`^9.3.1`)     |
| `moraine/virtualizer` | List and table virtualizers                         | `@tanstack/virtual-core` (`^3.19.11`) |
| `moraine/dnd`         | Sortable lists and trees                            | `@dnd-kit/dom` (`^0.5.3`)             |
| `moraine/icon.css`    | Optional stylesheet for built-in icons              | None                                  |

## 2. Configure Atomic Class Styling

Moraine needs generated utility classes and semantic CSS variables. Choose one integration and
complete its setup before checking a component.

### Option A: UnoCSS (Recommended)

Follow the [UnoCSS setup](https://moraine.subf.dev/docs/unocss.md#installation-and-config) to install `@subf/unocss`, register
its Vite plugin, and import `virtual:uno.css`. Then add the preset and component scanning to
`unocss.config.ts`:

```ts title="unocss.config.ts"
import { defineConfig, presetWind4 } from '@subf/unocss'
import { presetMoraine } from 'moraine/unocss'

export default defineConfig({
  presets: [presetWind4(), presetMoraine()],
  content: {
    filesystem: [
      './index.html',
      './src/**/*.{js,ts,jsx,tsx}',
      './node_modules/moraine/dist/**/*.{mjs,jsx}',
    ],
    pipeline: {
      include: [/\.(?:mjs|js|ts|jsx|tsx|mdx?|html)(?:\?|$)/],
    },
  },
})
```

For Wind3, replace the presets with `[presetWind3(), presetMoraine({ wind3: true })]`. The preset does not detect Wind3, so you must enable `wind3` explicitly. See the [UnoCSS guide](https://moraine.subf.dev/docs/unocss.md) for integration, scanning, and color tokens.

### Option B: Tailwind CSS

With Tailwind CSS v4, install `tailwindcss` and `@tailwindcss/vite`, configure the Vite plugin, and register the plugin from `moraine/tailwind`:

```css title="src/index.css"
@import 'tailwindcss';
@plugin 'moraine/tailwind';
@source '../node_modules/moraine/dist';
```

Define your theme variables in CSS, because the plugin does not emit them. See the [Tailwind CSS guide](https://moraine.subf.dev/docs/tailwind.md) for `@source` configuration and monorepo paths.

## 3. Verify the Installation

Render a test button to confirm that utility classes are generated:

```tsx title="src/App.tsx"
import { Button } from 'moraine'

export function App() {
  return (
    <div class="p-8">
      <Button variant="solid" onClick={() => alert('Moraine is working!')}>
        Click me
      </Button>
    </div>
  )
}
```

The button should have a solid primary background, rounded corners, and padding. Confirm the same appearance in each scenario:

1. Start the dev server with an empty Vite dependency cache and open the app, without editing source files or refreshing to recover styles.
2. Stop the dev server and restart it with the dependency cache present.
3. Open a lazy-loaded route that renders Moraine components directly, without visiting the home page first.
4. Build the application and check the same routes in its production preview server.

Use your application's dev, build, and preview commands. If any scenario is unstyled, see [UnoCSS verification and troubleshooting](https://moraine.subf.dev/docs/unocss.md#verification-and-troubleshooting) or [Tailwind troubleshooting](https://moraine.subf.dev/docs/tailwind.md#troubleshooting).

## Troubleshooting

### Styles Are Missing or Unstyled

If the button renders as a plain unstyled HTML button:

- **CSS entry**: Verify that the application entry imports `virtual:uno.css` for UnoCSS or your Tailwind stylesheet.
- **UnoCSS**: Configure both `content.filesystem` and `content.pipeline.include` as shown above. In the documented Vite integration, the filter also applies to filesystem extraction.
- **Tailwind v4**: Verify that `@source` points to `moraine/dist` relative to your CSS file. If the CSS rule exists but its color is missing, also check the theme variables.

Neither `MoraineProvider` nor the optional `moraine/icon.css` replaces class scanning. If styles appear only after you clear Vite's cache, follow the cache troubleshooting steps in the UnoCSS guide, then verify a restart with the cache retained.

### JSX TypeScript Errors

If TypeScript reports errors on JSX elements or missing types, check that your `tsconfig.json` includes:

```json title="tsconfig.json"
{
  "compilerOptions": {
    "jsx": "preserve",
    "jsxImportSource": "solid-js"
  }
}
```

## Next Steps

Choose a [component](https://moraine.subf.dev/components.md) and copy its Usage example. Read
[Composition](https://moraine.subf.dev/docs/composition.md) for attached parts and
[Customization](https://moraine.subf.dev/docs/customization.md) for local style overrides.

