Using CSS with @apply for plugin styles (instead of low-level CSS-in-JS)

[DaniGuardiola]

I'm using the excellent typography plugin and I've been trying to use tailwind's @apply itself to make my life much easier when extending the default plugin styles.

This has led me to experiment with possible implementations.

Hacky way

I've achieved this in a hacky but effective way.

The script

What this is script does is basically read a source CSS file, process it with PostCSS using the tailwind and autoprefixer plugins, and turned into CSS-in-JS format by postcss-js. Then it writes the output to a JSON file that is later read from the tailwind configuration to extend the plugin styles. Note that the config used by tailwind is the 'base' one (more on that below).

// tailwind-hack.js

const postcss = require('postcss')
const postcssJs = require('postcss-js')
const tailwind = require('tailwindcss')
const autoprefixer = require('autoprefixer')
const fs = require('fs/promises')
const path = require('path')

const getPath = p => path.join(process.cwd(), 'src/styles', p)
const INPUT = getPath('mdx-styles.css')
const OUTPUT = getPath('mdx-styles.compiled.json')

async function compile (cssString) {
  const { root } = await postcss([
    tailwind('tailwind.base.config.js'),
    autoprefixer
  ]).process(postcss.parse(cssString), {
    from: undefined
  })
  return postcssJs.objectify(root)
}

async function tailwindHack () {
  const input = await fs.readFile(INPUT, 'utf-8')
  const result = await compile(input)
  const jsonResult = JSON.stringify(result)
  return fs.writeFile(OUTPUT, jsonResult)
}

tailwindHack()

Tailwind config

In order to avoid recursivity when calling tailwind (as a postcss plugin), I've divided the tailwind config into two files: a base one (used from the script), and the final one which extends from the base and adds the compiled styles for the typography plugin:

// tailwind.base.config.js

module.exports = {
  purge: ['./src/**/*.{js,ts,jsx,tsx}'],
  theme: {
    extend: {
      fontFamily: {
        slab: '"Roboto Slab", serif',
        mono: '"Roboto Mono", monospace'
      },
      fontWeight: {
        'normal-light': '351'
      },
      colors: {
        'deep-green': '#1a281e'
      }
    }
  },
  variants: {
    extend: {
      margin: ['first', 'last'],
      height: ['hover']
    }
  }
}

// tailwind.config.js

const merge = require('lodash.merge')
const baseConfig = require('./tailwind.base.config')
const typography = require('@tailwindcss/typography')
const styles = require('./src/styles/mdx-styles.compiled.json')

module.exports = merge(baseConfig, {
  plugins: [typography],
  theme: {
    extend: {
      typography: styles
    }
  }
})

package.json scripts

To run this method I've modified my package.json scripts so that they look like this:

// package.json (scripts)
{
  {
    "dev": "yarn tailwind-hack && next dev",
    "build": "yarn tailwind-hack && next build",
    "start": "next start",
    "tailwind-hack": "node tailwind-hack"
  }
}

This has the disadvantage that the changes are not refreshed on file save when in development mode. A workaround is to run the script again, as Next.js will pick up the changes. A file watcher could be set-up for this task.

The input CSS

This is how the input CSS looks. To generate the appropriate structure, I'm using "fake selectors" that eventually get transformed into the object props that the plugin expects.

/* src/styles/mdx-styles.css (reduced for brevity) */

DEFAULT {
  css {
    @apply break-words;

    a {
      @apply text-blue-800 no-underline;
    }

    a:hover {
      @apply underline;
    }

    blockquote {
      @apply not-italic border-gray-500 bg-gray-100 pr-4 py-0.5 rounded-lg rounded-l-none;
    }
  }
}
xl {
  css {
    nav ol > li {
      @apply text-lg leading-5;
    }
  }
}

Compiled output

The output of running tailwind-hack.js script is written to this file:

// src/styles/mdx-styles.compiled.json

{
  "DEFAULT": {
    "css": {
      "overflowWrap": "break-word",
      "a": {
        "--tw-text-opacity": "1",
        "color": "rgba(30, 64, 175, var(--tw-text-opacity))",
        "textDecoration": "none"
      },
      "a:hover": {
        "textDecoration": "underline"
      },
      "blockquote": {
        "--tw-bg-opacity": "1",
        "backgroundColor": "rgba(243, 244, 246, var(--tw-bg-opacity))",
        "--tw-border-opacity": "1",
        "borderColor": "rgba(107, 114, 128, var(--tw-border-opacity))",
        "borderRadius": "0.5rem",
        "borderTopLeftRadius": "0px",
        "borderBottomLeftRadius": "0px",
        "paddingTop": "0.125rem",
        "paddingBottom": "0.125rem",
        "paddingRight": "1rem",
        "fontStyle": "normal"
      }
    }
  },
  "xl": {
    "css": {
      "nav ol > li": {
        "fontSize": "1.125rem",
        "lineHeight": [
          "1.75rem",
          "1.25rem"
        ]
      }
    }
  }
}

Ideas

I don't know much about PostCSS or Tailwind internals. However, with this experiment, I've learned a little bit. One idea that comes to mind is to allow asynchronous plugin functions so that you can have something like async theme => <plugin config>. This would allow for this hack to become less hacky.

This approach could be accompanied by a bunch of secondary tools exported from the tailwind package (or maybe as theme.<tool>, or (theme, tool1, tool2) => <> or (theme, { tool1, tool2 })), for example:

• apply("<tailwind classes>") function that returns CSS-in-JS structures
• A function or tagged template that allows writing tailwind-like CSS but returns CSS-in-JS structures
• Something like my script, that reads a CSS file, processes it, and returns the CSS-in-JS structure

Of course, the config recursivity issue is still there, so maybe tailwind could detect the current "plugin scope" and use a config without the problematic prop (which is the one being generated, hence the recursivity).

There'd be some limitations too with media-queries and pseudo-states, but maybe those could also be abstracted in a similar way with some kind of standard plugin CSS-in-JS spec? IDK, just brainstorming.

Another approach that could work would be to add an option to tailwind as a postcss plugin to work synchronously. That would leave the config loader unchanged but I'm guessing there'd be tradeoffs.

Conclusion

This hack works for me, as I don't change these styles very often, but it'd be cool if there was a more practical solution to this. Just wanted to give my two cents in case it helps push this forward.

I was actually inspired to play with this by this quote from the typography plugin README:

The customization API is currently extremely low-level in order to be as flexible as possible. We will be introducing higher-level configuration options over time as we learn what types of customizations are most common.

Have a great day, whoever's reading this :)