#Menulis Plugin Pertama

Dokumen ini akan memandu Anda membuat plugin Block yang dapat digunakan di halaman dari nol, untuk membantu Anda memahami struktur dasar dan alur pengembangan plugin NocoBase.

#Prasyarat

Sebelum memulai, pastikan Anda telah menginstal NocoBase. Jika belum diinstal, Anda dapat merujuk pada:

• Instalasi menggunakan create-nocobase-app
• Instalasi dari source code Git

Setelah instalasi selesai, Anda dapat memulai.

#Langkah 1: Membuat Skeleton Plugin melalui CLI

Jalankan perintah berikut di root direktori repository untuk dengan cepat menggenerate plugin kosong:

yarn pm create @my-project/plugin-hello

Setelah perintah berhasil dijalankan, file dasar akan digenerate di direktori packages/plugins/@my-project/plugin-hello, dengan struktur default sebagai berikut:

packages/plugins/@my-project/plugin-hello/
├─ package.json
├─ README.md
├─ .npmignore
├─ client-v2.d.ts            # Deklarasi tipe entry client v2
├─ client-v2.js              # Entry client v2
├─ client.d.ts               # Deklarasi tipe entry client v1
├─ client.js                 # Entry client v1
├─ server.d.ts               # Deklarasi tipe entry server
├─ server.js                 # Entry server
└─ src
   ├─ index.ts               # Default ekspor plugin server
   ├─ client-v2              # Lokasi penyimpanan kode client v2
   │  ├─ index.tsx           # Class plugin client yang diekspor secara default
   │  ├─ plugin.tsx          # Entry plugin (extends @nocobase/client-v2 Plugin)
   │  └─ client.d.ts
   ├─ client                 # Lokasi penyimpanan kode client v1
   │  ├─ index.tsx
   │  ├─ plugin.tsx
   │  ├─ locale.ts
   │  ├─ models
   │  │  └─ index.ts
   │  └─ client.d.ts
   ├─ server                 # Lokasi penyimpanan kode server
   │  ├─ index.ts            # Class plugin server yang diekspor secara default
   │  ├─ plugin.ts           # Entry plugin (extends @nocobase/server Plugin)
   │  └─ collections         # Collections server (awalnya direktori kosong)
   └─ locale                 # Resource multi-bahasa
      ├─ en-US.json
      └─ zh-CN.json

Scaffold hanya menghasilkan skeleton minimal, di dalam src/client-v2/ hanya ada file entry. Direktori models/ dan locale.ts yang digunakan pada langkah-langkah berikutnya perlu Anda buat sendiri.

Selanjutnya jalankan mode development agar perubahan kode langsung ter-hot update:

• Jika proyek dibuat melalui NocoBase CLI (nb init), jalankan di direktori root proyek (<app-path>):

  nb source dev

• Jika Anda meng-clone sendiri repository source code NocoBase, jalankan di direktori root source code:

  yarn dev

