使用 packagejson 脚本增强“npm run dev”

npm run dev 是“本地运行我的网站”的标准，但它是如何工作的呢？我们如何扩展它的功能？在这篇文章中，我们将看看：

• 如何配置 npm run dev 的功能。
• 如何将复杂的命令分解为细粒度的单元。
• 如何并行运行多个命令。
• 如何在不失去正常 ctrl-c 行为的情况下运行先决条件。
• 启动 convex 后端时如何添加种子数据（如果不存在）。

作为一个激励示例，以下是凸帮助程序示例应用程序中定义的一些脚本。我们将介绍每个部分的作用

  "scripts": {
    "dev": "npm-run-all --parallel dev:backend dev:frontend",
    "build": "tsc && vite build",
    "dev:backend": "convex dev",
    "dev:frontend": "vite",
    "predev": "convex dev --until-success",
    "test": "vitest"
  },

它们的定义方式和位置

npm run 运行项目工作区中 package.json 中定义的命令。当您从 npm create vite@latest 等命令启动存储库时，这些命令通常是预先配置的，其中的命令为：

• dev：运行开发环境。这通常包括在文件更改时自动重新加载 ui。对于 vite 来说，这是 vite，next.js 是下一个 dev。
• build：构建用于部署的网站。这通常会编译并捆绑所有 html、css 和 javascript。对于 vite，这是 vite 构建，next.js 是下一个构建。
• test：运行测试 - 如果您使用 jest，则只需“test”：“jest”或 vitest for vitest。

这是来自 next.js 的基本示例：

