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 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:
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 to install @subf/unocss, register
its Vite plugin, and import virtual:uno.css. Then add the preset and component scanning to
unocss.config.ts:
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:
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:
The button should have a solid primary background, rounded corners, and padding. Confirm the same appearance in each scenario:
- Start the dev server with an empty Vite dependency cache and open the app, without editing source files or refreshing to recover styles.
- Stop the dev server and restart it with the dependency cache present.
- Open a lazy-loaded route that renders Moraine components directly, without visiting the home page first.
- 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.cssfor UnoCSS or your Tailwind stylesheet. - UnoCSS: Configure both
content.filesystemandcontent.pipeline.includeas shown above. In the documented Vite integration, the filter also applies to filesystem extraction. - Tailwind v4: Verify that
@sourcepoints tomoraine/distrelative 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:
Next Steps#
Choose a component and copy its Usage example. Read Composition for attached parts and Customization for local style overrides.