Setelah berjalan, akses halaman "Plugin Manager" di browser (alamat default: http://localhost:13000/admin/settings/plugin-manager) untuk memastikan plugin sudah muncul di daftar.

#Langkah 2: Mengimplementasikan Block Client Sederhana

Selanjutnya tambahkan model Block kustom ke plugin, untuk menampilkan teks selamat datang.

1. Tambahkan file utilitas terjemahan src/client-v2/locale.ts. tExpr digunakan untuk mendeklarasikan ekspresi terjemahan bernamespace, sedangkan useT menyediakan fungsi terjemahan di dalam komponen:

import { tExpr as _tExpr, useFlowEngine } from '@nocobase/flow-engine';
// @ts-ignore
import pkg from '../../package.json';

export function useT() {
  const engine = useFlowEngine();
  return (str: string) => engine.context.t(str, { ns: [pkg.name, 'client'] });
}

export function tExpr(key: string) {
  return _tExpr(key, { ns: [pkg.name, 'client'] });
}

2. Tambahkan file model Block src/client-v2/models/HelloBlockModel.tsx:

import React from 'react';
import { BlockModel } from '@nocobase/client-v2';
import { tExpr } from '../locale';

export class HelloBlockModel extends BlockModel {
  renderComponent() {
    return (
      <div>
        <h1>Hello, NocoBase!</h1>
        <p>This is a simple block rendered by HelloBlockModel.</p>
      </div>
    );
  }
}

HelloBlockModel.define({
  label: tExpr('Hello block'),
});

3. Daftarkan model Block. Hanya membuat file model saja belum cukup — runtime front-end tidak memindai direktori models/ secara otomatis, sehingga model perlu didaftarkan secara eksplisit di entry plugin. Edit src/client-v2/plugin.tsx, deklarasikan cara pemuatan model melalui registerModelLoaders di dalam load():

import { Plugin } from '@nocobase/client-v2';

export class PluginHelloClientV2 extends Plugin {
  async load() {
    this.flowEngine.registerModelLoaders({
      HelloBlockModel: {
        loader: () => import('./models/HelloBlockModel'),
      },
    });
  }
}

export default PluginHelloClientV2;

registerModelLoaders menerima fungsi lazy loading, sehingga model baru dimuat ketika benar-benar digunakan. Nama key (HelloBlockModel) harus sama dengan nama class model, karena runtime mengambil class model dari named export modul berdasarkan nama tersebut.

Setelah menyimpan kode, jika Anda menjalankan mode development, Anda akan melihat log hot update di output terminal.

#Langkah 3: Aktifkan dan Coba Plugin

Anda dapat mengaktifkan plugin melalui command line atau antarmuka:

• Command Line

  yarn pm enable @my-project/plugin-hello

• Antarmuka Manajemen: Akses "Plugin Manager", temukan @my-project/plugin-hello, klik "Aktifkan".

Setelah diaktifkan, buat halaman "Modern page (v2)" baru, saat menambahkan Block Anda akan melihat "Hello block", masukkan ke halaman dan Anda akan melihat konten selamat datang yang baru saja Anda tulis.

#Membuat Plugin Default Preset atau Default Aktif (Opsional)

Di atas dijelaskan cara mengaktifkan plugin secara manual satu per satu. Jika Anda memelihara aplikasi NocoBase sendiri dan ingin beberapa plugin sudah siap secara otomatis setelah menjalankan nocobase install (instalasi pertama) atau nocobase upgrade (upgrade), Anda dapat menggunakan dua environment variable untuk mengontrol status default plugin:

• APPEND_PRESET_LOCAL_PLUGINS (tambahkan plugin preset lokal default) — Menambahkan plugin ke daftar plugin preset lokal; setelah instalasi akan muncul di "Plugin Manager", tetapi tidak aktif secara default dan perlu diaktifkan secara manual
• APPEND_PRESET_BUILT_IN_PLUGINS (tambahkan plugin built-in default) — Menambahkan plugin ke daftar plugin built-in; saat instalasi plugin diaktifkan secara otomatis, dan sebagai plugin built-in, tidak dapat dinonaktifkan atau dihapus di "Plugin Manager"

Nilai kedua variable ini adalah nama paket plugin (field name di package.json), pisahkan beberapa plugin dengan koma. Konfigurasi di file .env seperti berikut:

# Default preset: muncul di daftar Plugin Manager, tetapi tidak diaktifkan secara otomatis
APPEND_PRESET_LOCAL_PLUGINS=@my-project/plugin-hello,@my-project/plugin-hello-world

# Default aktif: diinstal dan diaktifkan secara otomatis, serta tidak dapat dinonaktifkan melalui antarmuka
APPEND_PRESET_BUILT_IN_PLUGINS=@my-project/plugin-hello,@my-project/plugin-hello-world

Pada umumnya, untuk pengembangan dan debugging lokal, yarn pm enable sudah cukup. Kedua variable ini lebih cocok untuk skenario distribusi "siap pakai" — misalnya Anda mengemas aplikasi NocoBase dengan plugin tertentu dan ingin plugin langsung tersedia setelah inisialisasi.

#Langkah 4: Build & Packaging

Ketika Anda siap mendistribusikan plugin ke environment lain, Anda perlu build kemudian packaging:

yarn build @my-project/plugin-hello --tar
# atau jalankan dalam dua langkah
yarn build @my-project/plugin-hello
yarn nocobase tar @my-project/plugin-hello

Setelah build selesai, file packaging secara default berada di direktori storage/tar/, dengan nama file <nama-paket>-<versi>.tgz, misalnya storage/tar/@my-project/plugin-hello-0.1.0.tgz.

#Langkah 5: Upload ke Aplikasi NocoBase Lain

Upload dan ekstrak file packaging ke direktori ./storage/plugins aplikasi target. Untuk langkah detail, lihat Instalasi & Upgrade Plugin.

Jika aplikasi target dibuat melalui NocoBase CLI (nb init), Anda juga dapat langsung mengimpornya dengan nb plugin import tanpa perlu mengekstrak secara manual:

nb plugin import /your/path/plugin-hello-0.1.0.tgz

#Tautan Terkait

• Ikhtisar Plugin Development — Memahami arsitektur microkernel NocoBase dan siklus hidup plugin
• Struktur Direktori Proyek — Konvensi direktori proyek, path dan prioritas loading plugin
• Ikhtisar Pengembangan Server — Pengantar menyeluruh dan konsep inti plugin server
• Ikhtisar Pengembangan Client — Pengantar menyeluruh dan konsep inti plugin client
• Build & Packaging — Alur build, packaging, dan distribusi plugin
• Test Pengujian — Menulis test case plugin server
• Instalasi menggunakan create-nocobase-app — Salah satu cara instalasi NocoBase
• Instalasi dari source code Git — Instalasi NocoBase dari source code
• Instalasi & Upgrade Plugin — Upload plugin yang sudah di-package ke environment lain
• Environment Variable — Konfigurasi environment variable untuk plugin preset dan built-in