SpyBara
Go Premium

plugins/dependencies.md 2026-11-10 21:57 UTC to 2026-11-11 22:59 UTC

This page contains 43 additions and 43 deletions.

2026
Wed 11 22:59

Dependensi plugin

Deklarasikan plugin yang plugin Anda bergantung padanya, dengan rentang versi seperti ^1.2, dan lihat bagaimana Claude Code menginstal, menyelesaikan, dan memangkas dependensi tersebut.

Dependensi plugin adalah plugin lain yang plugin Anda andalkan, seperti plugin yang memanggil MCP server atau skill-nya. Setiap dependensi melacak versi terbaru yang disediakan marketplace-nya kecuali Anda mendeklarasikan batasan versi, rentang semantic-version seperti ^2.0 atau ~2.1.0 yang telah Anda uji.

Halaman ini adalah untuk penulis plugin yang mendeklarasikan dependensi dalam plugin.json dan untuk pengelola marketplace yang menandai rilis.

[!NOTE]

Kasus-kasus ini tercakup di halaman lain:

Untuk menambahkan batasan, mulai dari Deklarasikan dependensi dengan batasan versi. Jika Anda mengelola plugin yang bergantung padanya oleh orang lain, tandai rilis Anda sehingga batasan mereka dapat diselesaikan.

Deklarasikan dependensi

Tanpa batasan versi, dependensi bergerak ke setiap rilis baru yang marketplace-nya terbitkan saat pengguna memperbarui. Jika rilis itu mengganti nama alat MCP yang plugin Anda panggil, plugin Anda rusak untuk semua orang yang memperbarui.

Dengan batasan seperti ~2.1.0 pada dependensi dari sumber yang didukung git, pengguna yang memiliki plugin Anda terinstal terus menerima patch 2.1.x dari dependensi dan tidak pernah pindah ke 2.2. Untuk meningkatkan sesuai jadwal Anda sendiri, uji terhadap rilis yang lebih baru dan kemudian terbitkan versi baru plugin Anda dengan batasan yang lebih luas.

Deklarasikan dependensi dengan batasan versi

Daftar dependensi dalam array dependencies dari .claude-plugin/plugin.json plugin Anda. Manifes berikut mendeklarasikan satu dependensi tanpa versi dan satu dependensi terbatas:

{
  "name": "deploy-kit",
  "version": "3.1.0",
  "dependencies": [
    "audit-logger",
    { "name": "secrets-vault", "version": "~2.1.0" }
  ]
}

Entri dapat berupa string: nama plugin saja, seperti "audit-logger" dalam manifes ini, atau "name@marketplace" untuk menyelesaikannya di marketplace lain. Dengan string kosong, plugin Anda bergantung pada versi apa pun yang disediakan marketplace plugin tersebut.

Untuk menetapkan batasan versi, gunakan objek dengan bidang-bidang ini, masing-masing berupa string:

Bidang Deskripsi
name Nama plugin dependensi, seperti yang muncul dalam entri marketplace-nya. Claude Code mencarinya di marketplace yang sama dengan plugin yang mendeklarasikan kecuali Anda menetapkan marketplace. Diperlukan.
version Rentang semantic-version seperti ~2.1.0, ^2.0, >=1.4, atau =2.1.0. Dependensi menginstal pada tag git tertinggi yang memenuhi rentang ini, jadi pengelola dependensi harus menandai rilis.
marketplace Marketplace berbeda untuk menyelesaikan name di dalamnya. Daftar izin mengontrol dependensi lintas-marketplace, dijelaskan dalam Bergantung pada plugin dari marketplace lain.

Rentang tidak cocok dengan versi pra-rilis seperti 2.0.0-beta.1 kecuali Anda memilih dengan akhiran pra-rilis seperti ^2.0.0-0.

Bundel plugin untuk tim

Untuk memungkinkan insinyur menginstal set plugin yang dikurasi dengan satu perintah, terbitkan plugin yang manifesnya berisi name dan array dependencies. Manifes plugin hanya membutuhkan name, jadi ini adalah plugin yang valid, dan menginstalnya menginstal setiap dependensi.

Misalnya, tim platform dapat menerbitkan bundel khusus peran di marketplace internal sehingga insinyur menjalankan satu claude plugin install alih-alih menginstal setiap plugin secara terpisah:

{
  "name": "backend-standard",
  "version": "1.0.0",
  "description": "Standard plugin set for backend engineers",
  "dependencies": [
    "secrets-vault",
    "deploy-kit",
    { "name": "db-migrate", "version": "^3.0" },
    "oncall-runbook"
  ]
}

