feat: more customisable configuration (#743)

* chore: initial

* chore: undo pnpm stuff for now

* chore: undo pnpm stuff for now

* chore: revert ting

* chore: add test

* chore: draft viewer test

Author: ineshbose

build.config.ts

@@ -2,8 +2,7 @@ import { defineBuildConfig } from 'unbuild'
 
 export default defineBuildConfig({
   externals: [
-    'pathe',
-    'minimatch'
+    'pathe'
   ],
   failOnWarn: false
 })

docs/content/1.getting-started/2.options.md

@@ -83,41 +83,14 @@ If you need to resolve the tailwind config in runtime, you can enable the `expos
 export default {
   tailwindcss: {
     exposeConfig: true
+    // or, for more customisation
+    // exposeConfig: { level: 2, alias: '#tailwind-config' }
   }
 }
 ```
 
 Learn more about it in the [Referencing in the application](/tailwind/config#referencing-in-the-application) section.
 
-## `exposeLevel`
-
-- Default: `2`
-
-If you want to only import *really* specific parts of your tailwind config, you can enable imports for each property in the config:
-
-```ts [nuxt.config]
-export default {
-  tailwindcss: {
-    exposeConfig: true,
-    exposeLevel: 3
-  }
-}
-```
-
-This is only relevant when [`exposeConfig`](/getting-started/options#exposeconfig) is set to `true`. Setting `exposeLevel` to ≤ 0 will only expose root properties.
-
-::alert{type="warning"}
-
-It is unlikely for `exposeLevel` to ever be over 4 - the usual depth of a Tailwind config. A higher value is also likely to increase boot-time and disk space in dev. Refer to the [Nuxt Virtual File System](https://nuxt.com/docs/guide/directory-structure/nuxt#virtual-file-system) to see generated files.
-
-::
-
-::alert{type="info"}
-
-Named exports for properties below [root options](https://tailwindcss.com/docs/configuration#configuration-options) are prefixed with `_` (`_colors`, `_900`, `_2xl`) to ensure safe variable names. You can use default imports to provide any identifier or rename named imports using `as`. Properties with unsafe variable names (`spacing['1.5']`, `height['1/2']`, `keyframes.ping['75%, 100%']`) do not get exported individually.
-
-::
-
 ## `injectPosition`
 
 - Default: `'first'`
@@ -188,6 +161,7 @@ To disable the viewer during development, set its value to `false`:
 export default {
   tailwindcss: {
     viewer: false
+    // viewer: { endpoint: '/_tailwind' }
   }
 }
 ```

docs/content/2.tailwind/1.config.md

@@ -267,8 +267,7 @@ If you need resolved Tailwind config at runtime, you can enable the [exposeConfi
 ```js{}[nuxt.config]
 export default {
   tailwindcss: {
-    exposeConfig: true,
-    // exposeLevel: 1,  // determines tree-shaking (optional)
+    exposeConfig: true
   }
 }
 ```
@@ -281,19 +280,36 @@ import tailwindConfig from '#tailwind-config'
 
 // Import only part which is required to allow tree-shaking
 import { theme } from '#tailwind-config'
+```
+
+Please be aware this adds `~19.5KB` (`~3.5KB`) to the client bundle size. If you want to only import _really_ specific parts of your tailwind config, you can enable imports for each property in the config:
+
+```js{}[nuxt.config]
+export default {
+  tailwindcss: {
+    exposeConfig: {
+      level: 4,
+      alias: '#twcss' // if you want to change alias
+    }
+  }
+}
+```
 
-// Import within properties for further tree-shaking (based on exposeLevel)
-import screens from '#tailwind-config/theme/screens'  // default import
-import { _neutral } from '#tailwind-config/theme/colors'  // named (with _ prefix)
-import { _800 as slate800 } from '#tailwind-config/theme/colors/slate'  // alias
+```js
+// Import within properties for further tree-shaking
+import screens from '#twcss/theme/screens'  // default import
+import { _neutral } from '#twcss/theme/colors'  // named (with _ prefix)
+import { _800 as slate800 } from '#twcss/theme/colors/slate'  // alias
 ```
 
 ::alert{type="warning"}
 
-  Please be aware this adds `~19.5KB` (`~3.5KB`) to the client bundle size.
+It is unlikely for `level` to ever be over 4 - the usual depth of a Tailwind config. A higher value is also likely to increase boot-time and disk space in dev. Refer to the [Nuxt Virtual File System](https://nuxt.com/docs/guide/directory-structure/nuxt#virtual-file-system) to see generated files.
 
 ::
 
-::alert
-Import types are only provided through the `#tailwind-config/*` alias.
+::alert{type="info"}
+
+Named exports for properties below [root options](https://tailwindcss.com/docs/configuration#configuration-options) are prefixed with `_` (`_colors`, `_900`, `_2xl`) to ensure safe variable names. You can use default imports to provide any identifier or rename named imports using `as`. Properties with unsafe variable names (`spacing['1.5']`, `height['1/2']`, `keyframes.ping['75%, 100%']`) do not get exported individually.
+
 ::

docs/content/2.tailwind/2.viewer.md

@@ -4,7 +4,7 @@ Visualize your Tailwind configuration with the viewer.
 
 ---
 
-Nuxt Tailwind exposes a `/_tailwind/` route in development, allowing you to quickly visualize your Tailwind configuration with easy copy-pasting (thanks to the awesome [tailwind-config-viewer](https://github.com/rogden/tailwind-config-viewer) package ✨).
+By default, the module will expose a `/_tailwind/` route in development, so that you can quickly visualize your Tailwind configuration with easy copy-pasting (thanks to the awesome [tailwind-config-viewer](https://github.com/rogden/tailwind-config-viewer) package ✨).
 
 The viewer is available starting from version  `v3.4.0` of `@nuxtjs/tailwindcss`.
 

src/module.ts

@@ -22,7 +22,9 @@ import { configMerger } from './utils'
 import {
   resolveModulePaths,
   resolveCSSPath,
-  resolveInjectPosition
+  resolveInjectPosition,
+  resolveExposeConfig,
+  resolveViewerConfig
 } from './resolvers'
 import createTemplates from './templates'
 import vitePlugin from './vite-hmr'
@@ -82,7 +84,8 @@ export default defineNuxtModule<ModuleOptions>({
     // Expose resolved tailwind config as an alias
     // https://tailwindcss.com/docs/configuration/#referencing-in-javascript
     if (moduleOptions.exposeConfig) {
-      createTemplates(resolvedConfig, moduleOptions.exposeLevel, nuxt)
+      const exposeConfig = resolveExposeConfig({ level: moduleOptions.exposeLevel, ...(typeof moduleOptions.exposeConfig === 'object' ? moduleOptions.exposeConfig : {})})
+      createTemplates(resolvedConfig, exposeConfig, nuxt)
       isNuxt2() && addTemplate({ filename: 'tailwind.config.cjs', getContents: () => `module.exports = ${JSON.stringify(resolvedConfig, null, 2)}` })
     }
 
@@ -154,7 +157,8 @@ export default defineNuxtModule<ModuleOptions>({
       // Add _tailwind config viewer endpoint
       // TODO: Fix `addServerHandler` on Nuxt 2 w/o Bridge
       if (moduleOptions.viewer) {
-        setupViewer(tailwindConfig, nuxt)
+        const viewerConfig = resolveViewerConfig(moduleOptions.viewer)
+        setupViewer(tailwindConfig, viewerConfig, nuxt)
 
         nuxt.hook('devtools:customTabs', (tabs) => {
           tabs.push({
@@ -163,7 +167,7 @@ export default defineNuxtModule<ModuleOptions>({
             icon: 'logos-tailwindcss-icon',
             view: {
               type: 'iframe',
-              src: '/_tailwind/'
+              src: viewerConfig.endpoint
             }
           })
         })

src/resolvers.ts

@@ -1,7 +1,8 @@
 import { existsSync } from 'fs'
+import { defu } from 'defu'
 import { join, relative, resolve } from 'pathe'
 import { addTemplate, createResolver, findPath, useNuxt, tryResolveModule, resolveAlias } from '@nuxt/kit'
-import type { Arrayable, InjectPosition, ModuleOptions } from './types'
+import type { Arrayable, ExposeConfig, InjectPosition, ModuleOptions, ViewerConfig } from './types'
 
 /**
  * Resolves all configPath values for an application
@@ -112,6 +113,17 @@ export async function resolveCSSPath (cssPath: ModuleOptions['cssPath'], nuxt =
   }
 }
 
+/**
+ * Resolves a boolean | object as an object with defaults
+ * @param config
+ * @param fb
+ *
+ * @returns object
+ */
+const resolveBoolObj = <T, U extends Record<string, any>>(config: T, fb: U): U => defu(typeof config === 'object' ? config : {}, fb)
+export const resolveViewerConfig = (config: ModuleOptions['viewer']): ViewerConfig => resolveBoolObj(config, { endpoint: '_tailwind' })
+export const resolveExposeConfig = (config: ModuleOptions['exposeConfig']): ExposeConfig => resolveBoolObj(config, { alias: '#tailwind-config', level: 2 })
+
 /**
  * Resolve human-readable inject position specification into absolute index in the array
  *

src/templates.ts

@@ -1,7 +1,7 @@
 import { dirname, join } from 'pathe'
 import { useNuxt, addTemplate } from '@nuxt/kit'
 import { isJSObject, NON_ALPHANUMERIC_RE } from './utils'
-import type { TWConfig } from './types'
+import type { ExposeConfig, TWConfig } from './types'
 
 /**
  * Creates MJS exports for properties of the config
@@ -10,15 +10,15 @@ import type { TWConfig } from './types'
  * @param maxLevel maximum level of depth
  * @param nuxt nuxt app
  */
-export default function createTemplates (resolvedConfig: Partial<TWConfig>, maxLevel: number, nuxt = useNuxt()) {
+export default function createTemplates (resolvedConfig: Partial<TWConfig>, config: ExposeConfig, nuxt = useNuxt()) {
   const dtsContent: Array<string> = []
 
   const populateMap = (obj: any, path: string[] = [], level = 1) => {
     Object.entries(obj).forEach(([key, value = {} as any]) => {
       const subpath = path.concat(key).join('/')
 
       if (
-        level >= maxLevel || // if recursive call is more than desired
+        level >= config.level || // if recursive call is more than desired
         !isJSObject(value) || // if its not an object, no more recursion required
         Object.keys(value).find(k => !k.match(NON_ALPHANUMERIC_RE)) // object has non-alphanumeric property (unsafe var name)
       ) {
@@ -30,13 +30,13 @@ export default function createTemplates (resolvedConfig: Partial<TWConfig>, maxL
             filename: `tailwind.config/${subpath}.mjs`,
             getContents: () => `${validKeys.map(i => `const _${i} = ${JSON.stringify(value[i])}`).join('\n')}\nconst config = { ${validKeys.map(i => `"${i}": _${i}, `).join('')}${invalidKeys.map(i => `"${i}": ${JSON.stringify(value[i])}, `).join('')} }\nexport { config as default${validKeys.length > 0 ? ', _' : ''}${validKeys.join(', _')} }`
           })
-          dtsContent.push(`declare module "#tailwind-config/${subpath}" { ${validKeys.map(i => `export const _${i}: ${JSON.stringify(value[i])};`).join('')} const defaultExport: { ${validKeys.map(i => `"${i}": typeof _${i}, `).join('')}${invalidKeys.map(i => `"${i}": ${JSON.stringify(value[i])}, `).join('')} }; export default defaultExport; }`)
+          dtsContent.push(`declare module "${config.alias}/${subpath}" { ${validKeys.map(i => `export const _${i}: ${JSON.stringify(value[i])};`).join('')} const defaultExport: { ${validKeys.map(i => `"${i}": typeof _${i}, `).join('')}${invalidKeys.map(i => `"${i}": ${JSON.stringify(value[i])}, `).join('')} }; export default defaultExport; }`)
         } else {
           addTemplate({
             filename: `tailwind.config/${subpath}.mjs`,
             getContents: () => `export default ${JSON.stringify(value, null, 2)}`
           })
-          dtsContent.push(`declare module "#tailwind-config/${subpath}" { const defaultExport: ${JSON.stringify(value)}; export default defaultExport; }`)
+          dtsContent.push(`declare module "${config.alias}/${subpath}" { const defaultExport: ${JSON.stringify(value)}; export default defaultExport; }`)
         }
       } else {
         // recurse through nested objects
@@ -47,7 +47,7 @@ export default function createTemplates (resolvedConfig: Partial<TWConfig>, maxL
           filename: `tailwind.config/${subpath}.mjs`,
           getContents: () => `${values.map(v => `import _${v} from "./${key}/${v}.mjs"`).join('\n')}\nconst config = { ${values.map(k => `"${k}": _${k}`).join(', ')} }\nexport { config as default${values.length > 0 ? ', _' : ''}${values.join(', _')} }`
         })
-        dtsContent.push(`declare module "#tailwind-config/${subpath}" {${Object.keys(value).map(v => ` export const _${v}: typeof import("#tailwind-config/${join(`${key}/${subpath}`, `../${v}`)}")["default"];`).join('')} const defaultExport: { ${values.map(k => `"${k}": typeof _${k}`).join(', ')} }; export default defaultExport; }`)
+        dtsContent.push(`declare module "${config.alias}/${subpath}" {${Object.keys(value).map(v => ` export const _${v}: typeof import("${config.alias}/${join(`${key}/${subpath}`, `../${v}`)}")["default"];`).join('')} const defaultExport: { ${values.map(k => `"${k}": typeof _${k}`).join(', ')} }; export default defaultExport; }`)
       }
     })
   }
@@ -61,14 +61,14 @@ export default function createTemplates (resolvedConfig: Partial<TWConfig>, maxL
     write: true
   })
 
-  dtsContent.push(`declare module "#tailwind-config" {${configOptions.map(v => ` export const ${v}: typeof import("${join('#tailwind-config', v)}")["default"];`).join('')} const defaultExport: { ${configOptions.map(v => `"${v}": typeof ${v}`)} }; export default defaultExport; }`)
+  dtsContent.push(`declare module "${config.alias}" {${configOptions.map(v => ` export const ${v}: typeof import("${join(config.alias, v)}")["default"];`).join('')} const defaultExport: { ${configOptions.map(v => `"${v}": typeof ${v}`)} }; export default defaultExport; }`)
   const typesTemplate = addTemplate({
     filename: 'tailwind.config.d.ts',
     getContents: () => dtsContent.join('\n'),
     write: true
   })
 
-  nuxt.options.alias['#tailwind-config'] = dirname(template.dst)
+  nuxt.options.alias[config.alias] = dirname(template.dst)
   nuxt.hook('prepare:types', (opts) => {
     opts.references.push({ path: typesTemplate.dst })
   })

src/types.ts

@@ -1,11 +1,39 @@
-export type TWConfig = import('tailwindcss').Config
-export type Arrayable<T> = T | Array<T>
-export type InjectPosition = 'first' | 'last' | number | { after: string };
+export type TWConfig = import("tailwindcss").Config;
+export type Arrayable<T> = T | Array<T>;
+export type InjectPosition = "first" | "last" | number | { after: string };
 
 interface ExtendTailwindConfig {
-  content?: TWConfig['content'] | ((contentDefaults: Array<string>) => TWConfig['content']);
+  content?:
+    | TWConfig["content"]
+    | ((contentDefaults: Array<string>) => TWConfig["content"]);
 }
 
+type BoolObj<T extends Record<string, any>> = boolean | Partial<T>;
+
+export type ViewerConfig = {
+  /**
+   * The endpoint for the viewer
+   *
+   * @default '/_tailwind'
+   */
+  endpoint: string
+};
+
+export type ExposeConfig = {
+  /**
+   * Import name for the configuration
+   *
+   * @default '#tailwind-config'
+   */
+  alias: string;
+  /**
+   * Deeper references within configuration for optimal tree-shaking.
+   *
+   * @default 2
+   */
+  level: number
+};
+
 export interface ModuleOptions {
   /**
    * The path of the Tailwind configuration file. The extension can be omitted, in which case it will try to find a `.js`, `.cjs`, `.mjs`, or `.ts` file.
@@ -28,19 +56,20 @@ export interface ModuleOptions {
   /**
    * [tailwind-config-viewer](https://github.com/rogden/tailwind-config-viewer) usage *in development*
    *
-   * @default true
+   * @default true // { endpoint: '_tailwind' }
    */
-  viewer: boolean;
+  viewer: BoolObj<ViewerConfig>;
   /**
    * Usage of configuration references in runtime. See https://tailwindcss.nuxtjs.org/tailwind/config#referencing-in-the-application
    *
-   * @default false
+   * @default false // if true, { alias: '#tailwind-config', level: 2 }
    */
-  exposeConfig: boolean;
+  exposeConfig: BoolObj<ExposeConfig>;
   /**
    * Deeper references within configuration for optimal tree-shaking.
    *
    * @default 2
+   * @deprecated use exposeConfig as object
    */
   exposeLevel: number;
   /**

src/viewer.ts

@@ -2,10 +2,10 @@ import { underline, yellow } from 'colorette'
 import { eventHandler, sendRedirect } from 'h3'
 import { addDevServerHandler, isNuxt2, isNuxt3, useLogger, useNuxt } from '@nuxt/kit'
 import { withTrailingSlash, withoutTrailingSlash, joinURL } from 'ufo'
-import type { TWConfig } from './types'
+import type { TWConfig, ViewerConfig } from './types'
 
-export default async function (twConfig: Partial<TWConfig>, nuxt = useNuxt()) {
-  const route = joinURL(nuxt.options.app?.baseURL, '/_tailwind')
+export default async function (twConfig: Partial<TWConfig>, config: ViewerConfig, nuxt = useNuxt()) {
+  const route = joinURL(nuxt.options.app?.baseURL, config.endpoint)
   // @ts-ignore
   const createServer = await import('tailwind-config-viewer/server/index.js').then(r => r.default || r) as any
   const routerPrefix = isNuxt3() ? route : undefined