Installation

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

1. Install the Package#

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

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

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

@import 'tailwindcss';
@plugin 'moraine/tailwind';
@source '../node_modules/moraine/dist';

Define your theme variables in CSS. See the Tailwind CSS Guide 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:

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

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

Next Steps#

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