Membuat aplikasi Node.js

Menentukan versi Node.js

Proyek buildpack menyediakan dukungan untuk rilis LTS Saat Ini dan Aktif dari Node.js. Rilis lama Node.js tersedia tetapi mungkin tidak dikelola secara aktif oleh project.

Menggunakan package.json

Anda dapat menentukan versi Node.js aplikasi selama deployment dengan mengonfigurasi kolom engines.node di package.json. Untuk mengonfigurasi buildpack agar menggunakan Node.js v16 versi terbaru saat men-deploy aplikasi, Anda dapat menggunakan nilai berikut di package.json:

"engines": {
  "node": "16.x.x"
}

Menggunakan GOOGLE_NODEJS_VERSION

Anda juga dapat menentukan versi Node.js melalui variabel lingkungan GOOGLE_NODEJS_VERSION. Jika kedua konfigurasi ditetapkan, nilai GOOGLE_NODEJS_VERSION akan lebih diprioritaskan daripada properti engines.node. Jika tidak ada nilai yang diberikan, maka Node.js versi LTS terbaru akan digunakan

Untuk mengonfigurasi buildpack agar menggunakan Node.js 16 saat men-deploy aplikasi:

pack build --builder=gcr.io/buildpacks/builder \
   sample-functions-framework-node \
   --env GOOGLE_NODEJS_VERSION=16.x.x

Anda juga dapat menggunakan deskriptor project project.toml untuk mengenkode variabel lingkungan bersama file project Anda. Lihat petunjuk cara mem-build aplikasi dengan variabel lingkungan.

Tips

  • Kolom engines.node dapat menggunakan batasan semver. Library khusus yang kami gunakan untuk buildpack Node.js adalah Masterminds/semver
  • Hindari penggunaan penentu yang lebih besar dari (>) di engines.node
  • Saat men-deploy aplikasi ke lingkungan standar App Engine, properti engines.node harus kompatibel dengan runtime yang ditentukan di app.yaml
  • Dokumentasi tambahan tentang opsi konfigurasi engines.node di package.json dapat ditemukan di dokumentasi NPM resmi pada topik engine
  • Saat men-deploy fungsi ke fungsi Cloud Run, properti engines.node harus kompatibel dengan runtime yang digunakan untuk men-deploy fungsi Anda

Menginstal dependensi

Menggunakan NPM

  • NPM adalah pengelola paket default.
  • Jika memungkinkan, gunakan package-lock.json untuk meningkatkan performa cache.
  • Secara default, hanya dependensi produksi yang diinstal.
  • Anda dapat menentukan bagian versi npm menggunakan kolom engines.npm di file package.json.

Menggunakan Yarn

  • Yarn akan digunakan saat Anda menyertakan file yarn.lock dalam project.
  • Anda dapat menentukan versi yarn yang akan digunakan di kolom engines.yarn pada file package.json.
  • Kami mendukung mode Yarn2 PnP jika project Anda menyertakan .yarn/cache.

Menggunakan Pnpm:

  • Sebagai gantinya, Pnpm digunakan saat Anda menyertakan file pnpm-lock.yaml dalam project Anda.
  • Anda dapat menentukan versi pnpm di kolom engines.pnpm pada file package.json.
  • Untuk contoh penggunaan, lihat aplikasi sample-node-pnpm.

Menggunakan modul pribadi

Anda dapat menggunakan modul npm pribadi dengan menyediakan setelan untuk mengautentikasi dengan registry dalam file .npmrc di direktori fungsi. Jika Anda menggunakan Yarn versi 2 atau yang lebih baru sebagai pengelola paket, file ini akan diberi nama .yarnrc.yml.

Modul pribadi dari Artifact Registry

Repositori paket Node.js Artifact Registry dapat menghosting modul pribadi untuk fungsi Anda. Saat Anda men-deploy fungsi Buildpack, proses build akan otomatis menghasilkan kredensial Artifact Registry untuk akun layanan Cloud Build. Anda hanya perlu mencantumkan repositori Artifact Registry dalam file .npmrc saat menggunakan NPM atau Yarn versi 1. Misalnya, saat menggunakan NPM atau Yarn versi 1:

@SCOPE:registry=https://REGION_ID-npm.pkg.dev/PROJECT_ID/REPOSITORY_NAME
//REGION_ID-npm.pkg.dev/PROJECT_ID/REPOSITORY_NAME:always-auth=true

Jika menggunakan Yarn versi 2 atau yang lebih baru, Anda hanya perlu mencantumkan repositori Artifact Registry di file .yarnrc.yml tanpa kredensial tambahan. Contoh:

npmScopes:
  SCOPE:
    npmRegistryServer: https://REGION_ID-npm.pkg.dev/PROJECT_ID/REPOSITORY_NAME
    npmAlwaysAuth: true

Modul pribadi dari repositori lain

