chore: update docs and add examples test ci (#853)

Author: ineshbose

.github/workflows/ci.yml

@@ -1,5 +1,8 @@
 name: ci
 
+env:
+  NODE_OPTIONS: --max_old_space_size=6144
+
 on:
   push:
     branches:
@@ -24,3 +27,26 @@ jobs:
       - run: pnpm build
       # - run: pnpm test:types
       - run: pnpm dev:build
+  examples:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/checkout@v4
+        with:
+          ref: docs-examples
+          path: docs-examples
+          sparse-checkout: |
+            examples
+      - run: corepack enable
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: "pnpm"
+      - run: pnpm install && pnpm dev:prepare
+      - run: pnpm link --global
+      - run: echo "  - \"docs-examples/examples/*\"" >> pnpm-workspace.yaml
+      - run: echo "  - \"!docs-examples/examples/nuxt-layers\"" >> pnpm-workspace.yaml
+      - run: echo "  - \"!docs-examples/examples/nuxtui\"" >> pnpm-workspace.yaml
+      # - run: pnpm --filter './examples/**' link @nuxtjs/tailwindcss
+      - run: pnpm install --no-frozen-lockfile
+      - run: pnpm --filter "./docs-examples/examples/**" build

docs/content/1.getting-started/1.installation.md

@@ -30,6 +30,7 @@ pnpm i -D @nuxtjs/tailwindcss
 2. If not already done, add it to your `modules` section in your `nuxt.config`:
 
 ::code-group
+
 ```ts [Nuxt 3]
 export default defineNuxtConfig({
   modules: ['@nuxtjs/tailwindcss']
@@ -41,6 +42,7 @@ export default {
   buildModules: ['@nuxtjs/tailwindcss']
 }
 ```
+
 ::
 
 ::callout{color="green" icon="i-ph-check-circle-duotone"}
@@ -127,8 +129,9 @@ Learn more about overwriting the Tailwind configuration in the [Tailwind Config]
 
 You can customize the module's behavior by using the `tailwindcss` property in `nuxt.config`:
 
-```ts [nuxt.config.ts]
+```ts [nuxt.config]
 export default defineNuxtConfig({
+  modules: ['@nuxtjs/tailwindcss'],
   tailwindcss: {
     // Options
   }

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

@@ -5,23 +5,24 @@ description: This module comes with a default Tailwind configuration file to pro
 
 ## Default configuration
 
-```js [tailwind.config.js]
-export default {
-  theme: {},
-  plugins: [],
-  content: [
-    `${srcDir}/components/**/*.{vue,js,ts}`,
-    `${srcDir}/layouts/**/*.vue`,
-    `${srcDir}/pages/**/*.vue`,
-    `${srcDir}/composables/**/*.{js,ts}`,
-    `${srcDir}/plugins/**/*.{js,ts}`,
-    `${srcDir}/utils/**/*.{js,ts}`,
-    `${srcDir}/App.{js,ts,vue}`,
-    `${srcDir}/app.{js,ts,vue}`,
-    `${srcDir}/Error.{js,ts,vue}`,
-    `${srcDir}/error.{js,ts,vue}`,
-    `${srcDir}/app.config.{js,ts}`
-  ]
+When you install the module, the default Tailwind configuration for your project would be equivalent to this:
+
+```json [tailwind.config]
+{
+  "theme": { "extend": {} },
+  "content": [
+    // all directories and extensions will correspond to your Nuxt config
+    "{srcDir}/components/**/*.{vue,js,jsx,mjs,ts,tsx}",
+    "{srcDir}/layouts/**/*.{vue,js,jsx,mjs,ts,tsx}",
+    "{srcDir}/pages/**/*.{vue,js,jsx,mjs,ts,tsx}",
+    "{srcDir}/plugins/**/*.{js,ts,mjs}",
+    "{srcDir}/composables/**/*.{js,ts,mjs}",
+    "{srcDir}/utils/**/*.{js,ts,mjs}",
+    "{srcDir}/{A,a}pp.{vue,js,jsx,mjs,ts,tsx}",
+    "{srcDir}/{E,e}rror.{vue,js,jsx,mjs,ts,tsx}",
+    "{srcDir}/app.config.{js,ts,mjs}"
+  ],
+  "plugins": []
 }
 ```
 
@@ -33,23 +34,22 @@ You can extend the default configuration:
 
 - with a [tailwind.config](#tailwindconfig) file
 - using the [config option](#config-option)
-- with the `tailwindcss:config` Nuxt hook
+- using [hooks](#hooks), such as the `tailwindcss:config`
 
-::callout{color="amber" icon="i-ph-warning-duotone"}
-The `tailwind.config` file and `config` options are subject to the [merging strategy](#merging-strategy).
+::callout{color="blue" icon="i-ph-info-duotone"}
+The provided configurations will be merged using [defu's array function merger](https://github.com/nuxt-contrib/defu#array-function-merger).
 ::
 
 ### `tailwind.config`
 
-If a `tailwind.config` file is present, it will be imported and used to overwrite the default configuration. All of the following file extensions will work by default: `.js`, `.cjs`, `.mjs`, and `.ts`. When not using the `.cjs` file extension, you need to use ESM syntax (see #549).
-
-You can configure the path with the [configPath option](/getting-started/configuration#configpath).
+If a `tailwind.config` file is present, it will be imported and used to overwrite the default configuration. All of the following file extensions will work by default: `.js`, `.cjs`, `.mjs`, and `.ts`. You can configure the path with the [`configPath` option](/getting-started/configuration#configpath).
 
 ::callout{color="blue" icon="i-ph-info-duotone"}
-This config has the highest priority to overwrite the defaults and [tailwindcss.config](#config-option).
+This config has the highest priority to overwrite the defaults and [`config` option](#config-option).
 ::
 
 ::code-group
+
 ```js [tailwind.config.js]
 import colors from 'tailwindcss/colors'
 
@@ -101,21 +101,25 @@ Learn more about the [Tailwind config](https://tailwindcss.com/docs/configuratio
 
 You can also use your `nuxt.config` file to set your Tailwind config with the `tailwindcss.config` property:
 
-```js [nuxt.config]
-import tailwindTypography from '@tailwindcss/typography'
+```ts [nuxt.config]
+import colors from 'tailwindcss/colors'
 
-export default {
+export default defineNuxtConfig({
   // ...
   tailwindcss: {
     config: {
-      plugins: [tailwindTypography]
+      theme: {
+        extend: {
+          colors: { primary: colors.green }
+        }
+      }
     }
   }
-}
+})
 ```
 
 ::callout{color="blue" icon="i-ph-info-duotone"}
-This config has less priority over the [tailwind.config.js](#tailwindconfigjs) file.
+This config option allows only simple primitive values, and has less priority over the [`tailwind.config`](#tailwindconfig) file(s).
 ::
 
 ### Hooks
@@ -163,101 +167,19 @@ Learn more about [Nuxt modules](https://nuxt.com/docs/guide/directory-structure/
 These hooks can be asynchronous (using `async/await`) and are called after merging the configurations.
 ::
 
-### Merging strategy
-
-The provided config will be merged using [defu's array function merger](https://github.com/nuxt-contrib/defu#array-function-merger).
-
-When assigning an array to the `content` property, it will be concatenated with the default value.
-
-**Example**
-
-```js{}[tailwind.config.js]
-export default {
-  content: [
-    'content/**/*.md'
-  ]
-}
-```
-
-The `content` option will be:
-
-```js
-[
-  'components/**/*.{vue,js,ts}',
-  'layouts/**/*.vue',
-  'pages/**/*.vue',
-  'composables/**/*.{js,ts}',
-  'plugins/**/*.{js,ts}',
-  'App.{js,ts,vue}',
-  'app.{js,ts,vue}',
-  'Error.{js,ts,vue}',
-  'error.{js,ts,vue}',
-  'content/**/*.md'
-]
-```
-
-If you want to fully overwrite its value, you can use a `function` that receives the default value:
-
-```js{}[tailwind.config.ts]
-import type { ModuleOptions } from '@nuxtjs/tailwindcss'
-
-const config: ModuleOptions['config'] = {
-  content (contentDefaults) {
-    return [
-      // add the defaults
-      ...contentDefaults,
-
-      // or filter only vue file patterns from defaults
-      ...contentDefaults.filter((c) => c.endsWith('*.vue')),
-
-      // add js and vue files for a directory
-      './my-components/**/*.{js,vue}',
-
-      // exclude test files if you keep them together with source
-      contentDefaults.filter(
-        c => c.endsWith('/**/*.{vue,js,ts}')
-      ).map(
-        c => c.replace('/**/*.{vue,js,ts}', '/**/!(*.{test,spec,story}).{vue,js,ts}')
-      ),
-    ]
-  }
-}
-
-export default config
-```
-
-::callout{color="blue" icon="i-ph-info-duotone"}
-This merging strategy of with a function only applies to `plugins` and `content` since the default value is defined as an `Array`.
-::
-
-### Safelisting classes
-
-If you need to safelist classes and avoid the content purging system, you need to specify the `safelist` option:
-
-```js{}[tailwind.config.js]
-module.exports = {
-  // Safelisting some classes to avoid content purge
-  safelist: [
-    'safelisted',
-    {
-      pattern: /bg-(red|green|blue)-(100|200|300)/,
-    },
-  ]
-}
-```
-
 ## Referencing in the application
 
 It can often be useful to reference Tailwind configuration values at runtime, e.g. to access some of your theme values when dynamically applying inline styles in a component.
 
 If you need resolved Tailwind config at runtime, you can enable the [exposeConfig](/getting-started/configuration#exposeconfig) option:
 
-```js{}[nuxt.config]
-export default {
+```ts [nuxt.config]
+export default defineNuxtConfig({
+  // ...
   tailwindcss: {
     exposeConfig: true
   }
-}
+})
 ```
 
 Then, import where needed from `#tailwind-config`:
@@ -272,15 +194,16 @@ 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 {
+```ts [nuxt.config]
+export default defineNuxtConfig({
+  // ...
   tailwindcss: {
     exposeConfig: {
       level: 4,
       alias: '#twcss' // if you want to change alias
     }
   }
-}
+})
 ```
 
 ```js
@@ -297,3 +220,29 @@ It is unlikely for `level` to ever be over 4 - the usual depth of a Tailwind con
 ::callout{color="blue" icon="i-ph-info-duotone"}
 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.
 ::
+
+## Tailwind CSS version
+
+If you wish to use another version of Tailwind CSS (i.e., different from the one that would be installed with this module), you can simply do so using your package manager like so:
+
+
+::code-group
+
+```bash [yarn]
+yarn add -D [email protected]
+```
+
+```bash [npm]
+npm install -D [email protected]
+```
+
+```sh [pnpm]
+pnpm i -D [email protected]
+```
+
+::
+
+::callout{color="amber" icon="i-ph-warning-duotone"}
+Be careful while downgrading Tailwind CSS as the module may also have changes compatible to specific minor versions! In such cases, be sure to go through the [release changelogs](https://github.com/nuxt-modules/tailwindcss/releases).
+::
+

docs/content/3.examples/1.basic.md

@@ -1,7 +1,6 @@
 ---
 title: Basic Usage
 description: Example usage of the module.
-toc: false
 ---
 
 This is a minimal example of a Nuxt project using the Tailwind CSS module.

docs/content/3.examples/10.module-authoring.md

@@ -0,0 +1,8 @@
+---
+title: Module Authoring
+description: Authoring a module that builds on top of this module
+---
+
+If you wish to author a Nuxt module that extends and builds on top of `@nuxtjs/tailwindcss`, like providing custom configuration, hooks, etc., you can find the recommended way in this example.
+
+:sandbox{src="https://stackblitz.com/github/nuxt-modules/tailwindcss/tree/docs-examples/examples/module-authoring"}

docs/content/3.examples/2.dark-mode.md

@@ -1,7 +1,6 @@
 ---
 title: Dark Mode
 description: Example of enabling dark mode with the module.
-toc: false
 ---
 
 This is an example using the [Tailwind Dark Mode](https://tailwindcss.com/docs/dark-mode) with the help of [`@nuxtjs/color-mode`](https://github.com/nuxt-modules/color-mode) module.

docs/content/3.examples/4.nuxt-layers.md

@@ -0,0 +1,8 @@
+---
+title: Nuxt Layers
+description: Module working with Nuxt Layers
+---
+
+In this example, the module works between different Nuxt Layers.
+
+:sandbox{src="https://stackblitz.com/github/nuxt-modules/tailwindcss/tree/docs-examples/examples/nuxt-layers"}

docs/content/3.examples/4.tailwind-plugins.md renamed to docs/content/3.examples/5.tailwind-plugins.md

@@ -1,7 +1,6 @@
 ---
 title: PostCSS Configuration
 description: Example of customising PostCSS options for Nuxt.
-toc: false
 ---
 
 <!-- TODO: Replace with another postcss plugin as tailwind supports gray colors natively. -->

docs/content/3.examples/5.postcss-config.md renamed to docs/content/3.examples/6.postcss-config.md

@@ -1,7 +1,6 @@
 ---
 title: DaisyUI
 description: Example of using the module with daisyUI and color mode.
-toc: false
 ---
 
 Example with [daisyUI](https://daisyui.com/) and [`@nuxtjs/color-mode`](https://color-mode.nuxtjs.org/).

docs/content/3.examples/6.daisyui.md renamed to docs/content/3.examples/7.daisyui.md

@@ -1,7 +1,6 @@
 ---
 title: Nuxt UI
-description: Example of Nuxt UI.
-toc: false
+description: Example of Nuxt UI
 ---
 
 Checkout [Nuxt UI](https://ui.nuxt.com) documentation.