Nuxt3 PrimeVue TailwindCss 最小化项目初始化

前言

Nuxt 已经成为 VUE 阵营一股强大的力量。本为以 Nuxt 3.15 结合 PrimeVue 这个超好看的组件库，以及 TailwindCss，快速搭建一个 start 项目出来。

这里提一下关于UI库的选择，目前常用的 UI 库也就是 Element Plus、antd vue 以及本文的 PrimeVue。如果大项目，尤其是后台，无脑用 Element Plus 可能是一个更好的选择。前台项目，我选择了 PrimeVue。组件90多个，不比 Element Plus 少。关键是个人觉得它比较好看。至于 VUE 自己维护的 vuetify v3，完全不对我的胃口。至于 Nuxt ui，免费版的组件非常少，pro 版就收费了，直接 pass 掉。

PS：因为喜欢刨根儿问底，加上是前端新手，所以细枝末节也有很多描写，行文可能会比较罗嗦，见谅。

Nuxt 项目初始化

个人习惯使用 npm，所以本文皆以 npm 指令为样本。

1
npx nuxi init my-site 

会提示你要使用 npm、pnpm 还是 yarn等，选择一个回车就好。是否初始化 git 仓库，根据自己习惯来选。然后可以将默认项目运行起来了。

1
2
cd my-site
npm run dev

就可以在本地查看了。默认地址是 http://localhost:3000/。

安装 nuxt 模块

一、模块选择

做为一个 mini start 项目，主打一个清爽不复杂。主要考虑以下主要组件：

PrimeVue – UI 库
TailwindCss – 流行的css库

二、模块安装方式

Nuxt 模块的安装一般有以下三种方式，当然实际底层逻辑是一样的。

1. 使用 Nuxt devTools 面板安装

在浏览器中，也就是刚才运行的页面底部，点击 Nuxt DevTools 图标，唤起面板，在面板中选择 Module -> Install new Module，搜索要安装的模块，点击模块名称，会弹出安装按钮。首次运行会需要一个 Token，观察你的终端，会输出一个 token，在 DevTools 中填入即可。然后在面板中搜索要安装的模块，根据提示，点击 install 按钮。在安装前，会显示安装该模块针对 nuxt.config.ts 会有哪些修改。安装完成后，再次搜索该模块的时候，在搜索结果列表中，会显示 installed，旁边还有个小按钮，可以用于卸载。在确认前，也会显示针对 nuxt.config.ts 的修改预览。这个工具还是非常好玩儿的。

tips：此种方式最省事儿。甚至会显示要修改 nuxt.config.ts 的预览。让你知道它都做了哪些工作。

2. 参考 Nuxt 的模块网站使用 nuxi 指令安装

Nuxt 为每个支持的模块都建立了二级域名的网站，通过其文档安装，例如：npx nuxi@latest module add primevue，然后配置 nuxt.config.{ts|js}

tips: 此种安装方式可以查看文档，了解更多的内容。

3. 通过模块自己的文档来安装

比如 primevue，文档地址是 https://primevue.org/nuxt/，可以选择使用 npm、pnpm 或 yarn 安装，然后，配置 nuxt.config.{ts|js}。

tips: 此种安装方式算是模块方的权威文档。

以上三种方式大部分时候，尤其是针对一些小模块的时候，直接 DevTools 安装就好了。但涉及一些复杂的模块，还是要参考一下模块儿的官方文档。

三、安装模块

PrimeVue 安装

使用 DevTools 安装 PrimeVue。

然后我们可以参考 PrimeVue 的 Installation 文档来简单配置一下。

DevTools 只是安装了 @primevue/nuxt-module。它是一个 Nuxt 模块，作用是用于在 Nuxt 项目中集成 PrimeVue，简化PrimeVue 的配置，它的作用更像是一个粘合剂。要完整的使用 PrimeVue 还需要更多的配置。我们可以看到 PrimeVue 的文档中，Download 部分是这样写的：

1
2
3
# Using npm
npm install primevue @primevue/themes
npm install --save-dev @primevue/nuxt-module

实际上，安装完 @primevue/nuxt-module 以后，通过 npm --list --depth 可以观察到， @primevue/next-module 已经依赖了 primevue

