Superchargez `npm run dev` avec les scripts package.json

npm run dev est la norme pour « gérer mon site Web localement », mais comment ça marche ? Comment pouvons-nous étendre ses fonctionnalités ? Dans cet article, nous examinerons :

• Comment configurer ce que fait npm run dev.
• Comment décomposer des commandes complexes en unités granulaires.
• Comment exécuter plusieurs commandes en parallèle.
• Comment exécuter les prérequis sans perdre le comportement normal de Ctrl-C.
• Comment ajouter des données de départ (s'il n'y en a pas) lors du démarrage d'un backend Convex.

À titre d'exemple motivant, voici quelques scripts définis dans l'exemple d'application convex-helpers. Nous couvrirons ce que fait chaque pièce

  "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"
  },

Comment et où ils sont définis

npm run exécute les commandes définies dans votre package.json dans l'espace de travail de votre projet. Ces commandes sont souvent préconfigurées lorsque vous démarrez votre dépôt à partir d'une commande comme npm create vite@latest avec les commandes pour :

• dev : exécutez un environnement de développement. Cela inclut souvent le rechargement automatique de l'interface utilisateur lorsque les fichiers changent. Pour Vite, c'est vite et Next.js est le prochain dev.
• build : créez le site Web pour le déploiement. Cela compilera et regroupera généralement tous vos fichiers HTML, CSS et Javascript. Pour Vite, il s'agit de la version vite et Next.js est la prochaine version.
• test : Exécutez des tests - si vous utilisez Jest, c'est simplement "test": "jest" ou vitest pour Vitest.

Voici un exemple de base de Next.js :

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

Ici, vous pouvez exécuter npm run dev ou npm run lint etc.

Vous pouvez en savoir plus sur l'exécution de npm dans la documentation.

Pourquoi utiliser des scripts ?

C'est une bonne question de savoir pourquoi on mettrait des commandes déjà si simples dans des scripts de package. Pourquoi ne pas simplement appeler jest ou vite ou next build ? Il y a quelques bonnes raisons :

1. Vous pouvez enregistrer les paramètres par défaut des commandes afin de ne pas avoir à vous souvenir ou à documenter la manière "standard" de démarrer quelque chose. Nous verrons ci-dessous comment vous pouvez le configurer pour enchaîner des commandes et en exécuter d'autres en parallèle.
2. Il vous permet d'exécuter facilement des commandes installées par npm mais qui ne sont pas accessibles globalement depuis votre shell (terminal).¹ Lorsque vous installez des éléments comme npm install -D vitest, il installe vitest dans node_modules/ .bin.² Vous ne pouvez pas exécuter vitest directement dans votre shell,³ mais vous pouvez avoir une configuration comme : "scripts": { "test": "vitest" } et npm run test exécutera vitest.
3. Il s'exécute toujours avec la racine du dossier du package comme "répertoire courant", même si vous êtes dans un sous-répertoire. Vous pouvez donc définir un script comme "foo": "./myscript.sh" et il cherchera toujours myscript.sh à la racine du package (dans le même répertoire que package.json). Remarque : vous pouvez accéder au répertoire courant où il a été appelé via la variable d'environnement INIT_CWD.
4. Vous pouvez facilement référencer des variables dans le package.json lorsque le script est exécuté à partir de npm run. Par exemple, vous pouvez accéder à la "version" de votre package avec la variable d'environnement npm_package_version, comme process.env.npm_package_version en js ou $npm_package_version dans un script.
5. Si vous avez plusieurs espaces de travail (de nombreux répertoires avec leur propre package.json configuré dans un package.json parent avec une configuration "workspaces"), vous pouvez exécuter la même commande dans tous les espaces de travail avec npm test --workspaces ou un avec npm exécutez lint --workspace apps/web.

Npm run dev fonctionne-t-il avec fil/pnpm/bun ?

Oui ! Même si vous installez vos dépendances avec un autre gestionnaire de packages, vous pouvez toujours exécuter vos scripts de package avec npm.

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

Vous n'avez pas besoin de vous rappeler que npm run dev correspond à Yarn Dev (ou Yarn Run Dev). Il en va de même pour npx : npx convex dev fonctionne quel que soit le gestionnaire de paquets que vous avez utilisé pour installer les éléments.

Exécuter des commandes en parallèle

Il existe quelques packages que vous pouvez utiliser pour exécuter des commandes simultanément :⁴

1. npm-run-all
2. simultanément

Nous allons simplement regarder npm-run-all ici. Prenons notre exemple :

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