Untuk menambahkan plugin ke set standar nanti, terbitkan versi backend-standard baru dengan dependensi tambahan. Ketika marketplace tidak auto-update secara default, insinyur baik mengaktifkan auto-update untuk marketplace atau memperbarui secara manual:

  • Aktifkan auto-update untuk marketplace: pembaruan auto-update berikutnya memindahkan bundel ke versi baru dan menginstal dependensi apa pun yang ditambahkannya.
  • Perbarui secara manual: jalankan claude plugin update backend-standard di shell, kemudian /reload-plugins dalam sesi terbuka untuk menginstal dependensi yang baru ditambahkan.

Untuk langkah-langkah sisi insinyur, lihat Jaga plugin tetap diperbarui.

Untuk menerapkan bundel ke semua orang dalam organisasi, administrator menambahkannya ke enabledPlugins dalam pengaturan terkelola. Lihat Pra-instal dan butuhkan plugin.

Bergantung pada plugin dari marketplace lain

Secara default, Claude Code tidak menginstal dependensi dari marketplace berbeda dari marketplace plugin yang mendeklarasikan sendiri, kecuali pengguna sudah memiliki dependensi itu terinstal dan diaktifkan pada cakupan yang sama. Default ini mencegah satu marketplace secara diam-diam menginstal plugin dari sumber yang belum ditinjau pengguna.

Untuk memungkinkan instalasi, tambahkan nama marketplace target ke allowCrossMarketplaceDependenciesOn dalam marketplace.json marketplace root. Marketplace root adalah yang menghosting plugin yang pengguna instal. Hanya daftar izin marketplace root yang berlaku.

marketplace.json berikut memungkinkan deploy-kit bergantung pada plugin dari your-shared-marketplace:

{
  "name": "your-marketplace",
  "owner": { "name": "Your Org" },
  "allowCrossMarketplaceDependenciesOn": ["your-shared-marketplace"],
  "plugins": [
    {
      "name": "deploy-kit",
      "source": "./deploy-kit",
      "dependencies": [
        { "name": "audit-logger", "marketplace": "your-shared-marketplace" }
      ]
    }
  ]
}

Jika allowCrossMarketplaceDependenciesOn hilang atau tidak menyertakan marketplace target, Claude Code tidak menginstal dependensi. Ketika dependensi dideklarasikan dalam entri marketplace, instalasi itu sendiri ditolak dengan pesan yang dimulai Dependency "audit-logger@your-shared-marketplace" (required by deploy-kit@your-marketplace) is in marketplace "your-shared-marketplace", which is not in the allowlist dan menyebutkan bidang yang akan ditetapkan. Ketika dideklarasikan dalam plugin.json, instalasi selesai tanpa dependensi dan plugin Anda kemudian gagal dimuat.

Pemeriksaan daftar izin tidak berlaku untuk dependensi yang sudah diaktifkan. Jika pengguna menginstal audit-logger dari your-shared-marketplace sendiri terlebih dahulu, pada cakupan yang sama, deploy-kit kemudian menginstal tanpa perubahan apa pun pada daftar izin.

Uji plugin dan dependensinya secara lokal

Jika Anda mengembangkan plugin dan plugin yang bergantung padanya pada saat yang sama, mulai Claude Code dari shell Anda dan muat keduanya dengan --plugin-dir:

claude --plugin-dir ./my-dependency --plugin-dir ./my-plugin

Salinan lokal dependensi memenuhi entri dependensi plugin Anda, jadi Anda tidak perlu menginstal dependensi dari marketplace-nya.

  • Tidak ada version yang diperlukan: plugin.json lokal juga tidak perlu version, karena batasan versi tidak diperiksa terhadap salinan lokal.
  • Entri yang menyebutkan marketplace: entri yang menyebutkan marketplace juga cocok dengan salinan lokal pada Claude Code v2.1.242 atau lebih baru.

Sampai Anda menginstal dependensi dari marketplace-nya, plugin Anda berhenti dimuat setiap kali salinan lokal dinonaktifkan atau tidak ada:

  • Anda menonaktifkan salinan lokal: plugin Anda dinonaktifkan pada pemuatan plugin berikutnya, dengan kesalahan yang berakhir is disabled — enable it or remove the dependency. Ketika kesalahan menyebutkan dependensi sebagai <name>@inline, pengidentifikasi itu merujuk pada salinan --plugin-dir.
  • Anda memulai sesi tanpa flag --plugin-dir dependensi: kesalahan melaporkan dependensi sebagai tidak terinstal. Lewatkan flag lagi, atau instal dependensi dari marketplace-nya.