1
2
3
4
5
6
7
8
9
├─┬ @primevue/nuxt-module@4.2.5
│ ├── @nuxt/kit@3.15.0
│ ├── @primeuix/styled@0.3.2
│ ├── @primeuix/utils@0.3.2
│ ├── @primevue/auto-import-resolver@4.2.5
│ ├── @primevue/metadata@4.2.5
│ ├── pathe@1.1.2
│ ├── primevue@4.2.5 <-- 这里
│ └── unplugin-vue-components@0.27.0

PrimeVue 的文档上，是显式的安装了 primevue 和 @primevue/themes。使用 PrimeVue 的文档中的安装方法，实际上简单、省事儿。 DevTools 的安装方式呢，实际上是好玩儿。

说明：

@primevue/themes 提供了多种预定义的主题，比如 Aura、Material、Lara、Nora，可以用于自定义 PrimeVue 组件的外观，比如图标大小，主题色系、边距等一系列定义。你也可以点击 https://primevue.org/nuxt/ 右上角的齿轮图标，打开 Theme Designer，定义自己的主题。

然后我们修改一下 Nuxt 的配置 nuxt.config.ts：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
// https://nuxt.com/docs/api/configuration/nuxt-config
import Aura from "@primevue/themes/aura";

export default defineNuxtConfig({
  compatibilityDate: "2024-11-01",
  devtools: { enabled: true },
  modules: ["@primevue/nuxt-module"],
  primevue: {
    autoImport: true, // 自动导入 PrimeVue 组件
    options: {
      ripple: true, // 是否启用涟漪效果
      inputVariant: "filled", //输入框的样式变体。filled 和 outlined。
      theme: {
        preset: Aura, // 预设的主题
        options: {
          prefix: "p", // 设置组件类名前缀。用于避免样式冲突。
          darkModeSelector: "system", // 设置暗黑模式的选择器。可以是 system（跟随系统设置）或自定义选择器。
          cssLayer: false, // 启用或禁用 CSS 层。用于控制样式的层级。
        },
      },
    },
  },
});

然后我们验证一下是否可用。在 app.vue 增加个按钮

1
2
3
4
5
6
7
<template>
  <div>
    <Button label="Verify" /> <!-- 增加这一行 -->
    <NuxtRouteAnnouncer />
    <NuxtWelcome />
  </div>
</template>

然后刷新页面可以看到按钮的样子了。默认是绿色的。甚至暗黑模式跟随系统也是生效的。调整你系统的主题颜色，可以看到已经发生变化了。

这里关键的一点是 preset: Aura，当使用主题时，可以看到按钮的样式，并且能做到跟随系统自动切换暗黑模式。可以注释掉这行观察一下效果，就变成了无样式模式。

下一步，让我们做个 Header 头出来，不过为了方便以后使用 TailwindCss, 我们需要先安装一下 TailwindCss。

TailwindCss 安装

参考 TailwindCss 文档，有两种安装方式，一种是标准安装 Standard installation 另一种是 Using Nuxt Modules。

然后 PrimeVue 文档 https://tailwind.primevue.org/nuxt/ 也提到可以选择安装 @nuxtjs/tailwindcss module 或者手动安装 Tailwind CSS;

先安装 tailwindcss 模块

1
2
3
npx nuxi@latest module add tailwindcss
# 不加 --ts 生成的是js类型的的配置文件，加上 --ts 会生成 wailwind.config.ts
npx tailwindcss init --ts

会发现终端 npm run dev 会报一个错：

1
2
 ERROR (node:42178) ExperimentalWarning: CommonJS module [my-site目录]/.nuxt/tailwind.config.cjs is loading ES Module [my-site目录]/node_modules/@nuxtjs/tailwindcss/dist/runtime/merger.js using require().
Support for loading ES Module in require() is an experimental feature and might change at any time

这是加载错误，看了一圈 github 上的反馈，可以先使用 nightly 版本解决此报错。

package.json 中修改版本：

1
"@nuxtjs/tailwindcss": "npm:@nuxtjs/tailwindcss@nightly",

