Supercharge `npm run dev` dengan skrip package.json-tutorial js-php.cn

Supercharge `npm run dev` with package.json scripts

npm run dev ialah standard untuk "jalankan tapak web saya secara setempat," tetapi bagaimanakah ia berfungsi? Bagaimanakah kita boleh mengembangkan fungsinya? Dalam siaran ini kita akan melihat:

Cara mengkonfigurasi perkara yang dilakukan oleh npm run dev.
Cara menguraikan perintah kompleks kepada unit berbutir.
Cara menjalankan berbilang arahan secara selari.
Cara menjalankan pra-syarat tanpa kehilangan kelakuan Ctrl-C biasa.
Cara menambah data benih (jika tiada) apabila memulakan hujung belakang Convex.

Sebagai contoh yang memotivasikan, berikut ialah beberapa skrip yang ditakrifkan dalam apl contoh pembantu cembung. Kami akan membincangkan perkara yang dilakukan oleh setiap bahagian

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

Salin selepas log masuk

Bagaimana dan di mana ia ditakrifkan

npm run menjalankan arahan yang ditakrifkan dalam package.json anda dalam ruang kerja projek anda. Arahan ini selalunya diprakonfigurasikan apabila anda memulakan repo anda daripada arahan seperti npm create vite@latest dengan arahan untuk:

dev: Jalankan persekitaran pembangunan. Ini selalunya termasuk memuatkan semula pengguna UI apabila fail berubah. Untuk Vite ini adalah vite dan Next.js ialah pembangun seterusnya.
bina: Bina tapak web untuk penempatan. Ini biasanya akan menyusun dan menggabungkan semua html, css dan javascript anda. Untuk Vite ini ialah binaan vite dan binaan Seterusnya.js ialah binaan seterusnya.
ujian: Jalankan ujian - jika anda menggunakan Jest, ini hanyalah "ujian": "jest" atau vitest untuk Vitest.

Berikut ialah contoh asas daripada Next.js:

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

Salin selepas log masuk

Di sini anda boleh menjalankan npm run dev atau npm run lint dll.

Anda boleh mengetahui lebih lanjut tentang npm run dalam dokumen.

Mengapa menggunakan skrip?

Persoalan yang wajar mengapa seseorang akan meletakkan arahan yang sudah begitu mudah ke dalam skrip pakej. Mengapa tidak panggil jest atau vite atau binaan seterusnya? Terdapat beberapa sebab yang baik:

Anda boleh menyimpan parameter lalai untuk arahan supaya anda tidak perlu mengingati atau mendokumenkan cara "standard" untuk memulakan sesuatu. Kami akan melihat di bawah bagaimana anda boleh mengkonfigurasinya kepada perintah rantai dan menjalankan yang lain secara selari.
Ia membolehkan anda menjalankan perintah dengan mudah yang dipasang oleh npm tetapi tidak boleh diakses secara global daripada shell (terminal) anda.¹ Apabila anda memasang perkara seperti npm install -D vitest, ia memasang vitest ke dalam node_modules/ .bin.² Anda tidak boleh menjalankan vitest secara langsung dalam shell anda,³ tetapi anda boleh mempunyai konfigurasi seperti: "scripts": { "test": "vitest" } dan Ujian larian npm akan menjalankan vitest.
Ia sentiasa berjalan dengan akar folder pakej sebagai "direktori semasa" walaupun anda berada dalam subdirektori. Jadi anda boleh mentakrifkan skrip seperti "foo": "./myscript.sh" dan ia akan sentiasa mencari myscript.sh dalam akar pakej (dalam direktori yang sama seperti package.json). Nota: anda boleh mengakses direktori semasa di mana ia dipanggil melalui pembolehubah persekitaran INIT_CWD.
Anda boleh merujuk pembolehubah dalam package.json dengan mudah apabila skrip dijalankan daripada npm run. Sebagai contoh, anda boleh mengakses "versi" pakej anda dengan pembolehubah persekitaran npm_package_version, seperti process.env.npm_package_version dalam js atau $npm_package_version dalam skrip.
Jika anda mempunyai berbilang ruang kerja (banyak direktori dengan package.json mereka sendiri dikonfigurasikan menjadi pakej induk.json dengan konfigurasi "ruang kerja"), anda boleh menjalankan arahan yang sama dalam semua ruang kerja dengan ujian npm --workspaces atau satu dengan npm run lint --workspace apps/web.

Adakah npm menjalankan dev berfungsi dengan benang / pnpm / bun?

Ya! Walaupun anda memasang kebergantungan anda dengan pengurus pakej lain, anda masih boleh menjalankan skrip pakej anda dengan npm.

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

Salin selepas log masuk

Anda tidak perlu ingat bahawa npm run dev memetakan kepada yarn dev (atau yarn run dev). Perkara yang sama berlaku untuk npx: npx convex dev berfungsi tanpa mengira pengurus pakej yang anda gunakan untuk memasang sesuatu.

Menjalankan arahan secara selari

Terdapat beberapa pakej yang anda boleh gunakan untuk menjalankan arahan secara serentak:⁴

npm-lari-semua
serentak

Kita hanya akan melihat npm-run-all di sini. Pertimbangkan contoh kami:

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

Salin selepas log masuk

Ini mentakrifkan tiga skrip.

npm run dev:backend menjalankan convex dev.
npm run dev:frontend runs vite.
npm run dev menjalankan dev convex dan vite secara selari melalui npm-run-all.

Kedua-dua output distrim keluar dan melakukan Ctrl-C akan mengganggu kedua-dua skrip.

predev? pasca binaan?

Anda boleh menentukan arahan untuk dijalankan sebelum (pra) atau selepas (post) perintah lain (katakan, X) dengan menamakan perintah anda preX atau postX. Dalam contoh:

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

Salin selepas log masuk

Ini akan menjalankan convex dev --until-success, sebelum arahan "dev" 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:

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

Salin selepas log masuk

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

Salin selepas log masuk

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"

Salin selepas log masuk

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

Salin selepas log masuk

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.

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. ↩
Technically you can override & specify where npm installs binaries. ↩
Jika anda benar-benar mahu, anda boleh menjalankan npm exec vitest, singkatan npx vitest, ./npm_modules/.bin/vitest secara langsung atau tambahkan .npm_modules/.bin pada PATH anda. ↩
Sesetengah orang menggunakan kosong & untuk menjalankan satu tugasan di latar belakang, tetapi itu tidak disokong pada Windows, dan mengganggu satu arahan tidak semestinya membunuh yang lain. ↩

Atas ialah kandungan terperinci Supercharge `npm run dev` dengan skrip package.json. Untuk maklumat lanjut, sila ikut artikel berkaitan lain di laman web China PHP!