N

Nokfa Docs

framework-next.js
project
style
tool-git

Current: framework-next.js

สารบัญ

ไม่มีชื่อบทความ

เอกสารแนวปฏิบัติในการทำโปรเจ็กต์พัฒนาเว็บไซต์ของบริษัท นกฟ้า จำกัด

1. วัตถุประสงค์

เพื่อให้ทุกคนในทีมเข้าใจโครงสร้างโปรเจ็กต์และกระบวนการทำงานไปในทิศทางเดียวกัน ลดความสับสนหรือความไม่แน่นอนในการจัดการไฟล์และการโค้ด รวมถึงกำหนดมาตรฐานในการเขียนโค้ด การวางไฟล์ และการดูแลคอนเทนต์ให้เป็นระบบ

2. ภาพรวมโครงสร้างโปรเจ็กต์

my-project/
│
├── app/
│   ├── _content/       # ไฟล์คอนเทนต์ที่ Content Creator เป็นผู้ดูแล
│   └── [โฟลเดอร์ / ไฟล์อื่น ๆ ที่เกี่ยวกับโค้ดหลักของแอปพลิเคชัน]
│
├── assets/             # ไฟล์ที่ไม่ต้องการให้ build ติดไปด้วย เช่น raw data, mock data, ฯลฯ
│   └── [รูปภาพ / ไฟล์ต่าง ๆ ที่ไม่ต้องใช้ใน production โดยตรง]
│
├── public/             # ไฟล์ที่ต้องการเปิดให้เข้าถึงแบบสาธารณะ เช่น รูปภาพ ไอคอน favicon
│
├── styles/             # เก็บไฟล์ CSS ทั่วไป (ถ้าไม่เก็บไว้ใน app หรือถ้าแยก styles ออกมาใช้)
│
├── .env.local          # ไฟล์ environment สำหรับ development (ไม่ commit ลง Git)
├── .env.production     # ไฟล์ environment สำหรับ production
│
├── package.json
├── tsconfig.json       # หรือ jsconfig.json หากใช้ JavaScript
└── ... (ไฟล์อื่น ๆ)

หมายเหตุ: โครงสร้างอาจปรับตามความเหมาะสมของทีม หรือรูปแบบโปรเจ็กต์ (เช่น ถ้าเป็น Next.js 13+ หรือใช้ App Router/Pages Router ก็อาจจัดโฟลเดอร์ต่างออกไปได้)

3. รายละเอียดและข้อกำหนดของแต่ละโฟลเดอร์

3.1 app/

  • โครงสร้างหลักของตัวแอป: เป็นส่วนของโค้ดที่เป็น Business Logic หรือ UI หลัก (เช่น page, layout, component)
  • โฟลเดอร์ _content/:
    • เก็บไฟล์คอนเทนต์ (เช่น Markdown, JSON, หรือไฟล์อื่น ๆ ที่ Content Creator จัดการ)
    • ข้อปฏิบัติ:
      • Dev ไม่ควรแก้ไขไฟล์ใน _content/ โดยตรง ยกเว้นกรณีจำเป็น หรือมีการตกลงร่วมกัน
      • เนื้อหาใด ๆ ที่ต้องการดึงมาใช้ในหน้าต่าง ๆ ควรโหลดผ่าน service หรือ API ของโปรเจ็กต์ เพื่อให้แยกบทบาท Content Creator และ Dev ออกจากกันชัดเจน

3.2 assets/

  • เก็บข้อมูลที่ ไม่ต้องการให้ build ติดไปด้วย เช่น
    • ไฟล์ raw data, mock data, ไฟล์ PDF หรืองานต้นฉบับใด ๆ ที่ใช้เฉพาะในกระบวนการภายใน
    • ไฟล์รูปภาพขนาดใหญ่ที่ยังไม่ถูก optimize หรือไฟล์ที่รอตกลงว่าจะใช้หรือไม่
  • แนวทางปฏิบัติ:
    • หากข้อมูลไม่ได้ใช้ใน Production หรือเป็นเพียงข้อมูลเพื่อ Reference ควรเก็บใน assets/
    • หากต้องการใช้งานไฟล์บางส่วนใน Production ให้ทำขั้นตอนการ Optimizing (ถ้าจำเป็น) แล้วค่อยย้ายไป public/ หรือใส่ในโค้ดที่เป็น Static Import

3.3 public/

  • เก็บไฟล์ที่พร้อมให้ผู้ใช้งาน (client) เข้าถึงได้โดยตรง เช่น ไอคอน favicon, รูปภาพทั่วไป, เอกสาร PDF ที่ต้องให้ผู้ใช้ดาวน์โหลด
  • การอ้างอิงไฟล์ใน public/ สามารถเรียกได้ผ่าน path ตรง ๆ เช่น /myimage.png

