Menentukan dependensi di Node.js

Fungsi diizinkan untuk menggunakan modul Node.js eksternal serta data lokal. Dependensi pada Node.js dikelola dengan npm dan dinyatakan dalam file metadata bernama package.json. Anda dapat menggunakan npm, yarn, pnpm, atau Bun untuk menginstal dependensi Node.js.

Node.js Functions Framework adalah dependensi wajib untuk semua fungsi. Meskipun Cloud Run Functions menginstalnya untuk Anda saat fungsi dibuat, sebaiknya sertakan sebagai dependensi eksplisit agar lebih jelas.

Jika fungsi Anda bergantung pada dependensi pribadi, sebaiknya duplikasi functions-framework ke registry pribadi Anda. Sertakan functions-framework yang diduplikasi sebagai dependensi ke fungsi Anda untuk menghindari penginstalan paket dari internet publik.

Untuk menentukan dependensi bagi fungsi Anda, tambahkan dependensi tersebut ke file package.json.

Jika buildpack Node.js mendeteksi file kunci, seperti package-lock.json, yarn.lock, pnpm-lock.yaml, bun.lock, atau bun.lockb dalam project Anda, buildpack tersebut akan memprioritaskan file kunci tersebut saat Anda menginstal dependensi menggunakan npm ci, yarn install, pnpm install, atau bun install.

Contoh berikut mencantumkan dependensi dalam file package.json:

{
  "dependencies": {
    "escape-html": "^1.0.3"
  }
}

Cloud Run mengimpor dependensi dalam fungsi:

const functions = require('@google-cloud/functions-framework');
const escapeHtml = require('escape-html');

/**
 * Responds to an HTTP request using data from the request body parsed according
 * to the "content-type" header.
 *
 * @param {Object} req Cloud Function request context.
 * @param {Object} res Cloud Function response context.
 */
functions.http('helloHttp', (req, res) => {
  res.send(`Hello ${escapeHtml(req.query.name || req.body.name || 'World')}!`);
});

Gunakan npm untuk menginstal modul Node.js secara lokal

Cara termudah untuk menginstal modul Node.js secara lokal adalah dengan menggunakan perintah npm install di folder yang berisi fungsi Cloud Run Anda. Misalnya, perintah berikut akan menambahkan modul uuid:

npm install uuid

Perintah ini menggabungkan 2 langkah:

1. Menandai versi terbaru dari modul sebagai dependensi dalam file package.json Anda. Langkah ini sangat penting: Cloud Run Functions hanya menginstal modul yang dideklarasikan dalam file package.json Anda.
2. Mendownload modul ke direktori node_modules Anda. Dengan langkah ini, Anda dapat menggunakan modul tersebut saat melakukan pengembangan secara lokal.

Jika belum menginstal npm di komputer Anda, dapatkan npm.

Catatan: Paket npm tersedia untuk berbagai produk Google Cloud . Lihat Library klien Node.js.

Mengonfigurasi dependensi deployment

Anda dapat menginstal dependensi produksi untuk NPM, Yarn, atau Pnpm:

Pengelola paket NPM

Saat Anda men-deploy fungsi, Cloud Run Functions akan menginstal dependensi yang dideklarasikan dalam file package.json menggunakan perintah npm install:

npm install --production

Pengelola paket Yarn

Di runtime Node.js 8 dan yang lebih baru, jika file yarn.lock ada, Cloud Run Functions menggunakan perintah yarn install:

yarn install --production

Pengelola paket Pnpm

Di runtime Node.js 8 dan yang lebih baru, jika file pnpm-lock.yaml ada, Cloud Run Functions menggunakan perintah pnpm install:

pnpm install

Pengelola paket Bun

Pratinjau — Support for the Bun package manager

Fitur ini tunduk pada "Persyaratan Penawaran Pra-GA" di bagian Persyaratan Layanan Umum dari Persyaratan Khusus Layanan. Fitur pra-GA tersedia "sebagaimana adanya" dan mungkin memiliki dukungan terbatas. Untuk mengetahui informasi selengkapnya, lihat deskripsi tahap peluncuran.

Buildpack Node.js mendukung pengelola paket Bun. Dengan pengelola paket Bun, Anda dapat menginstal dependensi sambil mempertahankan struktur project Node.js dan versi runtime yang ada. Anda dapat memilih salah satu mekanisme berikut untuk menginstal dependensi menggunakan Bun:

• Deteksi otomatis: Buildpack Node.js mendeteksi pengelola paket Bun saat Anda menyertakan file bun.lock atau bun.lockb dalam project Anda. Untuk mengonfigurasi deteksi otomatis dengan Bun, ikuti langkah-langkah berikut:

  1. Buat file kunci:

     bun install --lockfile-only
     

  2. Deploy ke Cloud Run dengan menjalankan perintah berikut:

      gcloud run deploy --source . --base-image=nodejs24
     

• Keikutsertaan eksplisit: Tetapkan variabel lingkungan GOOGLE_PACKAGE_MANAGER ke bun. Dengan metode ini, Anda tidak perlu membuat dan memelihara file kunci. Jalankan perintah berikut untuk men-deploy ke Cloud Run:

  gcloud run deploy --source . --base-image=nodejs24 --set-build-env-vars GOOGLE_PACKAGE_MANAGER=bun
  