Cela définit trois scripts.

1. npm run dev:backend exécute un développement convexe.
2. npm run dev:frontend exécute vite.
3. npm run dev exécute à la fois convexe dev et vite en parallèle via npm-run-all.

Les deux sorties sont diffusées et faire Ctrl-C interrompra les deux scripts.

avant? post-construction ?

Vous pouvez spécifier des commandes à exécuter avant (pré) ou après (post) une autre commande (par exemple, X) en nommant votre commande preX ou postX. Dans l'exemple :

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

Cela exécutera convex dev --until-success, avant la commande "dev" de npm-run-all --parallel dev:backend dev:frontend.

Chaining with "&&"

For those used to shell scripting, you can run two commands in sequence if the previous one succeeds with commandA && commandB. This works on both Windows and Unix (mac / linux).

However, there's a couple advantages to just using pre-scripts:

1. You can run either command with npm run dev --ignore-scripts to not do the "predev" script, or npm run predev to explicitly only do the "predev" step.
2. The Ctrl-C behavior is more predictable in my experience. In different shell environments, doing Ctrl-C (which sends an interrupt signal to the current process) would sometimes kill the first script but still run the second script. After many attempts we decided to switch to "predev" as the pattern.

Run interactive steps first

For Convex, when you first run npx convex dev (or npm run dev with the above scripts), it will ask you to log in if you aren't already, and ask you to set up your project if one isn't already set up. This is great, but interactive commands that update the output text don't work well when the output is being streamed by multiple commands at once. This is the motivation for running npx convex dev --until-success before npx convex dev.

• convex dev syncs your functions and schema whenever it doesn't match what you have deployed, watching for file changes.
• The --until-success flag syncs your functions and schema only until it succeeds once, telling you what to fix if something is wrong and retrying automatically until it succeeds or you Ctrl-C it.
• By running npx convex dev --until-success, we can go through the login, project configuration, and an initial sync, all before trying to start up the frontend and backend.
• The initial sync is especially helpful if it catches issues like missing environment variables which need to be set before your app can function.
• This way the frontend doesn't start until the backend is ready to handle requests with the version of functions it expects.

Seeding data on startup

If you change your "predev" command for Convex to include --run it will run a server-side function before your frontend has started.

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

The --run init command will run a function that is the default export in convex/init.ts. You could also have run --run myFolder/myModule:myFunction. See docs on naming here. See this post on seeding data but the gist is that you can define an internalMutation that checks if the database is empty, and if so inserts a collection of records for testing / setup purposes.

tsc?

If you use TypeScript, you can run a type check / compile your typescript files with a bare tsc. If your tsconfig.json is configured to emit types, it will write out the types. If not, it will just validate the types. This is great to do as part of the build, so you don't build anything that has type errors. This is why the above example did:

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

How to pass arguments?

If you want to pass arguments to a command, for instance passing arguments to your testing command to specify what test to run, you can pass them after a -- to separate the command from the argument. Technically you don't need -- if your arguments are positional instead of --prefixed, but it doesn't hurt to always do it in case you forget which to do it for.

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

Summary

We looked at some ways of using package.json scripts to simplify our workflows. Who knew how much power could rest behind a simple npm run dev? Looking at our original example:

  "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 runs the frontend and backend in parallel, after predev.
• build does type checking via tsc before building the static site.
• dev:backend continuously deploys the backend functions to your development environment as you edit files.
• dev:frontend runs a local frontend server that auto-reloads as you edit files.
• predev runs before dev and does an initial deployment, handling login, configuration, and an initial sync as necessary.
• test uses Vitest to run tests. Note: npm test is shorthand for npm run test along with other commands, but they're special cases. npm run test is the habit I suggest.

---

1. The way your shell finds which command to run when you type npm is to check the shell's PATH environment variable (on unix machines anyways). You can see your own with echo "$PATH". It checks all the places specified in $PATH and uses the first one.  ↩

2. Technically you can override & specify where npm installs binaries. ↩

3. Si vous le souhaitez vraiment, vous pouvez exécuter npm exec vitest, npx vitest en abrégé, ./npm_modules/.bin/vitest directement, ou ajouter .npm_modules/.bin à votre PATH. ↩

4. Certaines personnes utilisent un simple & pour exécuter une tâche en arrière-plan, mais cela n'est pas pris en charge sous Windows, et l'interruption d'une commande ne tuera pas nécessairement l'autre. ↩

Ce qui précède est le contenu détaillé de. pour plus d'informations, suivez d'autres articles connexes sur le site Web de PHP en chinois!