3.4 styles/

  • เก็บไฟล์ CSS/SCSS (ในกรณีที่แยกไฟล์ออกจาก _app.js หรือ globals.css)
  • สำหรับโปรเจ็กต์ที่ใช้ Next.js 13+ บางทีมอาจชอบเก็บสไตล์ไว้ในโฟลเดอร์ app/ บางทีมอาจแยกเป็น styles/ เพื่อความเป็นระเบียบ

    ข้อแนะนำ: ควรกำหนดรูปแบบไว้ชัดเจนในทีม เพื่อให้คนอื่นเข้ามาดูแล้วเข้าใจตำแหน่งไฟล์ได้ทันที

3.5 การใช้งาน font (ตัวอย่างสำหรับ Next.js)

  • ใช้ next/font/google ในการ import ฟอนต์ จากนั้นสร้างตัวแปรก่อนจะนำไปใส่ใน globals.css 
    // Example: fonts.js
import { Inter, Roboto } from 'next/font/google';

export const inter = Inter({
  subsets: ['latin'],
  weight: ['400', '700'],
});

export const roboto = Roboto({
  subsets: ['latin'],
  weight: ['400', '700'],
});

    /* globals.css */
:root {
  --font-inter: /* ใส่ค่าที่ได้จาก inter */;
  --font-roboto: /* ใส่ค่าที่ได้จาก roboto */;
}

body {
  font-family: var(--font-inter), sans-serif;
}
  • ข้อปฏิบัติ:
    • ให้ทุกคนใช้วิธี import ฟอนต์ในรูปแบบเดียวกัน เพื่อความสม่ำเสมอ
    • หากต้องการเปลี่ยนฟอนต์ หรือเพิ่มฟอนต์ใหม่ ให้แก้ไขในไฟล์รวม (เช่น fonts.js หรือ fonts.ts) ที่ตกลงกันในทีม

4. มาตรฐานการเขียนโค้ด (Code Standard)

  1. Naming Convention
    • ใช้ camelCase สำหรับตัวแปรและฟังก์ชัน
    • ใช้ PascalCase สำหรับชื่อ Component React (เช่น MyComponent.js)
    • ใช้ kebab-case สำหรับชื่อไฟล์ทั่วไป (เช่น my-component.js) หากเป็นไฟล์ CSS หรือ SCSS
  2. การย่อหน้าและรูปแบบ (Formatting)
    • กำหนดการตั้งค่า .editorconfig หรือใช้ ESLint, Prettier เพื่อตั้งค่าอัตโนมัติ (เช่น 2 spaces หรือ 4 spaces ตามทีมตกลง)
  3. Comment
    • ควรเขียน Comment เฉพาะที่จำเป็น ช่วยอธิบาย Block code ที่ซับซ้อน
  4. การใช้ ESLint / Prettier
    • ติดตั้ง ESLint และ Prettier เป็น Dev Dependencies
    • ผูก script ใน package.json เช่น "lint": "eslint . --ext .js,.jsx,.ts,.tsx", "format": "prettier --write ."
    • ควรรันก่อน commit โค้ด เพื่อให้โค้ดสะอาดและเป็นระเบียบ

