Skip to main content

Installation

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

View as Markdown

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 or the Tailwind CSS v4 integration.
  • TypeScript: Recommended for component props and collection types.

1. Install the Package#

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

pnpm 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.

Follow the UnoCSS setup to install @subf/unocss, register its Vite plugin, and import virtual:uno.css. Then add the preset and component scanning to unocss.config.ts:

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

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 for @source configuration and monorepo paths.

3. Verify the Installation#

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

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 or Tailwind 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:

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

Next Steps#

Choose a component and copy its Usage example. Read Composition for attached parts and Customization for local style overrides.