Troubleshooting

This guide covers common issues you might encounter when using postcss-logical-polyfill and how to resolve them.

Common Issues

Plugin Not Working

If the plugin doesn’t seem to be transforming your CSS:

Check Plugin Order: Ensure postcss-logical-polyfill runs before autoprefixer:

// ✅ Correct order
plugins: [
  'postcss-logical-polyfill',
  'autoprefixer'
]

// ❌ Wrong order
plugins: [
  'autoprefixer',
  'postcss-logical-polyfill'
]

Verify Configuration: Make sure the plugin is properly configured:

module.exports = {
  plugins: [
    require('postcss-logical-polyfill')({
      preserve: false
    })
  ]
}

Check CSS Syntax: Ensure your logical properties are correctly written:

/* ✅ Correct */
.element {
  margin-inline: 1rem;
  padding-block-start: 2rem;
}

/* ❌ Incorrect */
.element {
  margin-inline-horizontal: 1rem; /* Invalid property */
  padding-block-top: 2rem; /* Invalid property */
}

Unexpected Output

If the transformed CSS doesn’t match your expectations:

Review Direction Settings: Check if the dir option matches your layout:

// For RTL layouts
require('postcss-logical-polyfill')({
  dir: 'rtl'
})

Understand Preserve Option: When preserve: true, both logical and physical properties are output:

/* Input */
.element { margin-inline: 1rem; }

/* Output with preserve: true */
.element {
  margin-inline: 1rem;
  margin-left: 1rem;
  margin-right: 1rem;
}

/* Output with preserve: false */
.element {
  margin-left: 1rem;
  margin-right: 1rem;
}

Build Tool Integration Issues

Webpack Issues

If using with webpack and css-loader:

// Ensure PostCSS runs after CSS imports are resolved
module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/,
        use: [
          'style-loader',
          {
            loader: 'css-loader',
            options: {
              importLoaders: 1 // Important for processing @imports
            }
          },
          'postcss-loader'
        ]
      }
    ]
  }
}

Vite Issues

For Vite hot reload issues:

export default defineConfig({
  css: {
    postcss: {
      plugins: [
        require('postcss-logical-polyfill')()
      ]
    },
    devSourcemap: true // Enable source maps for debugging
  }
})

Next.js Issues

If styles aren’t applying in Next.js:

Ensure PostCSS config is in the project root
Restart the development server after adding the plugin
Check for CSS module conflicts

Browser Compatibility

IE11 Support

For IE11 compatibility, ensure you’re not using CSS custom properties with logical values:

/* ❌ Won't work in IE11 even with polyfill */
:root {
  --margin: margin-inline;
}
.element {
  var(--margin): 1rem;
}

/* ✅ Works with polyfill */
.element {
  margin-inline: 1rem; /* Transformed to physical properties */
}

Safari Quirks

Some older Safari versions may need additional prefixes. Combine with autoprefixer:

plugins: [
  'postcss-logical-polyfill',
  ['autoprefixer', { overrideBrowserslist: ['> 1%', 'last 2 versions'] }]
]

Performance Issues

Large CSS Files

For large CSS files, consider:

Enable Source Maps Only in Development:

module.exports = {
  plugins: [
    require('postcss-logical-polyfill')({
      preserve: process.env.NODE_ENV === 'development'
    })
  ]
}

Split CSS Processing:

// Process only files that use logical properties
module.exports = {
  plugins: [
    require('postcss-logical-polyfill')({
      // Only process files with logical properties
      filter: /logical/
    })
  ]
}

Experimental Features Issues

Gradient Logical Directions Not Working

If logical gradient directions aren’t being transformed:

Check Gradient Syntax: Ensure proper syntax for logical gradients:

/* ✅ Correct */
.element {
  background: linear-gradient(to inline-end, red, blue);
  background: radial-gradient(circle at inline-start, red, blue);
}

/* ❌ Incorrect */
.element {
  background: linear-gradient(to inline-horizontal, red, blue); /* Invalid direction */
  background: radial-gradient(at inline-start, red, blue); /* Missing shape */
}

Complex Gradient Positions: For mixed positioning, ensure proper order:

/* ✅ Correct - logical direction first or last */
background: radial-gradient(circle at inline-start top, red, blue);
background: radial-gradient(circle at 50% inline-end, red, blue);

/* ⚠️ May not transform - logical direction in middle */
background: radial-gradient(circle at 25% inline-start 75%, red, blue);

Multiple Gradients: Each gradient in a list is processed separately:

/* ✅ All gradients will be transformed */
background:
  linear-gradient(to inline-end, red, blue),
  radial-gradient(circle at inline-start, yellow, green);

!important Flags Not Preserved

If !important flags are appearing on all properties when only some should have them:

Check Plugin Version: Ensure you have the latest version that handles !important correctly

Verify Input Syntax: Make sure !important is placed correctly:

/* ✅ Correct */
.element {
  margin-inline-start: 1rem !important;
  padding-inline: 2rem; /* No !important */
}

/* Output should preserve the distinction */
[dir="ltr"] .element {
  margin-left: 1rem !important;
  padding-left: 2rem;
  padding-right: 2rem;
}

CSS Framework Conflicts

Bootstrap Integration

When using with Bootstrap or other frameworks:

/* Process framework CSS first, then your logical properties */
@import 'bootstrap/dist/css/bootstrap.css';

.my-component {
  margin-inline: 1rem; /* This will be transformed */
}

Tailwind CSS

With Tailwind CSS, add the plugin to process utility classes:

module.exports = {
  // ... other config
  plugins: [
    // Tailwind plugins
  ]
}

// postcss.config.js
module.exports = {
  plugins: [
    'tailwindcss',
    'postcss-logical-polyfill', // After Tailwind
    'autoprefixer'
  ]
}

Debug Mode

Enable debug mode to see what the plugin is transforming:

require('postcss-logical-polyfill')({
  preserve: true, // Keep original properties for comparison
  // Add debug logging in development
  debug: process.env.NODE_ENV === 'development'
})

Source Maps

Enable source maps to debug transformed CSS:

module.exports = {
  devtool: 'source-map',
  module: {
    rules: [
      {
        test: /\.css$/,
        use: [
          'style-loader',
          {
            loader: 'css-loader',
            options: { sourceMap: true }
          },
          {
            loader: 'postcss-loader',
            options: { sourceMap: true }
          }
        ]
      }
    ]
  }
}

Validation Tools

Use CSS validation tools to ensure your logical properties are correct:

W3C CSS Validator: Check if your CSS is valid
Browser DevTools: Inspect computed styles
PostCSS CLI: Test transformations manually:
Terminal window
```
npx postcss input.css -o output.css --verbose
```

Getting Help

If you’re still experiencing issues:

Check the GitHub Issues
Create a minimal reproduction case
Include your PostCSS configuration
Specify your build tool and version
Share the input CSS and expected output

Common Error Messages

”Plugin is not a function"

// ❌ Incorrect
plugins: ['postcss-logical-polyfill']

// ✅ Correct
plugins: [require('postcss-logical-polyfill')()]

"Cannot resolve ‘postcss-logical-polyfill’"

# Install the plugin
npm install postcss-logical-polyfill

"Invalid CSS after transformation”

Check that your CSS syntax is valid before transformation and that you’re not mixing logical and physical properties for the same dimension:

/* ❌ Conflicting properties */
.element {
  margin-left: 1rem;
  margin-inline-start: 2rem; /* Conflicts with margin-left */
}

/* ✅ Use only logical properties */
.element {
  margin-inline-start: 2rem;
}