Merge pull request #51 from dcastil/feature/37/add-plugin-documentation

Feature/37/add-plugin-documentation

README.md

@@ -169,6 +169,7 @@ function extendTailwindMerge(
     configExtension: Partial<Config>,
     ...createConfig: Array<(config: Config) => Config>
 ): TailwindMerge
+function extendTailwindMerge(...createConfig: Array<(config: Config) => Config>): TailwindMerge
 ```
 
 Function to create merge function with custom config.
@@ -206,6 +207,12 @@ Additionally you can pass multiple `createConfig` functions (more to that in [`c
 const customTwMerge = extendTailwindMerge({ … }, withSomePlugin)
 ```
 
+If you only use plugins, you can omit the `configExtension` object as well.
+
+```ts
+const customTwMerge = extendTailwindMerge(withSomePlugin)
+```
+
 ### `createTailwindMerge`
 
 ```ts
@@ -310,6 +317,37 @@ interface Config { … }
 
 TypeScript type for config object. Useful if you want to build a `createConfig` function but don't want to define it inline in [`extendTailwindMerge()`](#extendtailwindmerge) or [`createTailwindMerge()`](#createtailwindmerge).
 
+## Writing plugins
+
+This library supports classes of the core Tailwind library out of the box, but not classes of any plugins. But it's possible and hopefully easy to write third-party plugins for tailwind-merge. In case you want to write a plugin, I welcome you to follow these steps:
+
+-   Create a package called `tailwind-merge-magic-plugin` with tailwind-merge as peer dependency which exports a function `withMagic` and replace "magic" with your plugin name.
+-   This function would be ideally a `createConfig` function which takes a config object as argument and returns the modified config object.
+-   Use the [`validators`](#validators) and [`mergeConfigs()`](#mergeconfigs) from tailwind-merge to extend the config with magic.
+
+Here is an example of how a plugin could look like:
+
+```ts
+import { mergeConfigs, validators, Config } from 'tailwind-merge'
+
+export function withMagic(config: Config): Config {
+    return mergeConfigs(config, {
+        classGroups: {
+            magic: [{ magic: ['1', '2'] }],
+        },
+    })
+}
+```
+
+This plugin can then be used like this:
+
+```ts
+import { extendTailwindMerge } from 'tailwind-merge'
+import { withMagic } from 'tailwind-merge-magic-plugin'
+
+const twMerge = extendTailwindMerge(withMagic)
+```
+
 ## Versioning
 
 This package follows the [SemVer](https://semver.org) versioning rules. More specifically:

src/extend-tailwind-merge.ts

@@ -6,11 +6,13 @@ import { Config } from './types'
 type CreateConfigSubsequent = (config: Config) => Config
 
 export function extendTailwindMerge(
-    configExtension: Partial<Config>,
+    configExtension: Partial<Config> | CreateConfigSubsequent,
     ...createConfig: CreateConfigSubsequent[]
 ) {
-    return createTailwindMerge(
-        () => mergeConfigs(getDefaultConfig(), configExtension),
-        ...createConfig
-    )
+    return typeof configExtension === 'function'
+        ? createTailwindMerge(getDefaultConfig, configExtension, ...createConfig)
+        : createTailwindMerge(
+              () => mergeConfigs(getDefaultConfig(), configExtension),
+              ...createConfig
+          )
 }

tests/extend-tailwind-merge.test.ts

@@ -62,3 +62,34 @@ test('extendTailwindMerge works corectly with multiple configs', () => {
     expect(tailwindMerge('p-10 p-20')).toBe('p-20')
     expect(tailwindMerge('hover:focus:p-10 focus:hover:p-20')).toBe('focus:hover:p-20')
 })
+
+test('extendTailwindMerge works corectly with function config', () => {
+    const tailwindMerge = extendTailwindMerge((config) => ({
+        ...config,
+        cacheSize: 20,
+        classGroups: {
+            ...config.classGroups,
+            fooKey: [{ fooKey: ['bar', 'baz'] }],
+            fooKey2: [{ fooKey: ['qux', 'quux'] }, 'other-2'],
+            otherKey: ['nother', 'group'],
+        },
+        conflictingClassGroups: {
+            ...config.conflictingClassGroups,
+            fooKey: ['otherKey'],
+            otherKey: ['fooKey', 'fooKey2'],
+        },
+    }))
+
+    expect(tailwindMerge('')).toBe('')
+    expect(tailwindMerge('my-prefix:fooKey-bar my-prefix:fooKey-baz')).toBe('my-prefix:fooKey-baz')
+    expect(tailwindMerge('other-prefix:fooKey-bar other-prefix:fooKey-baz')).toBe(
+        'other-prefix:fooKey-baz'
+    )
+    expect(tailwindMerge('group fooKey-bar')).toBe('fooKey-bar')
+    expect(tailwindMerge('fooKey-bar group')).toBe('group')
+    expect(tailwindMerge('group other-2')).toBe('group other-2')
+    expect(tailwindMerge('other-2 group')).toBe('group')
+
+    expect(tailwindMerge('p-10 p-20')).toBe('p-20')
+    expect(tailwindMerge('hover:focus:p-10 focus:hover:p-20')).toBe('focus:hover:p-20')
+})