npm package: @fc.developer/fc-component-react
Description: Reusable React components using DevExtreme 24.2
Latest version: 1.2.19

# 🚀 NPM Auto-Deploy Guide (ผ่าน GitHub Actions)

## 📦 Overview
โปรเจกต์นี้ถูกตั้งค่าให้ **Deploy (Publish)** ขึ้น [npmjs.com](https://www.npmjs.com/) **อัตโนมัติ**
ทุกครั้งที่มีการ **สร้าง Release ใหม่บน GitHub**

> 🔄 ระบบจะ Build → (อัปเดตเวอร์ชันอัตโนมัติให้ตรงกับ tag) → ตรวจสอบ → และ Publish ขึ้น npm

---

## ⚙️ Workflow File
> `.github/workflows/publish.yml` (Auto-sync package.json จาก Tag)

```yaml
name: Publish to npm on Release

on:
  release:
    types: [published]
  push:
    tags:
      - '[0-9]+.[0-9]+.[0-9]+'
  workflow_dispatch: {}

jobs:
  publish:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      id-token: write

    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Use Node.js 18
        uses: actions/setup-node@v4
        with:
          node-version: 18
          registry-url: 'https://registry.npmjs.org'

      - name: Install dependencies
        run: npm ci

      - name: Sync package.json version with release tag
        run: |
          TAG="${GITHUB_REF##*/}"
          if [[ "$TAG" == v* ]]; then
            echo "❌ Tag must NOT start with 'v' (got: $TAG)."
            exit 1
          fi
          echo "🔄 Updating package.json version to $TAG"
          npm version "$TAG" --no-git-tag-version

      - name: Build library
        run: npm run build --if-present

      - name: Verify version matches tag
        run: |
          TAG="${GITHUB_REF##*/}"
          PKG_VERSION=$(node -p "require('./package.json').version")
          if [ "$TAG" != "$PKG_VERSION" ]; then
            echo "❌ After sync, Tag ($TAG) != package.json version ($PKG_VERSION)"
            exit 1
          fi
          echo "✅ OK: $TAG == package.json.version"

      - name: Publish to npm
        env:
          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
        run: npm publish --access public
```

---

## 🧾 ขั้นตอน Deploy (อัตโนมัติ)

### 🆕 0) Auto-sync version จาก Release Tag
Workflow จะอ่าน tag (เช่น `1.2.16`) แล้วรัน:
```bash
npm version 1.2.16 --no-git-tag-version
```
เพื่ออัปเดต `"version"` ใน `package.json` อัตโนมัติ

> ✅ เงื่อนไข: Tag ต้อง **ไม่มี `v`** เช่น `1.2.16`

### 1) สร้าง Release (แนะนำ GitFlow)
- `dev` → **Start Release** (เช่น `1.2.16`)
- ทำงาน/ทดสอบ → **Finish Release** (merge เข้า `main` + tag `1.2.16`)
- Workflow จะ trigger และ publish ให้เอง

> ใช้ GitHub UI ก็ได้: **Releases → Draft a new release** (Tag = `1.2.16`) → Publish

### 2) ตรวจ Actions
- GitHub → **Actions** → `Publish to npm on Release` → ต้องผ่านถึง “Publish to npm”

### 3) ตรวจ npm
```bash
npm info @fc.developer/fc-component-react version
```

---

## ⚙️ ขั้นตอนการพัฒนา (Development Setup)

### ติดตั้ง dependencies
```bash
npm install
```

### ติดตั้ง dev dependencies
```bash
npm install -D
```
> สำหรับ vite/eslint/jest/rollup ฯลฯ

### เริ่ม Dev Server / Playground
```bash
npm run dev
```

---

## 🚀 Manual Publish (ทำเองด้วยคำสั่ง)

1) Build
```bash
npm run build
```

2) (ตัวเลือก) ทดสอบแพ็คเกจ
```bash
npm pack
# จะได้ไฟล์ .tgz เพื่อลองติดตั้งในโปรเจกต์อื่น:
# npm install ../fc-component-react-1.2.16.tgz
```

3) Login npm (ครั้งแรกเท่านั้น)
```bash
npm login
```

4) Publish
```bash
npm publish --access public
```

---

## 🔑 ตั้งค่า NPM Token (สำหรับ GitHub Actions)
- สร้าง **Granular Access Token → Type: Automation → Read & Write (All packages)** บน npm
- เพิ่มไปที่ GitHub → **Repo → Settings → Secrets → Actions → `NPM_TOKEN`**

---

## ⚠️ หมายเหตุสำคัญ
- Tag ต้องเป็นแบบ **ไม่ใส่ `v`** เช่น `1.2.16`
- Repo แบบ private: **อย่าใช้ `--provenance`**
- 🧩 **แก้ไฟล์ `publish.yml` ใน `main` แล้ว merge เข้า `dev` เสมอ**
- หลัง release แนะนำให้ **merge `main → dev`** เพื่อ sync

---

## 🧩 ปัญหาที่พบบ่อย
| อาการ | สาเหตุ | วิธีแก้ |
|---|---|---|
| ❌ provenance error | ใช้ `--provenance` กับ repo private | เอา flag ออกใน publish.yml |
| ❌ Workflow ไม่รัน | tag ไม่ได้ push / workflow ไม่อยู่ใน main | ตรวจว่าไฟล์อยู่ `main` และมี trigger `release`/`push: tags` |
| 🔒 Auth error | token ผิด/หมดอายุ | สร้าง Automation token ใหม่บน npm แล้วอัปเดต `NPM_TOKEN` |
| 🕓 Publish ช้า | npm ยัง sync | รอ 1–2 นาทีแล้วรัน `npm info <package>` |