Tailwind 플러그인 API

Why Write Tailwind Plugins?

The plugin() Function

// tailwind.config.js
const plugin = require('tailwindcss/plugin');

module.exports = {
  content: ['./src/**/*.{html,js}'],
  theme: { extend: {} },
  plugins: [
    plugin(function({ addUtilities, addComponents, addBase, addVariant }) {
      // Your extension code here
    })
  ]
};

addUtilities: Adding Utility Classes

plugin(function({ addUtilities }) {
  addUtilities({
    '.scrollbar-hide': {
      '-ms-overflow-style': 'none',
      'scrollbar-width': 'none',
      '&::-webkit-scrollbar': {
        display: 'none'
      }
    },
    '.text-balance': {
      'text-wrap': 'balance'
    },
    '.content-auto': {
      'content-visibility': 'auto'
    }
  });
})

// Now usable in markup:
// <div class='scrollbar-hide overflow-auto h-64'>...
// <h1 class='text-balance text-4xl font-bold'>...

addComponents: Adding Component Classes

plugin(function({ addComponents }) {
  addComponents({
    '.btn': {
      display: 'inline-flex',
      alignItems: 'center',
      justifyContent: 'center',
      padding: '0.5rem 1rem',
      borderRadius: '0.5rem',
      fontWeight: '500',
      fontSize: '0.875rem',
      transitionProperty: 'color, background-color',
      transitionDuration: '150ms',
      cursor: 'pointer'
    },
    '.btn-primary': {
      backgroundColor: '#3b82f6',
      color: '#ffffff',
      '&:hover': {
        backgroundColor: '#1d4ed8'
      }
    }
  });
})

addBase: Adding Base Styles

plugin(function({ addBase, theme }) {
  addBase({
    // Style all h1-h6 elements with a consistent font
    'h1, h2, h3, h4, h5, h6': {
      fontFamily: theme('fontFamily.heading'),
      fontWeight: theme('fontWeight.semibold'),
      lineHeight: theme('lineHeight.tight')
    },
    // Custom focus style for all focusable elements
    ':focus-visible': {
      outline: '2px solid ' + theme('colors.blue.500'),
      outlineOffset: '2px'
    },
    // Smooth scrolling for the whole page
    'html': {
      scrollBehavior: 'smooth'
    }
  });
})

Accessing the Theme in Plugins

plugin(function({ addUtilities, theme }) {
  // Generate text-shadow utilities using spacing scale
  const shadows = {
    '.text-shadow-sm': {
      textShadow: '0 1px 2px ' + theme('colors.black/20')
    },
    '.text-shadow': {
      textShadow: '0 2px 4px ' + theme('colors.black/30')
    },
    '.text-shadow-lg': {
      textShadow: '0 8px 16px ' + theme('colors.black/40')
    },
    '.text-shadow-none': {
      textShadow: 'none'
    }
  };
  addUtilities(shadows);
})

Generating Utilities From Theme Values

plugin(function({ addUtilities, theme }) {
  // Generate border-start-* utilities from the color palette
  const colors = theme('colors');
  const utilities = {};

  Object.entries(colors).forEach(([colorName, shades]) => {
    if (typeof shades === 'string') {
      utilities['.border-start-' + colorName] = {
        borderInlineStartColor: shades
      };
    } else {
      Object.entries(shades).forEach(([shade, value]) => {
        utilities['.border-start-' + colorName + '-' + shade] = {
          borderInlineStartColor: value
        };
      });
    }
  });

  addUtilities(utilities);
})

matchUtilities for Arbitrary Values

plugin(function({ matchUtilities, theme }) {
  matchUtilities(
    {
      'text-shadow': (value) => ({
        textShadow: value
      })
    },
    {
      // Values from the theme that appear as autocomplete suggestions
      values: theme('textShadow')
    }
  );
  // Usage: text-shadow-sm (from theme) or
  //        text-shadow-[0_4px_8px_rgba(0,0,0,0.5)] (arbitrary)
})

// tailwind.config.js theme extension:
theme: {
  textShadow: {
    sm: '0 1px 2px rgba(0,0,0,0.2)',
    DEFAULT: '0 2px 4px rgba(0,0,0,0.3)',
    lg: '0 8px 16px rgba(0,0,0,0.4)'
  }
}

Plugin Options With withOptions

const plugin = require('tailwindcss/plugin');

// scrollbar plugin with options
const scrollbarPlugin = plugin.withOptions(function(options = {}) {
  return function({ addUtilities }) {
    const { width = '6px', track = '#f1f5f9', thumb = '#94a3b8' } = options;

    addUtilities({
      '.scrollbar-custom': {
        '&::-webkit-scrollbar': { width },
        '&::-webkit-scrollbar-track': { background: track },
        '&::-webkit-scrollbar-thumb': { background: thumb, borderRadius: '3px' }
      }
    });
  };
});

// tailwind.config.js usage:
plugins: [
  scrollbarPlugin({ width: '8px', thumb: '#3b82f6' })
]

Debugging Plugins

# Debug: build CSS and inspect output
npx tailwindcss \
  --input src/input.css \
  --output dist/debug.css \
  --content 'src/**/*.html'

# Then check:
grep 'text-shadow' dist/debug.css

# If missing:
# 1. Is the class used in an HTML file in content paths?
# 2. Does the addUtilities selector start with '.'?
# 3. Is the plugin listed in tailwind.config.js plugins array?

# Safelist it temporarily to confirm plugin works:
safelist: ['text-shadow-lg']

Using Official Tailwind Plugins

npm install @tailwindcss/typography @tailwindcss/forms

// tailwind.config.js
plugins: [
  require('@tailwindcss/typography'),
  require('@tailwindcss/forms')({
    strategy: 'class'  // use .form-input etc. classes
  })
]

// Usage:
<article class='prose prose-lg prose-blue max-w-none'>
  {/* Beautifully styled HTML content */}
</article>

<input type='text' class='form-input rounded-lg border-gray-300' />

Quick Check

Lesson Recap