然后执行 npm update 来更新版本，目前看此问题已经暂时解决，等后续稳定版本。我记得我曾经按 tailwindCss 网站上的手动安装方式安装过，也没有此报错。所以在此特别记录一下。因为看到这种错误，实在是很不爽。不过话说回来，开发团队在圣诞节假期也在处理和解决问题，这是非常值得用户高兴的。等过几天发布稳定版本以后，就不会报这个错了。

其实也可以选择显式的安装一下 tailwindcss, 但实际上 @nuxtjs/tailwindcss 已经依赖了 tailwindcss，所以不装也可以。如果css中的 @tailwind base; 有下划线提示，重启一下 vscode 就可以了。

app.vue 中 <div> 里增加一行内容测试一下

1
<h1 class="text-3xl font-bold underline">Hello world!</h1>

现在重新启动本地服务

1
npm run dev

启时动，可以看到控制台提示：Using default Tailwind CSS file。不过是因为现在用的是 nightly 版本。正式版的提示还不是这样。正式版还会在控制台提示一个本地的地址，是一个 taildwind css 的样式展示页面。方便我们预览不同样式是什么效果。然后刷新前端页面，如果看到粗体、有下划线的 Hello World! 就说明成功了。（等正式版不报错了，我换成正式版再看看要不要修改这段描述）。

制作一个头部导航

为了演示效果，我们制作一个头部导航菜单，包含logo、菜单和登录注册按钮。

先生成一个header组件，文件:components/AppHeader.vue:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
<template>
  <header class="fixed top-0 left-0 w-full backdrop-blur-md border-b z-50">
    <div class="mx-auto px-4 sm:px-6 lg:px-8 max-w-7xl flex items-center justify-between gap-3 h-[60px]">
      <!-- 左侧 Logo -->
      <div class="lg:flex-1 flex items-center gap-1.5 min-w-0">
        <NuxtLink to="/" class="flex items-center gap-2">
          <div class="w-6 h-6 flex-shrink-0">
            <!-- 先用 favicon 代替logo图片 -->
            <img src="/favicon.ico" alt="Logo" class="w-full h-full object-contain">
          </div>
          <span class="text-base font-medium">Site Name</span>
        </NuxtLink>
      </div>

      <!-- 中间导航 -->
      <nav class="items-center gap-x-8 hidden lg:flex">
        <NuxtLink 
          v-for="item in navItems" 
          :key="item.path"
          :to="item.path"
          class="text-sm font-medium hover:text-primary-500"
        >
          {{ item.name }}
        </NuxtLink>
      </nav>

      <!-- 右侧功能区 -->
      <div class="flex items-center justify-end lg:flex-1 gap-1.5">
        <Button label="登录" class="mx-2" link />
        <Button label="注册" severity="primary" />
      </div>
    </div>
  </header>
</template>

<script setup lang="ts">
import { ref } from 'vue'

const navItems = ref([
  { name: '首页', path: '/' },
  { name: '产品', path: '/products' },
  { name: '关于', path: '/about' }
])
</script>

组件目前是 components 目录，默认的组件都放这里，然后使用组件文件名加上尖括号就可以引入了。关于 Nuxt 的目录结构可以参考这里。

然后在app.vue 引入这个组件。app.vue

1
2
3
4
5
6
7
8
9
<template>
  <div>
    <AppHeader />
    <main class="pt-[60px] min-h-[calc(100vh-60px)]">
      <NuxtRouteAnnouncer />
      <NuxtWelcome />
    </main>
  </div>
</template>

效果出来了。

项目代码

好，这篇文章描述了如何从零开始搭建一个 Nuxt + primeVue + taildwind css 的应用。代码放在了：https://github.com/wkii/nuxt-primevue-tailwindcss-starter，有需要自取。

后记

这只是最小化搭建，其实还有很多没有配置，比如 eslint 等等。但即然是最小化，主要目的是学习如何从零开始，为什么要安装某个组件，如何安装，怎么确定安装好了。所谓万事开头难，第一步迈出去了，后面就知道怎么走了。

优秀的项目就像是艺术品（永远不会有绝对的完美，这不，我就碰上bug了），欣赏它，观察它的细节，就是仔细的欣赏艺术品。基于它们设计我们自己的产品，也是在制作属于我们自己的艺术品。

一直有期待，永远有期待。