5. การควบคุมเวอร์ชัน (Version Control)

  1. การตั้งชื่อ Branch
    • ชื่อสาขา (branch) ควรสื่อความหมาย เช่น feature/login-page, fix/bug-123, hotfix/user-not-found
  2. Pull Request (PR) Guidelines
    • ทุกครั้งที่จะ merge เข้า main หรือ develop ควรสร้าง PR
    • ตรวจสอบ ESLint, Prettier, และรันเทส (ถ้ามี) ก่อนขอให้รีวิว
    • ใส่รายละเอียดการแก้ไขใน PR เพื่อให้ผู้รีวิวเข้าใจบริบท
  3. Commit Message
    • ใช้รูปแบบที่สอดคล้องกัน เช่น [TYPE] Short description
      • ตัวอย่าง TYPE: feat, fix, chore, docs, ฯลฯ
    • อธิบายใน commit message ว่าได้แก้ไขหรือเพิ่มอะไร
    • หากแก้ไขบั๊กหรือฟีเจอร์ที่มีเลข Issue ให้ระบุเลขอ้างอิงด้วย (เช่น fix: แก้บั๊กหน้าล็อกอิน (#123))

6. การจัดการ Environment Variables

  1. แยกไฟล์ .env.local สำหรับ Development, .env.production สำหรับ Production (หรือใช้ .env.staging เพิ่มเติมตามต้องการ)
  2. อย่า commit ไฟล์ .env.local หรือไฟล์ที่มีข้อมูลลับขึ้น Git (จัดการด้วย .gitignore)
  3. ควรกำหนดตัวแปรสำคัญ เช่น API_KEY, DB_CONNECTION_STRING, SECRET_KEY ให้ชัดเจน และแจ้งวิธีตั้งค่าใน README

7. การ Build และ Deploy

  1. Pre-build
    • ตรวจสอบให้แน่ใจว่าไม่มีไฟล์เกินจำเป็นติดไปใน Production (กรณี Next.js ก็จะ ignore โฟลเดอร์บางส่วนอัตโนมัติ เช่น assets/ หากตั้งค่าไม่ให้ import ออกมา)
  2. การทดสอบ (Testing)
    • หากโปรเจ็กต์มี test suite (เช่น Jest, Cypress) ควรตั้ง script ให้ชัดเจน (npm run test, npm run e2e เป็นต้น) และรันก่อน deploy
  3. CI/CD Pipeline
    • หากใช้เครื่องมือ CI/CD เช่น GitHub Actions, GitLab CI, Jenkins ฯลฯ กำหนดขั้นตอนการ build, run test, deploy ให้ชัดเจน
  4. ตรวจสอบหลัง Deploy
    • ตรวจสอบว่าไฟล์ที่ไม่ควรออกสู่ Production ไม่ได้ถูก deploy ขึ้นไป
    • ทดสอบ function หลัก ๆ, route ต่าง ๆ, การแสดงผลบนหน้าจอ, และการเรียกใช้ API

8. การดูแล Content โดย Content Creator

  • ในกรณีที่มีการแก้ไข/อัปเดตคอนเทนต์ที่ _content/, ควรมีวิธีเวิร์กโฟลว์ที่ชัดเจน เช่น
    1. Content Creator อัปเดตไฟล์ใน _content/
    2. สร้าง PR (ถ้า Content Creator ใช้ Git เป็น) หรือส่งไฟล์ให้ Dev merge เข้าโปรเจ็กต์
    3. Dev ตรวจสอบความถูกต้องเบื้องต้น (Syntax, อักขระพิเศษ)
    4. Merge และ Deploy
  • ควรมีวิธีแจ้งผู้เกี่ยวข้อง หากมีการเปลี่ยนเนื้อหาที่กระทบกับฟีเจอร์ หรือโครงสร้างโค้ด

9. แนวทางเพิ่มเติมเพื่อปรับปรุงการทำงานร่วมกันในทีม

  1. การสื่อสารในทีม
    • กำหนดช่องทางหลัก เช่น Slack, Microsoft Teams, หรือ Trello สำหรับติดตามงาน
    • ตั้ง Scrum Meeting หรือ Stand-up Meeting สั้น ๆ เป็นประจำ เพื่ออัปเดตสถานะและปัญหาที่เกิดขึ้น
  2. การรีวิวโค้ด (Code Review)
    • ตั้งกฎว่าทุก PR ต้องมีผู้รีวิวอย่างน้อย 1-2 คนก่อนจะ merge
    • เน้นการรีวิวเพื่อปรับปรุงคุณภาพโค้ด ไม่เพียงแต่ตรวจหาบั๊ก ควรแนะนำวิธี refactor หรือปรับปรุงโค้ดให้ดีขึ้นได้
  3. Documentation
    • จัดทำ README อย่างละเอียดหรือใช้ Wiki เพื่อบันทึกขั้นตอนการเซ็ตอัปโปรเจ็กต์ การ build หรือการ deploy
    • อัปเดตเอกสารทันทีเมื่อมีการเปลี่ยนแปลงใหญ่ ๆ
  4. Performance & Security
    • ตรวจสอบเสมอว่ามีการใช้เครื่องมือใด ๆ ในการ optimize หรือป้องกันช่องโหว่ (เช่นการใช้ Helmet, CSP header, Rate limit ใน server side)
    • อย่าลืมอัปเดต dependencies อย่างสม่ำเสมอ เพื่อปิดช่องโหว่ด้านความปลอดภัย

10. สรุป

  • แนวปฏิบัตินี้เป็น “รากฐาน” ในการร่วมงานกันของทีมพัฒนาเว็บของบริษัท นกฟ้า จำกัด
  • หากมีความจำเป็นต้องแก้ไข ปรับปรุง หรือเพิ่มเติมข้อกำหนด สามารถนำเข้าที่ประชุมทีมเพื่อปรับปรุงให้สอดคล้องกับสถานการณ์จริงได้
  • การรักษามาตรฐานโค้ด โครงสร้าง และการสื่อสารอย่างชัดเจนจะช่วยให้โปรเจ็กต์เสถียร บำรุงรักษาง่าย และส่งมอบงานได้ตามกำหนด

ท้ายสุด อย่าลืมอัปเดตเอกสารนี้เมื่อต้องมีการเปลี่ยนแปลงโครงสร้างหรือขั้นตอนสำคัญ เพื่อให้แน่ใจว่าทีมมี “Single Source of Truth” ในการดำเนินงานร่วมกันเสมอ

“เราทำงานเป็นทีม โค้ดและคอนเทนต์ที่ดี ย่อมเกิดจากการสื่อสารและมาตรฐานร่วมกัน”