Ketika kedua plugin berada dalam satu folder induk, Anda dapat meneruskan folder itu ke --plugin-dir sekali. Jika folder itu sendiri bukan plugin, Claude Code memuat setiap folder anak yang memiliki .claude-plugin/plugin.json. Memerlukan Claude Code v2.1.265 atau lebih baru.

Merilis plugin yang menjadi dependensi plugin lain

Jika Anda memelihara plugin yang menjadi dependensi plugin lain dengan batasan versi, beri tag pada rilisnya agar batasan tersebut dapat di-resolve. Sebuah batasan di-resolve berdasarkan tag git pada repositori yang meng-host plugin tersebut. Beri tag pada repositori yang ditunjuk oleh sumber plugin milik plugin tersebut di marketplace.json:

  • Sumber github, url, atau git-subdir: repositori milik plugin itu sendiri, sehingga pembuat plugin yang membuat tag
  • Path relatif seperti ./plugins/secrets-vault: repositori marketplace, sehingga pengelola marketplace yang membuat tag

Membuat tag rilis

Beri tag pada setiap rilis dengan format <plugin-name>--v<version>, dengan <version> sesuai dengan field version di plugin.json pada commit tersebut. Prefiks nama plugin memungkinkan satu repositori marketplace meng-host beberapa plugin dengan riwayat versi yang independen.

Buat tag dari direktori plugin, dengan remote origin yang dikonfigurasi untuk menerima tag yang di-push, menggunakan claude plugin tag:

claude plugin tag --push

Perintah ini menyusun nama tag dari manifest plugin. Sebelum membuat tag, perintah ini menjalankan pemeriksaan berikut:

  • Memvalidasi plugin
  • Memeriksa bahwa plugin.json dan entri marketplace menyatakan versi yang sama, jika direktori plugin berada di dalam checkout marketplace
  • Mensyaratkan working tree yang bersih di bawah direktori plugin
  • Menolak jika tag sudah ada

Eksekusi yang berhasil mencetak Created tag secrets-vault--v2.1.0. Dengan --push, perintah ini juga mencetak Pushed to origin. Tanpa --push, perintah ini mencetak perintah git push untuk Anda jalankan sendiri.

Berikan --dry-run untuk melihat rencananya tanpa membuat apa pun.

Referensi claude plugin tag mencantumkan flag lainnya.

Anda juga dapat menjalankan git tag secrets-vault--v2.1.0 secara langsung, selama Anda sendiri menjaga version di plugin.json dan di entri marketplace tetap sinkron.

Membatasi dependensi yang memiliki sumber non-git

Resolusi berbasis tag hanya berlaku untuk sumber berbasis git. Untuk dependensi dengan sumber plugin npm, archive, atau command, batasan tersebut tidak mengontrol versi mana yang diambil. Batasan tetap diperiksa saat plugin dimuat, dan plugin yang bergantung akan dinonaktifkan jika versi yang terinstal tidak memenuhinya.

Untuk sumber npm, archive, dan command, versi yang diperiksa adalah version di plugin.json milik dependensi. Tetapkan versi di sana sebelum Anda membatasi dependensi tersebut, karena plugin.json yang tidak menetapkan versi tidak memenuhi batasan apa pun.

Claude Code tidak pernah menginstal sendiri dependensi dengan sumber command, sehingga pengguna menginstalnya terlebih dahulu. Claude Code juga tidak pernah menjalankan headersHelper milik dependensi, sehingga pengguna juga menginstal dependensi yang entri marketplace-nya menetapkan headersHelper sebelum mereka menginstal plugin Anda.

Selain claude plugin install, operasi berikut juga menginstal dependensi yang dideklarasikan tetapi belum ada, dan batasan terkait command dan headersHelper juga berlaku untuk operasi tersebut:

  • /reload-plugins
  • Pembaruan otomatis marketplace milik plugin yang bergantung
  • Menjalankan ulang claude plugin install pada plugin yang bergantung
  • claude plugin marketplace add

Bagaimana dependensi berperilaku bagi pengguna Anda

Bagian-bagian ini menjelaskan bagaimana Claude Code me-resolve, memeriksa, dan menggabungkan batasan yang Anda deklarasikan setelah plugin Anda diinstal bersama plugin lain.

Bagaimana batasan di-resolve terhadap tag

Ketika pengguna menginstal plugin yang mendeklarasikan { "name": "secrets-vault", "version": "~2.1.0" }, dependensi diinstal dari tag secrets-vault--v tertinggi yang memenuhi ~2.1.0 pada repositori yang meng-host secrets-vault. Ketika tidak ada tag yang memenuhi rentang tersebut, instalasi akan gagal atau menggunakan salinan marketplace saat ini:

  • Plugin dengan repositorinya sendiri: instalasi gagal dengan pesan yang berisi Dependency "secrets-vault@your-marketplace" has no git tag satisfying.
  • Plugin yang direferensikan melalui jalur relatif: instalasi menggunakan salinan marketplace saat ini sebagai gantinya, dan batasan diperiksa saat plugin dimuat. Jika salinan tersebut berada di luar rentang, plugin yang bergantung tetap dinonaktifkan dan claude plugin list menampilkan Requires "secrets-vault@your-marketplace" ~2.1.0, installed 3.0.0.

