本文档介绍如何创建你自己的 App Extensions。

假设你已经安装过官方的 App Extension。这些使用经验在你开始构建自己的 App Extension 时会非常有价值。如果遇到问题，请访问我们 Discord 服务器的 #app-extensions 频道。

App Extension 本质上就是一个 npm 包，由 Quasar CLI 加载以提供你所开发的功能。

创建 App Extension

pnpm create quasar@latest
# 然后选择 AppExtension 选项

它会询问你的具体需求：是否需要 install 脚本、uninstall 脚本，是否需要向用户提问等。只选择你会用到的即可，之后也可以随时手动添加。

为了方便说明，假设我们在 App Extension 的 ext-id 问题中回答了 my-ext。请记住，App Extension 源码目录的文件夹名可以与实际的 ext-id 不同。最终，我们将从 /ae 目录发布新的 npm 包（quasar-app-extension-my-ext）。

根据你的回答，将创建一个具有以下结构的 App Extension 目录：

App Extension 脚本说明

除了 /ae/src/index.js|ts 之外，其他文件都是可选的。你可以随时手动添加或删除它们。

处理包依赖

如果你的 App Extension 依赖某些包才能运行（Quasar CLI 提供的包除外，如 “quasar”、“@quasar/extras”、“@quasar/app-vite”——对于这些你应该在 /install.js 和 /index.js 脚本中使用 “api.compatibleWith()”——参见 Install API 和 Index API），那么将它们 PNPM install 到你的 App Extension 目录中就会自动提供给宿主应用。

例如：你正在创建一个依赖 “my-table” npm 包的 UI 组件（这里只是举例），那么你应该在 App Extension 目录中 PNPM install “my-table”。

开发

可用命令

注意 /package.json 中可用的脚本：

# 代码检查和格式化
# （如果你选择了 oxlint + oxfmt 选项）
pnpm run lint
pnpm run lint:check

# 使用 playground 进行开发；
# 同时可以测试 Index 脚本
pnpm run dev
pnpm run dev -m ssr
# ...等等

# 在需要时将 AE 注入到 /playground
# （比如修改脚本本身时）；
# 可以运行 Install 和 Prompts 脚本
pnpm run invoke

# 卸载并重新安装 AE；
# 主要用于运行 Uninstall 脚本
pnpm run cycle

Install 和 Prompts 脚本

你会注意到文档中提到 invoking（调用）AE。调用流程与"添加"流程不同，它假设 App Extension 的包已经通过 pnpm/yarn/npm/bun 安装到了宿主应用中（因此 Quasar CLI 会跳过安装步骤）。

quasar ext add <ext-id>
# 或：
quasar ext invoke <ext-id>

Uninstall 脚本

你会注意到文档中提到 uninvoking（取消调用）AE。取消调用流程与"移除"流程不同，它会从宿主应用中注销 App Extension，但不会卸载其 npm 包。

quasar ext remove <ext-id>
# 或：
quasar ext uninvoke <ext-id>

Index 脚本

Index 脚本是 App Extension 的核心。

在这里你可以修改所有 quasar.config 文件选项、扩展 Vite 配置、注册 Quasar CLI 命令、启动开发应用所需的外部服务等等。

quasar dev
quasar build

Index 脚本的一个常见用例是扩展宿主应用的 Vite 配置：

import { defineIndexScript } from '#q-app'

export default defineIndexScript(api => {
  api.extendViteConf (viteConf, { isClient, isServer }, api) {
    // 用法类似于 /quasar.config > build > extendViteConf
  }
})

发布

当你完成 App Extension 并准备部署时，只需将其发布到 npm 仓库即可。

• 确保编辑了 /ae/README.md。
• 如果需要，也编辑 /ae/package.json > peerDependencies。
• 发布 AE 时，需要从 /ae 目录内执行：

# 仅从 /ae 目录执行：
pnpm login
pnpm publish