feat: support for more semantic injection positions

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

@@ -83,15 +83,29 @@ Learn more about it in the [Referencing in the application](/tailwind/config#ref
 
 ## `injectPosition`
 
-- Default: `0`
+- Default: `'first'`
 
-You can use any integer to adjust the position of the [global CSS](https://v3.nuxtjs.org/api/configuration/nuxt.config#css) injection, which affects the CSS priority.
+This option lets you adjust the position of the [global CSS](https://v3.nuxtjs.org/api/configuration/nuxt.config#css) injection, which affects the CSS priority. You can use multiple formats to define the position:
+
+* Use `'first'` and `'last'` literals to make Tailwind CSS first or last respectively. First position has the lowest priority, last position overrides everything and hence has the highest priority.
+* Use `{ after: 'some/existing/file.css' } ` to specify the position explicitly.
+* You can use any integer to specify absolute position in the array. This is the most fragile way, as it's easy to forget to adjust it when changing CSS settings.
 
 ```ts [nuxt.config]
 export default {
+  css: [
+    'assets/low-priorty.pcss',
+    'assets/high-priorty.pcss'
+  ],
   tailwindcss: {
-    injectPosition: 0 // equal to nuxt.options.css.unshift(cssPath)
-    // injectPosition: Infinity, // equal to nuxt.options.css.push(cssPath)
+    injectPosition: { 
+        // 'low-priority' will have lower priority than Tailwind stylesheet, 
+        // while 'high-priorty' will override it
+        after: 'assets/low-priorty.pcss'
+    }
+    // injectPosition: 'first'   // equal to nuxt.options.css.unshift(cssPath)
+    // injectPosition: 'last'    // equal to nuxt.options.css.push(cssPath)
+    // injectPosition: 1         // after 'low-priority.pcss'
   }
 }
 ```

playground/nuxt.config.ts

@@ -6,7 +6,8 @@ export default defineNuxtConfig({
     tailwindModule
   ],
   tailwindcss: {
-    exposeConfig: true
+    exposeConfig: true,
+    injectPosition: 'last'
   },
   css: [
     // Including Inter CSS is the first component to reproduce HMR issue. It also causes playground to look better,

src/module.ts

@@ -14,17 +14,29 @@ import {
   resolvePath,
   addVitePlugin
 } from '@nuxt/kit'
+import { Config } from 'tailwindcss'
 import { name, version } from '../package.json'
 import vitePlugin from './hmr'
 import defaultTailwindConfig from './tailwind.config'
+import { InjectPosition, resolveInjectPosition } from './utils'
 
 const logger = consola.withScope('nuxt:tailwindcss')
 
 export interface ModuleHooks {
   'tailwindcss:config': (tailwindConfig: any) => void
 }
 
-export default defineNuxtModule({
+export interface ModuleOptions {
+  configPath: string;
+  cssPath: string;
+  config: Config;
+  viewer: boolean;
+  exposeConfig: boolean;
+  injectPosition: InjectPosition;
+  disableHmrHotfix: boolean;
+}
+
+export default defineNuxtModule<ModuleOptions>({
   meta: {
     name,
     version,
@@ -36,13 +48,12 @@ export default defineNuxtModule({
     config: defaultTailwindConfig(nuxt.options),
     viewer: true,
     exposeConfig: false,
-    injectPosition: 0,
+    injectPosition: 'first',
     disableHmrHotfix: false
   }),
   async setup (moduleOptions, nuxt) {
     const configPath = await resolvePath(moduleOptions.configPath)
     const cssPath = await resolvePath(moduleOptions.cssPath, { extensions: ['.css', '.sass', '.scss', '.less', '.styl'] })
-    const injectPosition = ~~Math.min(moduleOptions.injectPosition, (nuxt.options.css || []).length + 1)
 
     // Include CSS file in project css
     let resolvedCss: string
@@ -56,9 +67,18 @@ export default defineNuxtModule({
       }
     }
 
-    // Inject only if this file isn't listed already by user (e.g. user may put custom path both here and in css):
+    nuxt.options.css = nuxt.options.css ?? []
     const resolvedNuxtCss = await Promise.all(nuxt.options.css.map(p => resolvePath(p)))
+
+    // Inject only if this file isn't listed already by user (e.g. user may put custom path both here and in css):
     if (!resolvedNuxtCss.includes(resolvedCss)) {
+      let injectPosition: number
+      try {
+        injectPosition = resolveInjectPosition(nuxt.options.css, moduleOptions.injectPosition)
+      } catch (e) {
+        throw new Error('failed to resolve Tailwind CSS injection position: ' + e.message)
+      }
+
       nuxt.options.css.splice(injectPosition, 0, resolvedCss)
     }
 

src/utils.ts

@@ -0,0 +1,27 @@
+export type InjectPosition = 'first' | 'last' | number | { after: string };
+
+/** Resolve human-readable inject position specification into absolute index in the array */
+export function resolveInjectPosition (css: string[], position: InjectPosition): number {
+  if (typeof (position) === 'number') {
+    return ~~Math.min(position, css.length + 1)
+  }
+
+  if (typeof (position) === 'string') {
+    switch (position) {
+      case 'first': return 0
+      case 'last': return css.length
+      default: throw new Error('invalid literal: ' + position)
+    }
+  }
+
+  if (position.after !== undefined) {
+    const index = css.indexOf(position.after)
+    if (index === -1) {
+      throw new Error('`after` position specifies a file which does not exists on CSS stack: ' + position.after)
+    }
+
+    return index + 1
+  }
+
+  throw new Error('invalid position: ' + JSON.stringify(position))
+}