// in package.json
{
// ...
  "scripts": {
    "dev": "next dev",
    "build": "next build",
    "start": "next start",
    "lint": "next lint"
  },
//...

在这里你可以运行 npm run dev 或 npm run lint 等

您可以在文档中了解有关 npm run 的更多信息。

为什么使用脚本？

这是一个公平的问题，为什么人们会将已经如此简单的命令放入包脚本中。为什么不直接调用 jest 或 vite 或 next build 呢？有几个很好的理由：

1. 您可以保存命令的默认参数，这样您就不必记住或记录启动某项操作的“标准”方式。我们将在下面看到如何将其配置为链接命令并并行运行其他命令。
2. 它允许您轻松运行由 npm 安装但无法从 shell（终端）全局访问的命令。¹ 当您安装 npm install -d vitest 之类的东西时，它会将 vitest 安装到 node_modules/.bin 中。²你不能直接在 shell 中运行 vitest，³ 但你可以有一个像这样的配置： "scripts": { "test": "vitest" } 并且 npm run test 将运行 vitest.
3. 即使您位于子目录中，它也始终以包文件夹的根目录作为“当前目录”运行。因此，您可以定义一个类似 "foo": "./myscript.sh" 的脚本，它总是会在包根目录中（与 package.json 位于同一目录中）查找 myscript.sh。注意：您可以通过 init_cwd 环境变量访问当前调用的目录。
4. 当脚本从 npm run 运行时，您可以轻松引用 package.json 中的变量。例如，您可以使用 npm_package_version 环境变量访问包的“版本”，例如 js 中的 process.env.npm_package_version 或脚本中的 $npm_package_version 。
5. 如果你有多个工作区（许多目录都有自己的 package.json，并通过“workspaces”配置配置到父 package.json 中），你可以使用 npm test --workspaces 或使用 npm run 在所有工作区中运行相同的命令lint --workspace 应用程序/web.

npm run dev 可以与yarn/pnpm/bun一起使用吗？

是的！即使您使用其他包管理器安装依赖项，您仍然可以使用 npm 运行包脚本。

yarn # similar to `npm install`
npm run dev # still works!

您不必记住 npm run dev 映射到yarn dev（或yarn run dev）。 npx 也是如此：无论您使用什么包管理器来安装东西，npx 凸开发都可以工作。

并行运行命令

有几个包可以用来同时运行命令：⁴

1. npm-run-all
2. 同时

我们在这里只看一下 npm-run-all 。考虑我们的例子：

  "scripts": {
    "dev": "npm-run-all --parallel dev:backend dev:frontend",
    "dev:backend": "convex dev",
    "dev:frontend": "vite",
  },

这定义了三个脚本。

1. npm run dev:后端运行凸开发。
2. npm run dev:frontend 运行 vite。
3. npm run dev 通过 npm-run-all 并行运行凸开发和 vite。

两个输出都会流出，并且执行 ctrl-c 会中断两个脚本。

预开发？后期构建？

您可以通过将命令命名为 prex 或 postx 来指定在另一个命令（例如 x）之前（前）或之后（后）运行的命令。在示例中：

  "scripts": {
    "dev": "npm-run-all --parallel dev:backend dev:frontend",
    "dev:backend": "convex dev",
    "dev:frontend": "vite",
    "predev": "convex dev --until-success",
  },

这将在 npm-run-all --parallel dev:backend dev:frontend 的“dev”命令之前运行凸开发 --until-success。

用“&&”链接

对于习惯 shell 脚本的人来说，如果前一个命令成功，则可以按顺序运行两个命令：commanda && commandb。这适用于 windows 和 unix (mac / linux)。

但是，仅使用预先脚本有几个优点：

1. 您可以使用 npm run dev --ignore-scripts 运行任一命令以不执行“predev”脚本，或者 npm run predev 显式地仅执行“predev”步骤。
2. 根据我的经验，ctrl-c 的行为更容易预测。在不同的 shell 环境中，执行 ctrl-c（向当前进程发送中断信号）有时会终止第一个脚本，但仍运行第二个脚本。经过多次尝试，我们决定切换到“predev”作为模式。

首先运行交互式步骤

对于 convex，当您第一次运行 npx 凸开发（或使用上述脚本的 npm run dev）时，如果您还没有登录，它会要求您登录；如果尚未登录，它会要求您设置项目设置。这很棒，但是当多个命令同时传输输出时，更新输出文本的交互式命令不能很好地工作。这是在 npx 凸 dev 之前运行 npx 凸 dev --until-success 的动机。

• 只要函数和模式与您部署的内容不匹配，凸开发就会同步您的函数和模式，并监视文件更改。
• --until-success 标志仅同步您的函数和模式，直到成功一次，告诉您如果出现问题要修复什么，并自动重试，直到成功或您按 ctrl-c 为止。
• 通过运行 npx凸开发 --until-success，我们可以在尝试启动前端和后端之前完成登录、项目配置和初始同步。
• 如果初始同步发现了诸如缺少环境变量之类的问题（需要在应用程序运行之前进行设置），那么它会特别有用。
• 这样，在后端准备好使用其期望的函数版本处理请求之前，前端不会启动。

启动时播种数据

如果您将 convex 的“predev”命令更改为包含 --run ，它将在前端启动之前运行服务器端功能。

  "scripts": {
      //...
    "predev": "convex dev --until-success --run init",
        //...
  },

--run init 命令将运行凸/init.ts 中默认导出的函数。您还可以运行 --run myfolder/mymodule:myfunction。请参阅此处有关命名的文档。请参阅这篇关于播种数据的文章，但要点是您可以定义一个内部突变来检查数据库是否为空，如果是，则插入一组记录以用于测试/设置目的。

tsc？

如果您使用 typescript，您可以使用裸 tsc 运行类型检查/编译您的 typescript 文件。如果您的 tsconfig.json 配置为发出类型，它将写出类型。如果没有，它只会验证类型。作为构建的一部分，这非常好，因此您不会构建任何有类型错误的东西。这就是上面例子的原因：

    "build": "tsc && vite build",

如何传递参数？

如果您想将参数传递给命令，例如将参数传递给测试命令以指定要运行的测试，您可以在after之后传递它们 - 以将命令与参数分开。从技术上讲，你不需要 -- 如果你的参数是位置参数而不是 -- 前缀，但总是这样做也没什么坏处，以防你忘记为哪个而做。

npm run test -- --grep="pattern"

概括

我们研究了一些使用 package.json 脚本来简化工作流程的方法。谁知道一个简单的 npm run dev 背后可以蕴含多少力量？看看我们原来的例子：

  "scripts": {
    "dev": "npm-run-all --parallel dev:backend dev:frontend",
    "build": "tsc && vite build",
    "dev:backend": "convex dev",
    "dev:frontend": "vite",
    "predev": "convex dev --until-success",
    "test": "vitest"
  },

• dev 在 predev 之后并行运行前端和后端。
• build 在构建静态站点之前通过 tsc 进行类型检查。
• dev:backend 在您编辑文件时不断将后端功能部署到您的开发环境。
• dev:frontend 运行一个本地前端服务器，它会在您编辑文件时自动重新加载。
• predev 在 dev 之前运行，并根据需要进行初始部署、处理登录、配置和初始同步。
• test 使用 vitest 来运行测试。注意：npm test 是 npm run test 以及其他命令的简写，但它们是特殊情况。 npm run test 是我建议的习惯。

1. 输入 npm 时 shell 查找要运行的命令的方法是检查 shell 的 path 环境变量（无论如何在 unix 机器上）。您可以使用 echo "$path" 看到您自己的。它检查 $path 中指定的所有位置并使用第一个位置。  ↩

2. 从技术上讲，您可以覆盖并指定 npm 安装二进制文件的位置。 ↩

3. 如果你真的想，你可以直接运行 npm exec vitest，简称 npx vitest，./npm_modules/.bin/vitest，或者将 .npm_modules/.bin 添加到你的 path 中。 ↩

4. 有些人使用裸 & 在后台运行一项任务，但这在 windows 上不受支持，并且中断一个命令不一定会杀死另一个命令。 ↩