Plugin Options

Complete reference for all available configuration options in the @duskmoon-dev/core Tailwind CSS plugin.

Options Object

interface DuskMoonUIOptions {
  themes?: string[];
  defaultTheme?: string;
  styled?: boolean;
  components?: 'all' | string[];
  prefix?: string;
}

`themes`

Type: string[] Default: ['sunshine', 'moonlight']

Array of built-in themes to include in your project.

Usage

// tailwind.config.js
{
  themes: ['sunshine', 'moonlight']  // Built-in themes only
}

Built-in Themes

sunshine: Warm light theme with amber primary color
moonlight: Cool dark theme with blue primary color

`defaultTheme`

Type: string Default: 'sunshine'

The theme to use when no data-theme attribute is present on the HTML element.

Usage

{
  defaultTheme: 'moonlight'  // Use dark theme by default
}

Behavior

<!-- Uses defaultTheme (moonlight) -->
<html>
  <body>Content</body>
</html>

<!-- Explicitly uses sunshine theme -->
<html data-theme="sunshine">
  <body>Content</body>
</html>

Validation

The defaultTheme value must match a theme name in the themes array:

{
  themes: ['sunshine', 'moonlight'],
  defaultTheme: 'moonlight',  // ✅ Valid - built-in theme
}

{
  themes: ['sunshine', 'moonlight'],
  defaultTheme: 'custom',  // ❌ Invalid - not a built-in theme
}

`styled`

Type: boolean Default: true

Whether to include component styles. Set to false if you only want theme CSS variables.

Usage

{
  styled: true   // Include component styles (default)
}

{
  styled: false  // Only theme CSS variables
}

When to Use `styled: false`

Building custom components: You want theme variables but will write your own components
Reducing bundle size: You don’t need the pre-built components
Using only themes: You’re only interested in the color system

Example with `styled: false`

// tailwind.config.js
{
  plugins: [
    duskmoonui({
      styled: false,  // No component classes
    }),
  ],
}

/* You can still use theme variables */
.my-custom-button {
  background-color: hsl(var(--color-primary));
  color: hsl(var(--color-primary-content));
  padding: 0.5rem 1rem;
  border-radius: 0.25rem;
}

`components`

Type: 'all' | string[] Default: 'all'

Which components to include. Use 'all' for all components, or specify an array of component names.

Usage

// Include all components
{
  components: 'all'  // Default
}

// Include specific components only
{
  components: ['button', 'card', 'input']
}

Available Components

'button' - Button variants and icon buttons
'card' - Card containers with subcomponents
'input' - Form inputs (input, textarea, select, checkbox, radio)
'badge' - Badge indicators and notifications
'alert' - Alert messages and notifications

Component Sizes

Approximate CSS output sizes (uncompressed):

Component	Variants	Approx. Size
button	30+	~2.5 KB
card	20+	~2.0 KB
input	15+	~2.0 KB
badge	25+	~1.5 KB
alert	20+	~1.5 KB
All	110+	~8.0 KB

Example: Button-Only Build

{
  components: ['button']  // Only include button styles (~2.5 KB)
}

Case Sensitivity

Component names are case-insensitive:

{
  components: ['Button', 'CARD', 'input']  // All valid
}

Bundle Optimization

For production builds, include only what you use:

// Development: All components
const isDev = process.env.NODE_ENV === 'development';

{
  components: isDev ? 'all' : ['button', 'card', 'input']
}

`prefix`

Type: string Default: '' (empty string)

Prefix for all component classes. Useful to avoid naming conflicts.

Usage

{
  prefix: 'dm-'  // Prefix all classes with 'dm-'
}

Affected Classes

With prefix: 'dm-':

<!-- Without prefix -->
<button class="btn btn-primary">Button</button>

<!-- With prefix -->
<button class="dm-btn dm-btn-primary">Button</button>

All Classes Are Prefixed

<!-- Cards -->
<div class="dm-card dm-card-default">
  <div class="dm-card-body">
    <h3 class="dm-card-title">Title</h3>
  </div>
</div>

<!-- Inputs -->
<input class="dm-input dm-input-outlined" />

<!-- Badges -->
<span class="dm-badge dm-badge-primary">Badge</span>

<!-- Alerts -->
<div class="dm-alert dm-alert-success">Alert</div>

Prefix Recommendations

Common prefixes:

'' - No prefix (default, cleanest)
'dm-' - DuskMoon prefix
'ui-' - Generic UI prefix
'app-' - Application-specific prefix

Avoid Conflicts

Use prefixes when integrating with other libraries:

// Avoid conflicts with other component libraries
{
  prefix: 'dm-',
  components: 'all'
}

Complete Configuration Example

Basic Configuration

// tailwind.config.js
const { duskmoonui } = require('@duskmoon-dev/core');