Untuk plugin yang direferensikan marketplace melalui jalur relatif, marketplace yang Anda tambahkan sebagai jalur folder lokal juga me-resolve batasan terhadap tag git folder tersebut, ketika folder tersebut merupakan repositori git. Folder lokal yang bukan repositori git tidak memiliki tag, sehingga Claude Code menginstal dependensi dari konten folder saat ini sebagai gantinya.

Konfirmasi versi yang di-resolve

Untuk mengonfirmasi versi mana yang menjadi hasil resolve suatu batasan, jalankan claude plugin list di shell Anda. Dependensi yang di-resolve melalui tag menampilkan versinya dengan akhiran commit 12 karakter, seperti 2.1.0-8713c5b11005.

Pemeriksaan batasan menggunakan versi tag alih-alih version di plugin.json, bahkan jika plugin.json pada commit tersebut tertinggal.

Jika Anda memindahkan tag secara paksa ke commit yang berbeda, instalasi berikutnya akan mengambil konten commit tersebut alih-alih menggunakan kembali salinan cache yang usang. Lihat Versi dan pembaruan untuk mengetahui bagaimana versi plugin menjadi kunci cache-nya.

Menggabungkan batasan dari beberapa plugin

Ketika beberapa plugin yang terinstal membatasi dependensi yang sama, dependensi di-resolve ke versi tertinggi yang memenuhi semua rentang mereka. Kombinasi umum di-resolve seperti ini:

Plugin A memerlukan Plugin B memerlukan Hasil
^2.0 >=2.1 Satu instalasi pada tag 2.x tertinggi yang sama dengan atau di atas 2.1.0. Kedua plugin dimuat.
~2.1 ~3.0 Instalasi plugin B gagal dengan pesan has conflicting version requirements. Plugin A dan dependensi tetap seperti semula.
=2.1.0 tidak ada Dependensi tetap pada 2.1.0. Pembaruan otomatis melewati versi yang lebih baru selama plugin A terinstal.

Pembaruan otomatis mengambil dependensi yang dibatasi pada tag git tertinggi yang memenuhi rentang setiap plugin yang terinstal, alih-alih pada versi terbaru marketplace. Jika rentang plugin yang terinstal tidak saling tumpang tindih, pembaruan otomatis membiarkan dependensi tersebut pada versinya saat ini, dan tab Errors pada /plugin menampilkan entri yang menyebutkan plugin pembatasnya. Jika rentangnya tumpang tindih tetapi tidak ada tag yang berada dalam rentang tersebut, pembaruan otomatis mengambil salinan marketplace saat ini dan melewati pembaruan ketika version salinan tersebut berada di luar rentang salah satu plugin yang terinstal.

Ketika pengguna menghapus instalasi plugin terakhir yang membatasi suatu dependensi, dependensi tersebut tidak lagi dibatasi pada rentang versi dan kembali mengikuti entri marketplace-nya pada pembaruan berikutnya.

Dependensi ketika plugin Anda dimuat dari claude.ai

Ketika pengguna mengaktifkan plugin Anda untuk akun claude.ai mereka, Claude Code memuatnya sebagai <name>@synced, tanpa marketplace. Untuk salinan plugin Anda tersebut, Claude Code menganggap entri dependensi yang menyebutkan marketplace sebagai terpenuhi ketika pengguna memiliki salah satu dari berikut ini:

  • Dependensi dari marketplace-nya: diinstal dari marketplace yang disebutkan dalam entri Anda, dan diaktifkan. Claude Code memeriksa rentang version dalam entri Anda terhadap versi salinan yang terinstal.
  • Plugin claude.ai dengan nama yang sama: diaktifkan dari akun claude.ai mereka. Claude Code memeriksa rentang version dalam entri Anda terhadap version plugin tersebut, dan plugin yang tidak menyatakan version lolos pemeriksaan.

Jika Anda meminta pengguna untuk mengaktifkan plugin Anda dari claude.ai, minta mereka untuk mengaktifkan dependensinya di sana juga, atau menginstalnya dari marketplace-nya.

Plugin claude.ai memenuhi entri tersebut hanya ketika plugin Anda juga dimuat dari claude.ai.

Lihat juga