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.

[Giachasidis]

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!