Meskipun buildpack menggunakan Bun untuk menginstal dependensi, runtime Node.js tetap menjalankan aplikasi Anda. Project Anda harus menyertakan file package.json. Untuk mengetahui detail selengkapnya tentang persyaratan konfigurasi, lihat Membangun aplikasi Node.js di dokumentasi Buildpack.

Menjalankan langkah-langkah build kustom selama deployment

Setelah men-deploy, Anda dapat melakukan langkah build kustom selama proses build fungsi dengan menambahkan skrip gcp-build dalam file package.json.

Saat skrip ini dijalankan, dependensi di kolom dependencies dan devDependencies dari file package.json Anda akan tersedia. Setelah menjalankan langkah build kustom, Cloud Run Functions akan menghapus dan membuat ulang folder node_modules, hanya dengan menginstal dependensi produksi yang dideklarasikan di kolom dependencies pada file package.json Anda.

Jika tidak ada skrip gcp-build di package.json, Cloud Run Functions hanya menginstal dependensi produksi.

Menggunakan paket sistem

Runtime Node.js juga menyertakan sejumlah paket sistem di lingkungan eksekusi.

Menyertakan modul Node.js lokal

Anda juga dapat menyertakan modul Node.js lokal sebagai bagian dari fungsi Anda. Caranya, deklarasikan modul Anda di package.json menggunakan awalan file:. Dalam contoh berikut, mymodule merujuk ke nama modul Anda dan mymoduledir adalah direktori yang berisi modul Anda:

  {
  "dependencies": {
    "mymodule": "file:mymoduledir"
  }
}

Kode untuk modul lokal ini tidak boleh disimpan di folder node_modules dalam direktori root fungsi Anda.

Catatan: jika Anda men-deploy menggunakan alat command line gcloud, gcloud akan otomatis membuat file .gcloudignore di direktori fungsi Anda. Secara default, folder node_modules ditambahkan ke .gcloudignore ini dan tidak diupload sebagai bagian dari deployment Anda. Anda tidak perlu menyertakan folder node_modules saat mengupload kode secara manual sebagai file zip. Anda tetap dapat men-deploy fungsi tanpa folder node_modules.

Memuat modul Node.js

Gunakan fungsi require() Node.js untuk memuat modul Node.js mana pun yang telah diinstal. Anda juga dapat menggunakan fungsi require() untuk mengimpor file lokal yang di-deploy bersama fungsi Anda.

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 v2 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 Cloud Run Functions, proses build akan otomatis menghasilkan kredensial Artifact Registry untuk akun layanan Cloud Build. Anda hanya perlu mencantumkan repositori Artifact Registry di .npmrc tanpa membuat kredensial tambahan. Contoh:

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

Pendekatan ini juga berfungsi untuk pengelola paket Yarn v1. Jika Anda menggunakan Yarn v2 atau yang lebih baru, Anda hanya perlu mencantumkan repositori Artifact Registry di .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 tulis tidak diperlukan selama deployment, dan dapat menimbulkan risiko keamanan.

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

Catatan: Jika Anda menggunakan izin khusus (seperti izin yang diperlukan untuk VPC), pastikan Anda secara eksplisit mengizinkan fungsi untuk mengakses repositori pribadi sasaran.

Format file

Jika Anda menggunakan file .npmrc untuk menetapkan token autentikasi kustom, file tersebut harus menyertakan baris berikut.

//REGISTRY_DOMAIN/:_authToken=AUTH_TOKEN

Ganti:

• REGISTRY_DOMAIN: nama domain registry npm pribadi Anda. Jika repositori Anda dihosting dengan 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 dengan 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.

Membangun fungsi dengan dependensi yang disalin

Dependensi yang disalin adalah dependensi yang sumbernya disertakan langsung dalam paket kode sumber Anda dan dibangun ulang bersama kode Anda sendiri. Anda membuat dependensi Node.js yang disalin dan melewati penginstalannya selama deployment dengan menggunakan variabel lingkungan build GOOGLE_VENDOR_NPM_DEPENDENCIES.

Prasyarat untuk dependensi yang disalin

1. Pastikan fungsi yang dapat bekerja dengan semua dependensi yang ingin Anda salin telah ditentukan dalam file package.json.

2. Instal dependensi ini secara lokal dengan menjalankan:

       npm install
   

3. Hapus node_modules dari file .gcloudignore di direktori kerja Anda.

4. Deploy fungsi, pastikan versi Node.js lokal Anda sama dengan versi yang Anda tentukan selama deployment.

5. Deploy fungsi dan dependensi yang disalin dengan perintah berikut:

     gcloud run deploy SERVICE \
       --source . \
       --function FUNCTION_ENTRY_POINT \
       --set-build-env-vars GOOGLE_VENDOR_NPM_DEPENDENCIES=true
   

   Ganti:

   • SERVICE: nama fungsi Cloud Run yang Anda deploy
   • FUNCTION_ENTRY_POINT: dengan titik entri ke fungsi Anda dalam kode sumber.

Jika Anda menentukan mesin npm dalam file package.json, versi npm yang ditentukan akan didownload pada waktu build. Untuk mencegah perilaku ini, hapus perilaku tersebut dari file package.json Anda.