# สร้างปลั๊กอิน JavaScript

> ปลั๊กอิน JavaScript คือ Site Code ที่แพ็กเป็นปลั๊กอิน — manifest, สิทธิ์ของโค้ด (scopes), การตั้งค่า, migration, dependencies, การแพ็ก .zip และการทดสอบ

ที่มา: https://anasaki.live/docs/developers/js-plugins

ปลั๊กอิน JavaScript (`&#34;runtime&#34;: &#34;js&#34;`) ใช้ API เดียวกับ [Site Code](/docs/developers/site-code) แต่รันเป็น **หน่วยแยก** ของตัวเอง: มีตาราง การตั้งค่า คุกกี้ ฮุก และ route ของตัวเอง และทำได้เฉพาะสิทธิ์ที่ผู้ดูแลอนุมัติ ปลั๊กอินทางการทุกตัวก็เขียนแบบนี้ (ซอร์สอยู่ใน `plugins-official/` ของ repository)

## โครงสร้างแพ็กเกจ

```text
my-plugin/
├── manifest.json          (จำเป็น — ที่รากของ zip)
├── README.md              (แสดงในร้าน — เขียนไทย + อังกฤษ)
├── code/
│   ├── main.ts            (ไฟล์เริ่มต้น)
│   ├── lib.ts
│   └── index.d.ts         (ไม่บังคับ: type ให้ปลั๊กอินที่ import)
├── migrations/
│   └── 001_create_tables.ts
├── assets/                (css / js / รูป / ฟอนต์ ที่เสิร์ฟสาธารณะ)
└── screenshots/           (รูปสำหรับหน้าร้าน)
```

ไฟล์ใน `code/` และ `migrations/` รับ `.ts .js .mjs .json .md` ไม่เกิน 200 ไฟล์ ไฟล์ละ 512 KB รวม 2 MB ทั้งแพ็กเกจไม่เกิน 30 MB

## manifest.json

```json
{
  &#34;id&#34;: &#34;event-booking&#34;,
  &#34;name&#34;: &#34;Event booking&#34;,
  &#34;version&#34;: &#34;1.0.0&#34;,
  &#34;description&#34;: &#34;จองที่นั่งอีเวนต์ / Event seat booking&#34;,
  &#34;author&#34;: &#34;Your name&#34;,
  &#34;icon&#34;: &#34;🎟&#34;,
  &#34;category&#34;: &#34;content&#34;,
  &#34;license&#34;: &#34;MIT&#34;,
  &#34;minCore&#34;: &#34;2.0.4&#34;,
  &#34;runtime&#34;: &#34;js&#34;,
  &#34;permissions&#34;: [&#34;code&#34;, &#34;settings&#34;],
  &#34;settings&#34;: [
    { &#34;key&#34;: &#34;notifyEmail&#34;, &#34;type&#34;: &#34;text&#34;, &#34;label&#34;: { &#34;th&#34;: &#34;อีเมลแจ้งเตือน&#34;, &#34;en&#34;: &#34;Notification email&#34; } }
  ],
  &#34;code&#34;: {
    &#34;entry&#34;: &#34;code/main.ts&#34;,
    &#34;scopes&#34;: [&#34;db&#34;, &#34;routes&#34;, &#34;mail&#34;, &#34;admin-pages&#34;],
    &#34;routes&#34;: [&#34;/booking&#34;],
    &#34;exports&#34;: [&#34;seatsLeft&#34;],
    &#34;hooks&#34;: { &#34;events&#34;: [&#34;event-booking.booked&#34;] }
  },
  &#34;requires&#34;: { &#34;thai&#34;: &#34;^1.0.0&#34; }
}
```