Dokumentasi npm menjelaskan cara membuat token akses hanya baca kustom. Sebaiknya jangan gunakan file .npmrc yang dibuat di direktori home karena file tersebut berisi token baca-tulis. Izin operasi tulis tidak diperlukan selama deployment, dan dapat menimbulkan risiko keamanan.

Jangan menyertakan file .npmrc jika Anda tidak menggunakan repositori pribadi, karena dapat memperlama waktu deployment untuk fungsi Anda.

Format file

Jika Anda menggunakan file .npmrc untuk menetapkan token autentikasi kustom, file tersebut harus menyertakan baris yang ditampilkan di bawah.

//REGISTRY_DOMAIN/:_authToken=AUTH_TOKEN

Ganti:

  • REGISTRY_DOMAIN: nama domain registry npm pribadi Anda. Misalnya, jika host repositori Anda adalah npmjs.org, tetapkan kolom ini ke registry.npmjs.org.

  • AUTH_TOKEN: token otorisasi untuk registry npm Anda. Token ini dapat berupa nilai teks literal dari token atau string teks ${NPM_TOKEN}, yang diganti oleh perintah npm dengan nilai token sebenarnya dari lingkungan.

    Anda dapat menetapkan variabel lingkungan $NPM_TOKEN dengan argumen --set-build-env-vars ke perintah gcloud functions deploy. Lihat tutorial NPM tentang modul pribadi untuk mengetahui detail lebih lanjut tentang token autentikasi NPM.

Menjalankan langkah-langkah build kustom selama deployment

Secara default, npm run build dijalankan jika Anda menentukan skrip dalam file package.json. Namun, Anda dapat menentukan langkah-langkah build kustom untuk mengganti perilaku default dan hanya menjalankan skrip yang diinginkan selama build. Anda dapat mengontrol langkah-langkah build menggunakan variabel lingkungan GOOGLE_NODE_RUN_SCRIPTS atau gcp-build dalam file package.json.

Anda hanya dapat menggunakan satu metode. Perhatikan bahwa variabel lingkungan GOOGLE_NODE_RUN_SCRIPTS lebih diutamakan dan menggantikan apa pun yang ditentukan untuk gcp-build dalam package.json Anda.

Secara default, saat Anda mengonfigurasi langkah-langkah build kustom, dependencies dan devDependencies dalam file package.json akan diinstal terlebih dahulu sebelum skrip atau perintah dijalankan. Untuk mengganti perilaku default, Anda dapat menggunakan variabel lingkungan NODE_ENV.

Menggunakan GOOGLE_NODE_RUN_SCRIPTS

Anda dapat meneruskan variabel lingkungan GOOGLE_NODE_RUN_SCRIPTS ke build untuk mengontrol skrip yang dijalankan. Anda dapat menentukan satu atau beberapa skrip, atau meneruskan variabel lingkungan kosong untuk mencegah perilaku default berjalan, seperti GOOGLE_NODE_RUN_SCRIPTS=. Untuk mengetahui detail selengkapnya, lihat Variabel lingkungan.

Menggunakan package.json

Menambahkan gcp-build di file package.json hanya akan menjalankan npm run gcp-build, yang berarti tindakan tersebut akan menggantikan perilaku default. Anda dapat menentukan satu atau beberapa perintah, atau menentukan string kosong untuk mencegah perintah apa pun berjalan, seperti "gcp-build":"".

"scripts": {
  ...
  "gcp-build": "npm run lint && npm run build"
  ...
}

Titik entri aplikasi

Buildpack Node.js akan menjalankan perintah yang ditentukan di kolom scripts.start pada package.json Anda. Jika scripts.start tidak ditetapkan, buildpack akan menjalankan npm start.

Sebaiknya gunakan Procfile karena npm atau yarn akan dikeluarkan dari jalur.

Variabel lingkungan

Anda dapat menetapkan variabel lingkungan untuk mengonfigurasi build image container.

Buildpack Node.js mendukung variabel lingkungan berikut untuk menyesuaikan container Anda.

NPM_CONFIG_<key>

Lihat dokumentasi.

Contoh: NPM_CONFIG_FLAG=value meneruskan -flag=value ke perintah npm.

NODE_ENV

Menentukan lingkungan pengembangan selama proses build; disetel untuk npm install.

Contoh: NODE_ENV=development menginstal dependencies dan devDependencies yang ditentukan di package.json.

GOOGLE_NODE_RUN_SCRIPTS

Menentukan daftar skrip npm dari package.json yang akan dijalankan setelah menginstal dependensi. Daftar harus dipisahkan koma dan dijalankan sesuai urutan pencantuman setiap skrip.

Saat Anda menentukan GOOGLE_NODE_RUN_SCRIPTS, hanya skrip yang Anda cantumkan yang akan dijalankan. Misalnya, jika Anda ingin mencegah npm run build default berjalan, tentukan variabel lingkungan tanpa nilai.

Contoh:

  • GOOGLE_NODE_RUN_SCRIPTS=lint,build menjalankan npm run lint, lalu npm run build.
  • GOOGLE_NODE_RUN_SCRIPTS= tidak menjalankan skrip.