DEV Community

SiteBrief
SiteBrief

Posted on

Why "flex" breaks your email in Outlook (and how to catch it in VS Code)

#github #tailwindcss #eslint #outlook

You spent hours building a beautiful email template with Tailwind CSS.
Flex layout, rounded corners, smooth animations. Looks perfect in the browser.

Then it lands in Outlook. Complete disaster.

The problem

Outlook 2016/2019/2021 uses Microsoft Word as its HTML renderer.
Word doesn't understand modern CSS. At all.

These Tailwind classes silently do nothing in Outlook:

Class Why it breaks
flex, inline-flex No flexbox support in Outlook Windows
grid, grid-cols-* No CSS Grid support
rounded-* border-radius is ignored
animate-* No CSS animations
shadow-* No box-shadow support
gap-* Requires flex/grid (both unsupported)
w-screen, h-screen No vw/vh units

The worst part? No errors. No warnings. Just broken layouts.

The fix

I built an ESLint plugin that catches these issues right in VS Code —
before you send anything.

bash

npm install --save-dev eslint-plugin-email-safe
Enter fullscreen mode Exit fullscreen mode 
// eslint.config.js
import emailSafe from 'eslint-plugin-email-safe'

export default [
  {
    files: ['emails/**/*.{jsx,tsx}'],
    ...emailSafe.configs.recommended,
  }
]
Enter fullscreen mode Exit fullscreen mode

Now flex, grid, rounded-lg get underlined instantly:
"rounded-lg" (border-radius) is not supported in: Outlook Windows.
Details: https://www.caniemail.com/features/css-border-radius/
89 unsafe patterns detected. Works with cn(), template literals,
and conditional expressions out of the box.

Bonus: Tailwind plugin with MSO utilities

npm install --save-dev tailwind-email-safe
Enter fullscreen mode Exit fullscreen mode 
// tailwind.config.js
module.exports = {
  plugins: [require('tailwind-email-safe')],
}
Enter fullscreen mode Exit fullscreen mode

Adds Outlook-safe utilities you actually need:

<table class="email-table w-full max-w-email-md mx-auto">
  <tr>
    <td class="email-td mso-lh-exact p-6">
      <img class="email-img" src="logo.png" />
      <p class="font-email-sans text-base">Hello!</p>
    </td>
  </tr>
</table>
Enter fullscreen mode Exit fullscreen mode
  • email-table — resets MSO table spacing
  • mso-hide — hides element from Outlook only
  • mso-lh-exact — fixes line-height in Outlook
  • email-img — removes gaps under images
  • max-w-email-md — standard 600px email width
  • How the compat matrix stays up to date
  • The compatibility data comes from caniemail.com.

A weekly AI agent (Claude) monitors Gmail, Outlook, and Apple Mail
release notes for CSS changes. If something changes — it auto-updates
the matrix and opens a PR.

No manual maintenance needed.

GitHub: https://github.com/PasateArtem/email-safe

Free and open source. Would love feedback from people building emails!

Top comments (0)