| ฟิลด์ | หมายเหตุ |
| --- | --- |
| `id` | `^[a-z0-9][a-z0-9-]{2,39}$` ไม่ซ้ำ — ใช้เป็น namespace ทุกอย่าง |
| `version` | semver — ทุกการอัปเดตต้องสูงขึ้น |
| `minCore` | เวอร์ชัน Anasaki Studio ต่ำสุดที่ติดตั้งได้ |
| `permissions` | ต้องมี `code` และ permission ของทุกฟีเจอร์ที่ใช้ (`settings`, `bodyEnd`, `webhooks`…) |
| `code.entry` | จำเป็น ไฟล์ `.ts` / `.js` / `.mjs` ใน `code/` |
| `code.scopes` | สิทธิ์ของโค้ด — เรียก API นอกสิทธิ์จะ throw |
| `code.routes` | prefix ของพาธสาธารณะที่ `site.route` / `site.page` ใช้ได้ (ต้องมี scope `routes`) — a-z 0-9 `_` `-` และตั้งแต่ CMS 2.2.2 มีจุดได้ เช่น `/feed.xml` |
| `code.hosts` | โดเมนที่ `http.fetch` เรียกได้ (ต้องมี scope `http`) |
| `code.library` / `code.exports` | โมดูลที่ปลั๊กอินอื่น import ได้ / ฟังก์ชันที่เรียกด้วย `plugins.call` |
| `code.hooks` | ชื่อ filter / event ของตัวเอง ต้องขึ้นต้นด้วย `.` |
| `requires` / `optionalRequires` | ปลั๊กอินที่ต้องมี / ใช้ร่วมได้ถ้ามี (`^1.2.0`, `~1.2`, `1.x`, `>=1.0.0 <2`) |
| `capabilities` | สิทธิ์ของปลั๊กอินที่ผู้ดูแลติ๊กต่อตำแหน่งได้ (ตั้งแต่ 2.0.6) — ดู [สิทธิ์ของปลั๊กอิน](/docs/developers/plugin-capabilities) |

## สิทธิ์ของโค้ด (scopes)

`db` · `content` · `content-write` · `content-fields` · `post-types` (ตั้งแต่ 2.0.5) · `mail` · `http` · `webhooks` · `visitor` · `routes` · `jobs` · `admin-pages` · `filters-core` · `middleware` · `head-scripts` — ความหมายของแต่ละตัวดูที่ [สิทธิ์ที่ปลั๊กอินขอ](/docs/store/plugin-permissions) ขอเท่าที่ใช้จริง เพราะผู้ดูแลเห็นทุกตัวก่อนติดตั้ง และการขอเพิ่มในเวอร์ชันถัดไปจะทำให้ปลั๊กอินถูกปิดจนกว่าจะอนุมัติใหม่

## ทุกอย่างมี namespace

| สิ่งของ | ในปลั๊กอิน `event-booking` |
| --- | --- |
| ตาราง | `schema.create('seats')` → ตารางจริง `p_event_booking_seats` (ระบบเติม/ตัด prefix ให้) |
| การตั้งค่า | `site.settings('notifyEmail')` อ่านค่าจาก ปลั๊กอิน → ตั้งค่า ก่อน แล้ว โค้ดของเว็บไซต์ → ค่าลับและการตั้งค่า (ของปลั๊กอินนี้) แล้วค่า `default` ใน manifest |
| คุกกี้ | `response.setCookie('cart', …)` → ชื่อจริงขึ้นต้นด้วย `pl__` — ปลั๊กอินไม่เห็นคุกกี้ของระบบหรือปลั๊กอินอื่น |
| action / collection | `/_a/event-booking:` · `code:event-booking:` |
| หน้าหลังบ้าน / งาน | `event-booking:` |
| ฮุกของตัวเอง | `site.emit('event-booking.booked', …)` |

ปลั๊กอินไม่ได้ `db.query` / `schema.raw` และมองไม่เห็นตารางของหน่วยอื่น

## ประเภทเนื้อหาของปลั๊กอิน (ตั้งแต่ 2.0.5)

ปลั๊กอินที่ขอ scope `post-types` (และตั้ง `&#34;minCore&#34;: &#34;2.0.5&#34;`) เรียก `site.postType` ได้เหมือน Site Code:

```ts
site.postType('docs_doc', {
  label: { th: 'เอกสาร', en: 'Docs' }, icon: '📘',
  slug: 'docs',          // ค่าเริ่มต้น = id ที่เปลี่ยน _ เป็น - (docs-doc)
  public: false,         // ระบบไม่ route /docs และ /docs/<slug> ให้ — ปลั๊กอินเสิร์ฟหน้าเอง
  fields: {
    product: { type: 'select', options: ['studio', 'store'] },
    order: 'number',
  },
});
```

