feat: warn about unsupported tailwind config theme keys

Add detection and user-friendly warnings for unsupported theme
configuration keys in tailwind.config files. When users attempt to
extend theme with unsupported properties (spacing, borderRadius, etc.),
they now receive a clear warning message listing the unsupported keys
and directing them to open an issue on GitHub.

Currently supported: colors, fontFamily, fontSize

The warning system includes:
- Detection of unsupported keys in both theme.extend and theme
- Deduplication to prevent repeated warnings for same config file
- Clear messaging with link to GitHub issues
- Production mode bypass for performance

Author: mgcrea

src/babel/config-loader.test.ts

@@ -1,6 +1,11 @@
 import * as fs from "fs";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
-import { extractCustomTheme, findTailwindConfig, loadTailwindConfig } from "./config-loader";
+import {
+  extractCustomTheme,
+  findTailwindConfig,
+  loadTailwindConfig,
+  warnUnsupportedThemeKeys,
+} from "./config-loader";
 
 // Mock fs
 vi.mock("fs");
@@ -122,33 +127,78 @@ describe("config-loader", () => {
       const result = extractCustomTheme("/project/src/file.ts");
       expect(result).toEqual({ colors: {}, fontFamily: {}, fontSize: {} });
     });
+  });
 
-    it("should return empty theme when config has no theme", () => {
-      const configPath = "/project/tailwind.config.js";
+  describe("warnUnsupportedThemeKeys", () => {
+    it("should warn about unsupported theme keys", () => {
+      const configPath = "/project/unsupported/tailwind.config.js";
+      const mockConfig = {
+        theme: {
+          extend: {
+            colors: { brand: "#123456" },
+            spacing: { "72": "18rem" }, // Unsupported
+            borderRadius: { xl: "1rem" }, // Unsupported
+          },
+          screens: { tablet: "640px" }, // Unsupported
+        },
+      };
 
-      vi.spyOn(fs, "existsSync").mockImplementation((filepath) => filepath === configPath);
-      vi.spyOn(require, "resolve").mockReturnValue(configPath);
+      const consoleSpy = vi.spyOn(console, "warn").mockImplementation(vi.fn());
 
-      // loadTailwindConfig will be called, but we've already tested it
-      // For integration, we'd need to mock the entire flow
-      const result = extractCustomTheme("/project/src/file.ts");
+      warnUnsupportedThemeKeys(mockConfig, configPath);
 
-      // Without actual config loading, this returns empty
-      expect(result).toEqual({ colors: {}, fontFamily: {}, fontSize: {} });
+      expect(consoleSpy).toHaveBeenCalledWith(
+        expect.stringContaining("Unsupported theme configuration detected"),
+      );
+      expect(consoleSpy).toHaveBeenCalledWith(expect.stringContaining("theme.extend.spacing"));
+      expect(consoleSpy).toHaveBeenCalledWith(expect.stringContaining("theme.extend.borderRadius"));
+      expect(consoleSpy).toHaveBeenCalledWith(expect.stringContaining("theme.screens"));
+      expect(consoleSpy).toHaveBeenCalledWith(
+        expect.stringContaining("https://github.com/mgcrea/react-native-tailwind/issues/new"),
+      );
+
+      consoleSpy.mockRestore();
+    });
+
+    it("should not warn for supported theme keys only", () => {
+      const configPath = "/project/supported/tailwind.config.js";
+      const mockConfig = {
+        theme: {
+          extend: {
+            colors: { brand: "#123456" },
+            fontFamily: { custom: "CustomFont" },
+            fontSize: { huge: "48px" },
+          },
+        },
+      };
+
+      const consoleSpy = vi.spyOn(console, "warn").mockImplementation(vi.fn());
+
+      warnUnsupportedThemeKeys(mockConfig, configPath);
+
+      expect(consoleSpy).not.toHaveBeenCalled();
+
+      consoleSpy.mockRestore();
     });
 
-    it("should extract colors and fontFamily from theme.extend", () => {
-      // This would require complex mocking of the entire require flow
-      // Testing the logic: theme.extend is preferred
-      const colors = { brand: { light: "#fff", dark: "#000" } };
-      const fontFamily = { sans: ['"SF Pro"'], custom: ['"Custom Font"'] };
-      const theme = {
-        extend: { colors, fontFamily },
+    it("should only warn once per config path", () => {
+      const configPath = "/project/once/tailwind.config.js";
+      const mockConfig = {
+        theme: {
+          extend: {
+            spacing: { "72": "18rem" },
+          },
+        },
       };
 
-      // If we had the config, we'd flatten the colors and convert fontFamily
-      expect(theme.extend.colors).toEqual(colors);
-      expect(theme.extend.fontFamily).toEqual(fontFamily);
+      const consoleSpy = vi.spyOn(console, "warn").mockImplementation(vi.fn());
+
+      warnUnsupportedThemeKeys(mockConfig, configPath);
+      warnUnsupportedThemeKeys(mockConfig, configPath);
+
+      expect(consoleSpy).toHaveBeenCalledTimes(1);
+
+      consoleSpy.mockRestore();
     });
   });
 });

src/babel/config-loader.ts

@@ -15,13 +15,66 @@ export type TailwindConfig = {
       colors?: Record<string, string | Record<string, string>>;
       fontFamily?: Record<string, string | string[]>;
       fontSize?: Record<string, string | number>;
+      [key: string]: unknown;
     };
     colors?: Record<string, string | Record<string, string>>;
     fontFamily?: Record<string, string | string[]>;
     fontSize?: Record<string, string | number>;
+    [key: string]: unknown;
   };
 };
 
+/**
+ * Theme keys currently supported by react-native-tailwind
+ */
+const SUPPORTED_THEME_KEYS = new Set(["colors", "fontFamily", "fontSize", "extend"]);
+
+/**
+ * Cache for warned config paths to avoid duplicate warnings
+ */
+const warnedConfigPaths = new Set<string>();
+
+/**
+ * Check for unsupported theme extensions and warn the user
+ * @internal Exported for testing
+ */
+export function warnUnsupportedThemeKeys(config: TailwindConfig, configPath: string): void {
+  if (process.env.NODE_ENV === "production" || warnedConfigPaths.has(configPath)) {
+    return;
+  }
+
+  const unsupportedKeys: string[] = [];
+
+  // Check theme.extend keys
+  if (config.theme?.extend && typeof config.theme.extend === "object") {
+    for (const key of Object.keys(config.theme.extend)) {
+      if (!SUPPORTED_THEME_KEYS.has(key)) {
+        unsupportedKeys.push(`theme.extend.${key}`);
+      }
+    }
+  }
+
+  // Check direct theme keys (excluding 'extend')
+  if (config.theme && typeof config.theme === "object") {
+    for (const key of Object.keys(config.theme)) {
+      if (key !== "extend" && !SUPPORTED_THEME_KEYS.has(key)) {
+        unsupportedKeys.push(`theme.${key}`);
+      }
+    }
+  }
+
+  if (unsupportedKeys.length > 0) {
+    warnedConfigPaths.add(configPath);
+    console.warn(
+      `[react-native-tailwind] Unsupported theme configuration detected:\n` +
+        `  ${unsupportedKeys.join(", ")}\n\n` +
+        `  Currently supported: colors, fontFamily, fontSize\n\n` +
+        `  These extensions will be ignored. If you need support for these features,\n` +
+        `  please open an issue: https://github.com/mgcrea/react-native-tailwind/issues/new`,
+    );
+  }
+}
+
 // Cache configs per path to avoid repeated file I/O
 const configCache = new Map<string, TailwindConfig | null>();
 
@@ -111,6 +164,9 @@ export function extractCustomTheme(filename: string): CustomTheme {
     return { colors: {}, fontFamily: {}, fontSize: {} };
   }
 
+  // Warn about unsupported theme keys
+  warnUnsupportedThemeKeys(config, configPath);
+
   // Extract colors
   /* v8 ignore next 5 */
   if (config.theme.colors && !config.theme.extend?.colors && process.env.NODE_ENV !== "production") {