---
title: Installation
description: Install Moraine, configure atomic styling, and verify your SolidJS
  application setup.
package: moraine
version: 0.6.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 [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 using 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
```

## 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`. The component scanning configuration is:

Import `moraine/unocss` and configure `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 })]`. Wind3 compatibility must be enabled explicitly. See the [UnoCSS Setup Guide](https://moraine.subf.dev/docs/unocss.md) for integration, scanning, variant groups, and color tokens.

### Option B: Tailwind CSS

If you use Tailwind CSS v4, configure its Vite integration 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. 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 in your application to confirm that behavioral scripts and utility classes are functioning correctly:

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

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

Check that the button has a solid primary background, rounded corners, and padding. Verify 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 and restart the dev server with its dependency cache present.
3. Directly open a lazy-loaded route that renders Moraine components, without first visiting the home page.
4. Build the application and check the same routes through its production preview server.

Use your application's dev, build, and preview commands. 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) if any scenario is unstyled.

## 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. The filter also applies to filesystem extraction in the documented Vite integration.
- **Tailwind v4**: Verify that `@source` points to `moraine/dist` relative to your CSS file. If the CSS rule exists but its color is missing, check the theme variables as well.

Changing `MoraineProvider` or importing the optional `moraine/icon.css` does not replace class scanning. If styles appear only after clearing Vite's cache, follow the cache troubleshooting steps in the UnoCSS guide and verify a restart with the cache retained.

### JSX TypeScript Errors

If TypeScript complains about JSX elements or missing types, ensure 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 Basic 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.