使用 Nx 的 Nuxt 应用生成器从零搭建 Nuxt 3/4 应用【免费下载链接】nxThe Monorepo Platform that amplifies both developers and AI agents. Nx optimizes your builds, scales your CI, and fixes failed PRs automatically. Ship in half the time.项目地址: https://gitcode.com/GitHub_Trending/nx/nxnx/nuxt是 Nx 官方提供的 Nuxt 插件其核心生成器nx/nuxt:app可以在 Nx 工作区内一键创建结构完整、开箱即用的 Nuxt 应用。本指南以 packages/nuxt/docs/application-examples.md 为骨架结合nx/nuxt插件的源码实现完整讲解生成器的产物结构、全部命令行选项、内置页面/组件/API 端点以及如何基于nx/vue:component生成器继续扩展页面与组件。读完本文你将能够熟练使用nx/nuxt:app在任意目录生成应用、切换单元测试与 E2E 测试方案、使用纯 JavaScript 开发并对生成器的底层执行流程有源码级的认识。生成器概览nx/nuxt:app在 packages/nuxt/generators.json 中nx/nuxt插件注册了三个生成器生成器别名说明nx/nuxt:initng-add初始化插件内部使用hidden: truenx/nuxt:applicationapp创建 Nuxt 应用nx/nuxt:storybook-configuration—为 Nuxt 应用配置 Storybook其中application生成器的工厂函数指向applicationGeneratorInternal见 application.ts 与 generators.json其入口在 packages/nuxt/src/generators/application/。此外generators.json通过extends: [nx/vue]继承了 Vue 插件的全部生成器——这正是文档中可以直接使用nx/nuxt:component生成组件的原因。生成的应用目录结构执行nx g nx/nuxt:app my-nuxt-app后生成的应用遵循 Nuxt 官方推荐的 目录结构完整结构如下my-nuxt-app ├── nuxt.config.ts ├── project.json ├── src │ ├── app.vue │ ├── assets │ │ └── css │ │ └── styles.css │ ├── components │ │ └── NxWelcome.vue │ ├── pages │ │ ├── about.vue │ │ └── index.vue │ ├── public │ │ └── favicon.ico │ └── server │ ├── api │ │ └── greet.ts │ └── tsconfig.json ├── tsconfig.app.json ├── tsconfig.json ├── tsconfig.spec.json └── vitest.config.ts从源码看这套结构来自 packages/nuxt/src/generators/application/files/ 下的两套模板base/使用src/目录Nuxt 3 默认useAppDir为 falseapp-dir/使用app/目录Nuxt 4 默认useAppDir为 true。模板选择逻辑位于 application.tsconst templateDir options.useAppDir ? app-dir : base;随后通过generateFiles将模板渲染到目标项目根目录。默认值判定在 normalize-options.ts插件会检测工作区安装的 Nuxt 主版本nuxtMajorVersion 4时useAppDir默认开启。各文件职责生成器通过generateFiles渲染模板后还会依次执行createTsConfig、updateGitIgnore、addLinting、addVitest可选、nuxtInitGenerator、addE2e等步骤完整调用链见 application.ts最终在项目根目录写入project.jsonNx 项目配置projectType: applicationsourceRoot指向src或app目录由addProjectConfiguration写入tsconfig.json/tsconfig.app.json/tsconfig.spec.json分层 TS 配置其中tsconfig.spec.json会include生成的.nuxt/nuxt.d.ts见 add-vitest.tsvitest.config.ts仅当unitTestRunnervitest时生成见下文nuxt.config.ts应用级 Nuxt 配置src/下的页面、组件、静态资源与 server 端点。生成的应用默认包含哪些内容新应用默认自带以下内容与文档一致且可在模板文件中逐一验证两个页面src/pages/index.vue与src/pages/about.vue。其中首页模板 index.vue__tmpl__ 渲染NxWelcome title% title % /一个组件src/components/NxWelcome.vue。该组件由 files/nx-welcome/ 目录中的模板生成并根据当前 Nx Cloud 绑定状态分为claimed已认领、unclaimed可认领与not-configured未配置三个变体对应模板子目录一个 greet API 端点src/server/api/greet.ts访问/api/greet返回 JSON。模板源码见 greet.ts__tmpl__它使用 h3 的defineEventHandler与getQuery支持?name查询参数import { defineEventHandler, getQuery } from h3; export default defineEventHandler((event) { const q getQuery(event); const projectName q.name || World; return { message: Hello ${projectName}, }; });访问/api/greet?nameNx将返回{message:Hello Nx}Vitest 配置vitest.config.ts与tsconfig.spec.json详见下文单元测试一节应用入口src/app.vue模板见 app.vue__tmpl__。它包含指向首页和关于页的NuxtLink导航以及用于渲染当前页面内容的nuxt-page /组件。同时生成的nuxt.config.ts模板见 nuxt.config.ts__tmpl__预置了与 Nx 工作区集成的关键配置export default defineNuxtConfig({ workspaceDir: % offsetFromRoot %, // 指向 Nx 工作区根目录 srcDir: src, // 源码目录 devtools: { enabled: true }, devServer: { host: localhost, port: 4200, // 默认开发端口 }, typescript: { typeCheck: true, tsConfig: { extends: ../% relativePathToRootTsConfig %, }, }, imports: { autoImport: true }, css: [~/assets/css/styles.css], // 选择 style 为 none 时不生成 vite: { plugins: [nxViteTsPaths()], // 让 Vite 解析 Nx 的 TS 路径别名 }, });其中nxViteTsPaths()来自nx/vite/plugins/nx-tsconfig-paths.plugin确保 Nuxt 的 Vite 构建能解析 Nx 工作区中的 TypeScript 路径映射style: none时模板中的css配置块会被条件渲染跳过见模板中的_% if (style ! none)逻辑同时 application.ts 会删除对应的styles.none占位文件。命令行示例在嵌套目录中创建应用nx g nx/nuxt:app apps/nested/myappdirectory是唯一必填选项见 schema.json生成器会以目录的最后一段作为应用名并自动在apps/nested/myapp-e2e创建配套的 E2E 项目normalizeOptions中拼接${appProjectName}-e2e见 normalize-options.ts。创建带 Vitest 的应用nx g nx/nuxt:app apps/nested/myapp --unitTestRunnervitestunitTestRunner的可选值为vitest | none。从 normalize-options.ts 的解析逻辑options.unitTestRunner ?? vitest看未显式指定时会被解析为vitest即默认启用。启用后 application.ts 会额外向package.json的 devDependencies 添加vue/test-utils与vitejs/plugin-vue并调用addVitest。addVitest的实现见 add-vitest.ts会委托nx/vitest的configurationGenerator完成配置关键参数包括testEnvironment: jsdomDOM 环境、coverageProvider: v8内置覆盖率、addPlugin: true并通过createOrEditViteConfig写入 Vite 配置注入import vue from vitejs/plugin-vue与plugins: [vue()]。因此生成的项目会得到可立即运行的 Vitest 环境与测试目标。使用纯 JavaScript而非 TypeScriptnx g nx/nuxt:app apps/myapp --js--js选项会让生成器在完成所有文件生成后调用toJS(tree)见 application.ts把所有 TypeScript 模板文件转换为对应的.js文件同时保留 Nuxt 的完整能力。toJS是nx/devkit提供的能力会自动同步更新相关的路径引用与配置文件。生成器完整选项参考nx/nuxt:app的完整参数定义在 schema.json以下为主要选项选项取值默认说明directory字符串必填新应用所在目录别名dir可省略--直接作为位置参数传入name字符串由目录推导应用名称支持 scoped 包名如org/appunitTestRunnervitest/nonevitest代码层解析单元测试运行器e2eTestRunnerplaywright/cypress/noneplaywrightE2E 测试运行器默认 playwrightlintereslint/oxlint/none沿用工作区配置Lint 工具formatternone/prettier/oxfmt—代码格式化工具stylecss/scss/nonecss样式文件扩展名js布尔false生成 JavaScript 而非 TypeScripttags字符串—给应用添加标签用于约束依赖别名tenableTypedLinting布尔false启用类型感知 lintflat config 配置parserOptions.projectService因性能原因默认关闭useAppDir布尔Nuxt 4 为 trueNuxt 3 为 false使用 Nuxt 4 的app/目录结构还是src/结构skipFormat布尔false跳过生成后的文件格式化skipPackageJson布尔false不向package.json添加依赖rootProject布尔false在工作区根目录创建应用内部选项useProjectJson布尔视 TS solution 配置而定使用project.json而非在package.json内联 Nx 配置所有选项的约束枚举、默认值、别名、x-prompt交互提示均以 schema.json 为准required: [directory]表明目录是唯一必填项。交互模式下Nx 会依据x-prompt引导你选择样式、单元测试运行器等。生成器底层执行流程了解生成器的内部执行顺序有助于排查生成后的各种问题。applicationGeneratorInternalapplication.ts按以下步骤工作版本校验assertSupportedNuxtVersion检查工作区中的 Nuxt 版本是否受支持初始化 JS 生态调用nx/js的initGenerator建立 TS 配置与工具链基础选项归一化normalizeOptions推导项目名、项目根目录、importPath、Nuxt 主版本3/4并确定useAppDir等默认值依赖保障ensureDependencies按版本工具解析需要安装的 Nuxt 相关依赖版本渲染模板generateFiles渲染应用主体模板base/app-dir与NxWelcome组件模板按 Nx Cloud 状态选择子目录配置写入createTsConfig、updateGitIgnore若启用 TS solution 则更新工作区文件质量工具addLintingESLint/Oxlint、可选addVitest插件初始化nuxtInitGenerator注册nx/nuxt插件相关的 targetsE2E 项目addE2e创建配套的 Playwright/Cypress 项目JS 转换options.js时执行toJS收尾sortPackageJsonFields、formatFiles并返回一个串行任务队列runTasksInSerial(...tasks)。值得注意的是最后一步生成器会尝试自动执行nuxi prepareapplication.ts为应用生成.nuxt类型声明。这段实现针对不同包管理器做了特殊处理npm/yarn/bun 可在应用目录内解析根目录安装的nuxi而 pnpm 不会向上查找node_modules/.bin因此仅当应用目录自身拥有nuxipackage-based 布局时才在应用目录运行否则回退到工作区根目录执行。若自动执行失败控制台会提示你手动运行nuxi prepare。生成页面与组件创建应用之后你可以借助nx/vue提供的组件生成器继续扩展。由于nx/nuxt的generators.json通过extends: [nx/vue]继承了 Vue 插件的生成器所以nx/nuxt:component与nx/vue:component指向同一个生成器。完整文档位于 packages/vuenx/vue:component生成器这里给出两个最常用的示例生成新页面nx g nx/nuxt:component my-app/src/pages/my-page在src/pages下创建的 Vue 单文件组件会自动被 Nuxt 文件路由系统识别为一个新页面无需任何额外配置。生成新组件nx g nx/nuxt:component my-app/src/components/my-cmp在src/components下创建的组件可被 Nuxt 的自动导入机制直接使用nuxt.config.ts中已开启imports: { autoImport: true }无需手动import。生成器同样支持样式与脚本相关的选项如--stylescss、--js等可参考nx/vue:component的 schema 定义按需组合。验证与运行生成完成后你可以在应用目录或使用--projectmy-app执行 Nx 提供的 targetsnx serve my-app # 启动开发服务器默认 http://localhost:4200 nx test my-app # 运行 Vitest 单元测试若启用 nx e2e my-app-e2e # 运行 Playwright/Cypress E2E 测试 nx lint my-app # 运行 Lint 检查开发服务器端口由nuxt.config.ts中的devServer.port指定模板默认4200。/api/greet端点的测试、页面路由与NxWelcome组件的快照断言可在 application.spec.ts 及其 快照文件 中查看生成器自身的测试用例作为验证生成结果是否符合预期的参考。小结nx/nuxt:app生成器将 Nuxt 应用的脚手架搭建与 Nx 工作区深度集成它生成遵循 Nuxt 官方目录结构的完整应用页面、组件、app.vue入口、/api/greet端点、Vitest 配置自动链接根 TS 配置与nxViteTsPaths路径插件并同步创建 E2E 项目。无论是嵌套目录布局、纯 JavaScript 项目还是通过nx/nuxt:component继续生成页面和组件都可以在一条命令内完成。掌握本指南后你可以直接基于生成的骨架开始业务开发并借助nx/nuxt:storybook-configuration生成器见 storybook-configuration-examples.md继续接入组件文档化能力。【免费下载链接】nxThe Monorepo Platform that amplifies both developers and AI agents. Nx optimizes your builds, scales your CI, and fixes failed PRs automatically. Ship in half the time.项目地址: https://gitcode.com/GitHub_Trending/nx/nx创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