- **id ของ type** ต้องเป็น `_` และยังต้องตรง `^[a-z][a-z0-9_]{1,19}$` (รวมไม่เกิน 20 ตัวอักษร) — ปลั๊กอิน `docs` → `docs_doc` ✔, `docs` เฉย ๆ ✘, ปลั๊กอิน `event-booking` → `event_booking_seat` ✔ ถ้ายาวเกินหรือ id ของปลั๊กอินขึ้นต้นด้วยตัวเลข การเปิดใช้จะล้มพร้อมข้อความแจ้ง
- **`public: false`** — ระบบไม่ทำหน้ารวม `/` และหน้า `//` ให้ (ค่าเริ่มต้น `true`) แต่ลิงก์ของโพสต์ (`post.url`, ปุ่ม &#34;ดู&#34; ในหลังบ้าน) ยังเป็น `//` ปลั๊กอินจึงควรรับพาธนั้นเอง (เช่น redirect) — `slug` ตั้งให้ตรงกับ prefix ใน `code.routes` ของปลั๊กอินเองได้ แต่ห้ามชนกับพาธของระบบ ของปลั๊กอินอื่น หรือ slug ของ type อื่น
- **ช่องข้อมูลที่ประกาศใน `fields` ของ spec** เก็บด้วยชื่อตรง ๆ (`product`, `order`) — ใช้ใน `db.posts.list({ type: 'docs_doc', where: { 'meta.order': { gte: 1 } }, orderBy: 'meta.order' })` และได้กลับเป็น `post.meta.product` ส่วน `site.fields(type, …)` ของปลั๊กอินยังเก็บแบบ `.` (กรองด้วย `where` ไม่ได้) จึงควรประกาศช่องไว้ใน spec ของ type สเปกของช่อง (รวมตัวเลือกของ select) ถูกกำหนดตอนลงทะเบียน — เปลี่ยนการตั้งค่าแล้วจะมีผลเมื่อปลั๊กอินโหลดใหม่
- อ่าน/เขียนโพสต์ของ type ด้วย `db.posts` ต้องมี scope `content` / `content-write` ตามปกติ หน่วยอื่น (Site Code, ปลั๊กอินอื่น) อ่านได้ แต่เขียนได้เฉพาะปลั๊กอินเจ้าของ
- type ได้เมนูและหน้าแก้ไขในหลังบ้าน อยู่ในตัวเลือกของรายการบทความในหน้าออกแบบ และส่งออก/นำเข้าพร้อมเว็บ — ปิดหรือลบปลั๊กอินแล้วโพสต์ยังอยู่ (ซ่อนไว้) จนกว่าจะเปิดใช้อีกครั้ง

> [!NOTE]
> Plugin Store รองรับ scope `post-types` ตั้งแต่ Store 1.2.1 — อัปโหลดปลั๊กอินที่ใช้ scope นี้ขึ้น Store ได้ตามปกติ

## Migration

```ts
// migrations/001_create_tables.ts
export default migration({
  up(schema) {
    schema.create('seats', (t) => {
      t.id();
      t.string('event_slug', 191).index();
      t.string('email', 191);
      t.timestamps();
    });
  },
  down(schema) { schema.drop('seats'); },
});
```

ต้องมี scope `db` — migration รันตอนเปิดใช้และตอนอัปเกรดปลั๊กอินที่เปิดอยู่ ถ้าเป็นการเปลี่ยนแปลงที่อาจทำให้ข้อมูลหาย ผู้ดูแลต้องติ๊กยืนยัน และระบบสำรองตารางก่อน

## แพ็กและทดสอบ

1. ตรวจ type ระหว่างเขียน: คัดลอก `anasaki.d.ts` (ดาวน์โหลดจากหน้าโค้ดของเว็บไซต์ หรือ `anasaki-code types`) มาไว้ในโฟลเดอร์
2. zip โฟลเดอร์ (ไฟล์อยู่ที่รากของ zip หรือในโฟลเดอร์บนสุดโฟลเดอร์เดียวก็ได้)
    4 
3. ในเว็บทดสอบ: **ปลั๊กอิน → อัปโหลด .zip** → อนุมัติสิทธิ์ → **เปิดใช้งาน** — ถ้าโค้ด build ไม่ผ่าน ระบบแจ้งไฟล์:บรรทัด และปลั๊กอินยังปิดอยู่
4. ดู log ของปลั๊กอินที่ **โค้ดของเว็บไซต์ → บันทึกการทำงาน** (หรือ `anasaki-code logs --unit event-booking`)
5. แก้แล้วเพิ่ม `version` และอัปโหลดใหม่ — การตั้งค่าและข้อมูลยังอยู่

> [!NOTE]
> มี Site Code ที่ใช้งานได้อยู่แล้ว? ปุ่ม **ส่งออกเป็นปลั๊กอิน** ในหน้าโค้ดของเว็บไซต์สร้าง `.zip` จากเวอร์ชันที่เผยแพร่อยู่ พร้อม `manifest.json` ที่เดา scopes, routes, exports และ requires ให้ — ตรวจแล้วแก้ก่อนส่งขึ้นร้าน

พร้อมแล้ว: [สมัครและเผยแพร่ปลั๊กอิน](/docs/store/publish-plugin) · ตัวอย่างครบทั้งตัว: [ตัวอย่างปลั๊กอิน](/docs/developers/plugin-example) · API ทั้งหมด: [Plugin API](/docs/developers/plugin-api)