module.exports = {
  content: ['./src/**/*.{html,js,jsx,ts,tsx}'],
  plugins: [
    duskmoonui({
      themes: ['sunshine', 'moonlight'],
      defaultTheme: 'sunshine',
      styled: true,
      components: 'all',
      prefix: '',
    }),
  ],
};

Advanced Configuration

// tailwind.config.js
const { duskmoonui } = require('@duskmoon-dev/core');

// Custom theme
const brandTheme = {
  name: 'brand',
  primary: '220 90% 50%',
  'primary-focus': '220 90% 40%',
  // ... other tokens
};

// Environment-based configuration
const isDev = process.env.NODE_ENV === 'development';
const isProd = process.env.NODE_ENV === 'production';

module.exports = {
  content: ['./src/**/*.{html,js,jsx,ts,tsx}'],
  plugins: [
    duskmoonui({
      // Include built-in themes
      themes: ['sunshine', 'moonlight'],

      // Use sunshine by default in prod
      defaultTheme: isProd ? 'sunshine' : 'moonlight',

      // Always include component styles
      styled: true,

      // All components in dev, specific components in prod
      components: isDev ? 'all' : ['button', 'card', 'input', 'badge'],

      // No prefix
      prefix: '',
    }),
  ],
};

TypeScript Configuration

// tailwind.config.ts
import { duskmoonui, type DuskMoonUIOptions } from '@duskmoon-dev/core';
import type { Config } from 'tailwindcss';

const options: Partial<DuskMoonUIOptions> = {
  themes: ['sunshine', 'moonlight'],
  defaultTheme: 'sunshine',
  styled: true,
  components: 'all',
  prefix: '',
};

const config: Config = {
  content: ['./src/**/*.{html,js,jsx,ts,tsx}'],
  plugins: [duskmoonui(options)],
};

export default config;

Tailwind CSS 4.0 Configuration

For Tailwind CSS 4.0+, use the @plugin directive:

/* app.css or global.css */
@import "tailwindcss";

@plugin "@duskmoon-dev/core/plugin" {
  @theme {
    --theme: "sunshine";           /* defaultTheme */
  }

  @config {
    themes: ["sunshine", "moonlight"];
    components: ["button", "card", "input"];
    prefix: "";
  }
}

Tailwind CSS 4.0 Limitations

Some options may have different syntax or limitations in Tailwind CSS 4.0. Refer to Tailwind’s v4 documentation for details.

Default Values Summary

Option	Type	Default	Description
`themes`	`string[]`	`['sunshine', 'moonlight']`	Themes to include
`defaultTheme`	`string`	`'sunshine'`	Default theme name
`styled`	`boolean`	`true`	Include component styles
`components`	`'all' \| string[]`	`'all'`	Components to include
`prefix`	`string`	`''`	Class name prefix

Configuration Guide - Setup and configuration
Theme Tokens - Complete token reference
Theme Customization - Adjust sunshine and moonlight

Migration Guide

From v0.1.x to v0.2.x

No breaking changes expected. All options are backward compatible.

Troubleshooting

Components Not Appearing

Problem: Component classes don’t work

Solution: Ensure styled: true (default):

{
  styled: true  // Must be true for components
}

Theme Not Applying

Problem: Theme colors don’t apply

Solution: Check data-theme attribute and defaultTheme:

<html data-theme="moonlight">  <!-- Must match a theme in themes array -->

Prefix Not Working

Problem: Prefixed classes don’t work

Solution: Use prefix consistently:

// Config
{
  prefix: 'dm-'
}

// HTML - Use prefix in all classes
<button class="dm-btn dm-btn-primary">Button</button>

Performance Tips

Include only needed components for smaller bundles
Use one theme in production if you don’t need theme switching
Set styled: false if you’re building custom components
Use PurgeCSS/Tailwind purge to remove unused classes

// Optimized for production
{
  themes: [productionTheme],           // One theme only
  defaultTheme: 'production',          // Explicit default
  components: ['button', 'card'],      // Only used components
  styled: true,                        // Keep component styles
}

Plugin Options

Options Object

themes

Usage

Built-in Themes

defaultTheme

Usage

Behavior

Validation

styled

Usage

When to Use styled: false

Example with styled: false

components

Usage

Available Components

Component Sizes

Example: Button-Only Build

Case Sensitivity

Bundle Optimization

prefix

Usage

Affected Classes

All Classes Are Prefixed

Prefix Recommendations

Avoid Conflicts

Complete Configuration Example

Basic Configuration

Advanced Configuration

TypeScript Configuration

Tailwind CSS 4.0 Configuration

Tailwind CSS 4.0 Limitations

Default Values Summary

Related Documentation

Migration Guide

From v0.1.x to v0.2.x

Troubleshooting

Components Not Appearing

Theme Not Applying

Prefix Not Working

Performance Tips

`themes`

`defaultTheme`

`styled`

When to Use `styled: false`

Example with `styled: false`

`components`

`prefix`