Membuat aplikasi Node.js

Menentukan versi Node.js

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

Gunakan package.json

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

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

Gunakan GOOGLE_NODEJS_VERSION

Anda juga dapat menentukan versi Node.js menggunakan variabel lingkungan GOOGLE_NODEJS_VERSION. Jika kedua konfigurasi ditetapkan, nilai GOOGLE_NODEJS_VERSION akan lebih diprioritaskan daripada properti engines.node. Jika Anda tidak memberikan versi, buildpack akan menggunakan Node.js versi LTS terbaru.

Untuk mengonfigurasi buildpack agar menggunakan Node.js 24 saat men-deploy aplikasi, jalankan perintah berikut:

pack build --builder=gcr.io/buildpacks/builder \
   sample-functions-framework-node \
   --env GOOGLE_NODEJS_VERSION=24.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 kolom engines.node.
• Saat men-deploy aplikasi ke lingkungan standar App Engine, properti engines.node harus kompatibel dengan runtime yang ditentukan di app.yaml. Untuk mengetahui informasi selengkapnya tentang opsi konfigurasi engines.node dalam file package.json, lihat dokumentasi NPM resmi untuk topik mesin.
• Saat men-deploy fungsi ke Cloud Run Functions, properti engines.node harus kompatibel dengan runtime yang digunakan untuk men-deploy fungsi Anda

Menginstal dependensi

NPM adalah pengelola paket default untuk semua versi Node.js. Bagian berikut mencakup dependensi yang kompatibel untuk aplikasi Node.js Anda.

Pengelola paket NPM

• NPM adalah pengelola paket default.
• Jika memungkinkan, gunakan package-lock.json untuk meningkatkan performa cache.
• Secara default, hanya dependensi produksi yang diinstal.
• Tentukan versi npm menggunakan kolom engines.npm di file package.json. Untuk mengetahui informasi selengkapnya, lihat dokumentasi NPM.

Pengelola paket Yarn

• buildpack menggunakan Yarn saat Anda menyertakan file yarn.lock dalam project.
• Tentukan versi yarn di kolom engines.yarn pada file package.json.
• buildpack mendukung mode Yarn2 PnP jika project Anda menyertakan folder .yarn/cache.

Pengelola paket Pnpm

• buildpack menggunakan Pnpm saat Anda menyertakan file pnpm-lock.yaml dalam project Anda.
• Tentukan versi pnpm di kolom engines.pnpm pada file package.json.
• Untuk contoh penggunaan, lihat sample-node-pnpm.

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, google.nodejs.bun buildpack untuk menginstal dependensi. Untuk menggunakan pengelola paket Bun, ikuti langkah-langkah berikut:

• Buat file bun.lock atau bun.lockb di direktori root untuk deteksi otomatis.
• Atau, Anda juga dapat menetapkan variabel lingkungan GOOGLE_PACKAGE_MANAGER secara eksplisit ke bun. Dengan metode ini, Anda tidak perlu membuat dan memelihara file kunci.
• Project Anda harus menyertakan file package.json. Anda dapat menentukan versi Bun di kolom engines.bun atau packageManager pada file package.json. Jika tidak ada versi yang ditentukan, buildpack akan menggunakan rilis stabil terbaru secara default.

Untuk mengetahui informasi selengkapnya tentang cara men-deploy ke Cloud Run, lihat Menentukan dependensi di Node.js.

Untuk mengetahui informasi selengkapnya tentang pengelola paket Bun, lihat dokumentasi Bun.

Prioritas pengelola paket

Buildpack Node.js menentukan pengelola paket berdasarkan konfigurasi dalam urutan prioritas berikut:

1. GOOGLE_PACKAGE_MANAGER selalu lebih diprioritaskan. Variabel lingkungan ini hanya mendukung bun (pratinjau).

2. Buildpack memeriksa file kunci dalam urutan berikut:

   • Yarn - yarn.lock
   • pnpm - pnpm-lock.yaml
   • Roti - bun.lock atau bun.lockb
   • NPM - package-lock.json

3. Jika Anda tidak menetapkan variabel lingkungan atau menggunakan file kunci, buildpack akan menggunakan NPM secara default.

Modul pribadi

Gunakan modul npm pribadi dengan menyediakan setelan untuk mengautentikasi dengan registry dalam .npmrc file 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 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, sertakan hal berikut:

//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.

Gunakan 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.

Gunakan 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 menjalankan perintah yang Anda tentukan di kolom scripts.start pada file package.json Anda. Jika Anda tidak mengonfigurasi kolom scripts.start, buildpack akan menjalankan perintah npm start.

Sebaiknya gunakan Procfile karena akan mengeluarkan pengelola paket dari jalur dan memungkinkan eksekusi langsung.

Variabel lingkungan

Anda dapat menetapkan variabel lingkungan untuk mengonfigurasi build image container.

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

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.

NPM_CONFIG_<key>

Menentukan parameter konfigurasi, misalnya, NPM_CONFIG_FLAG=value meneruskan -flag=value ke perintah npm.

Untuk mengetahui informasi tentang variabel lingkungan ini, lihat Config dalam dokumentasi NPM.

GOOGLE_PACKAGE_MANAGER (pratinjau)

Hanya mendukung pengelola paket Bun. Variabel lingkungan ini berfungsi sebagai penggantian untuk proses deteksi otomatis. Misalnya, GOOGLE_PACKAGE_MANAGER=bun memaksa penggunaan Bun meskipun Anda tidak membuat file lock.

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.