Tailwind Resolver - A resolveConfig() alternative for Tailwind v4

[0xstern]

I built a tool that bridges the gap between Tailwind v4's @theme variables and JavaScript runtime environments like Chart.js, Canvas, D3, or any library that needs access to your design tokens.

For v3 users: This is a resolveConfig() alternative for Tailwind v4, since v4's CSS-first approach means the old config-based approach no longer works.

Tailwind v4 uses CSS variables (--color-primary-500) which work great in CSS but are problematic when you need theme values in JavaScript. You can't use var(--color-primary) in Chart.js datasets or Canvas contexts.

tailwind-resolver parses your Tailwind files and generates fully-typed TypeScript interfaces plus runtime objects with all your theme values resolved to actual strings.

What it does

• Vite plugin for build-time generation with HMR support
• Runtime API for dynamic resolution (SSR, build scripts, etc.)
• CLI for one-off generation without a build tool
• Full TypeScript support with autocomplete for all theme properties and variants
• CSS conflict detection - automatically detects when direct CSS rules override variables and ensures runtime values match actual rendered styles
• Dynamic spacing helper - callable spacing(4) function that replicates Tailwind's calc(var(--spacing) * N) behavior

Example usage

import { defaultTheme, dark } from './generated/tailwindcss';

// Chart.js
new Chart(ctx, {
  data: {
    datasets: [{
      backgroundColor: [
        defaultTheme.colors.primary[500],  // Fully typed
        dark.colors.background             // Autocomplete works
      ]
    }]
  }
});

// Dynamic spacing (matches Tailwind's p-4, w-16, etc.)
element.style.padding = defaultTheme.spacing(4);  // 'calc(0.25rem * 4)'
element.style.width = defaultTheme.spacing(64);   // 'calc(0.25rem * 64)'

Features worth mentioning

1. Recursive @import resolution - handles complex file structures automatically
2. Nested variant support - compound selectors like [data-theme='dark'].compact work correctly
3. Automatic conflict resolution - detects CSS rules that override variables and reports them with confidence levels
4. Zero runtime dependencies - only PostCSS for parsing

Installation

npm install -D tailwind-resolver

GitHub: https://github.com/0xstern/tailwind-resolver

The library is MIT licensed and open to contributions. I'd love to hear feedback from the community, especially if anyone has edge cases or feature requests.

[mehediScriptDev]

[0xstern]

Thanks! Really appreciate the kind words.

Since the initial release, I've added a bunch more features:

Nesting Configuration - Full control over how CSS variable names are parsed into nested structures. You can limit nesting depth per namespace, control consecutive dash handling, and choose flattening modes. Example: --color-tooltip-outline-50 can be parsed as deeply nested or completely flat based on your preference.

Theme Overrides - Programmatically inject or override theme values without modifying CSS. Useful for Next.js fonts, plugin variables, or quick prototyping. Supports variant-specific overrides and wildcards.

Unresolved Variable Detection - Automatically detects var() references that couldn't be resolved and categorizes them (external plugins, self-referential, etc.) with actionable recommendations.

Tailwind Defaults Control - Granular control over which default theme categories to include. You can also use the initial keyword in CSS to exclude specific defaults (matches Tailwind v4 behavior).

The library is under active development so there will definitely be bugs and edge cases I haven't covered. I'd really appreciate if you could test it out when you have time and provide feedback on any issues or unexpected behavior. Real-world usage is the best way to find edge cases.

Full docs: https://github.com/0xstern/tailwind-resolver

[KaloudasDev]

Hello! This is an excellent contribution to the Tailwind v4 ecosystem. The tailwind-resolver library addresses a critical gap that many developers face when migrating from v3 to v4.

Key Benefits for the Community:

1. Solves Real Pain Point - JavaScript runtime access to theme values was a major missing piece in v4
2. Type Safety - Full TypeScript support with autocomplete prevents runtime errors
3. Build Tool Integration - Vite plugin with HMR makes development seamless
4. CSS Conflict Detection - This is particularly valuable for maintaining consistency

Implementation Example:

// Chart.js integration with resolved theme values
import { defaultTheme } from 'tailwind-resolver';

const chartConfig = {
  type: 'bar',
  data: {
    labels: ['Q1', 'Q2', 'Q3', 'Q4'],
    datasets: [{
      label: 'Sales',
      data: [65, 59, 80, 81],
      backgroundColor: defaultTheme.colors.primary[500],
      borderColor: defaultTheme.colors.primary[700],
      borderWidth: defaultTheme.spacing(0.5)
    }]
  },
  options: {
    scales: {
      y: {
        grid: {
          color: defaultTheme.colors.gray[200]
        }
      }
    }
  }
};

Migration Path for v3 Users:

import resolveConfig from 'tailwindcss/resolveConfig';
import tailwindConfig from './tailwind.config.js';

const theme = resolveConfig(tailwindConfig).theme;

import { defaultTheme } from 'tailwind-resolver';
// Use defaultTheme.colors, defaultTheme.spacing(), etc.

Additional Use Cases:

• Dynamic SVG generation with theme colors
• Canvas-based visualizations that match your design system
• Server-side rendering where CSS variables aren't available
• Design system documentation generation

This library effectively bridges the CSS-first approach of Tailwind v4 with the practical needs of JavaScript runtime environments. The conflict detection and TypeScript support make it production-ready for complex applications.

Great work on addressing this community need!

[0xstern]

I appreciate the support. I'm going to allow myself to give you some advice, please avoid using AI-generated content for spamming.

The more AI-generated blocks of text are shared on GitHub, the harder it becomes for people to find valuable information. I do use AI regularly to rewrite my drafts to save time overthinking my phrasing, but I don't share content just for the sake of sharing.

Testing the package and sharing feedback will provide immensely more value than complimenting or restating facts about it. So I would greatly appreciate it if you try the library and share feedback instead of sharing AI-generated descriptions of it.

What you're doing now is only hurting your reputation instead of helping it.