Configuration โปรเจกต์แบบ Self-Contained: รัน Maven / Node / Java บน Windows โดยไม่พึ่ง PATH

บทนำ

“เมื่อสมาชิกใหม่เข้าร่วม ขั้นตอนแรกคือการ align versions ของ Java, Node.js และ Maven เสมอ”

แม้ในการพัฒนาคนเดียว ปัญหาเดียวกันก็เกิดขึ้นเมื่อเปลี่ยน PC หรือ reset environment

โปรเจกต์นี้ใช้ configuration ที่จำกัด Maven, Node และ npm ไว้ในโฟลเดอร์โปรเจกต์
โดยไม่พึ่งพา system PATH

---

ภาพรวม Configuration

dvd-rental-admin/
  mvnw          ← Maven Wrapper (สำหรับ macOS/Linux)
  mvnw.cmd      ← Maven Wrapper (สำหรับ Windows)
  node/
    npm         ← npm (สำหรับ macOS/Linux)
    npm.cmd     ← npm (สำหรับ Windows)
    npx
    npx.cmd
  package.json  ← npm configuration สำหรับ frontend build

เมื่อ run build commands เราใช้ commands ภายในโปรเจกต์แทนที่จะใช้ Maven และ Node ที่ติดตั้งบน system

---

Maven Wrapper

mvnw / mvnw.cmd คือ Maven Wrapper
เมื่อ execute จะ download และรัน version ของ Maven ที่ระบุใน .mvn/wrapper/maven-wrapper.properties โดยอัตโนมัติ

# .mvn/wrapper/maven-wrapper.properties
distributionUrl=https://repo.maven.apache.org/maven2/org/apache/maven/apache-maven/3.9.6/apache-maven-3.9.6-bin.zip

การใช้งาน

# ใช้ version ที่ระบุในโปรเจกต์ ไม่ใช่ system Maven
.\mvnw.cmd clean package

# Build ได้แม้ไม่มี mvn command ติดตั้งบน system

วิธีสร้าง

# Generate wrapper ในสภาพแวดล้อมที่มี Maven อยู่แล้ว
mvn wrapper:wrapper -Dmaven=3.9.6

---

การจำกัด Node / npm ไว้ภายในโปรเจกต์

ติดตั้ง Node ภายในโปรเจกต์ผ่าน npm install

การวาง Node.js binaries ในโฟลเดอร์ node ทำให้แยกออกจาก system Node

// package.json
{
  "engines": {
    "node": ">=22.0.0"
  },
  "scripts": {
    "build:css": "node/npm.cmd run tailwind",
    "build:ts": "node/npx.cmd tsc"
  }
}

หรือใช้ frontend-maven-plugin:

<!-- pom.xml -->
<plugin>
    <groupId>com.github.eirslett</groupId>
    <artifactId>frontend-maven-plugin</artifactId>
    <version>1.15.0</version>
    <configuration>
        <installDirectory>node</installDirectory>  <!-- วางใน node/ ของโปรเจกต์ -->
        <nodeVersion>v22.0.0</nodeVersion>
    </configuration>
    <executions>
        <execution>
            <id>install-node-and-npm</id>
            <goals><goal>install-node-and-npm</goal></goals>
        </execution>
    </executions>
</plugin>

การรัน mvn generate-resources จะติดตั้ง Node.js ลงในโฟลเดอร์ node/

---

หมายเหตุเกี่ยวกับการ Resolve Path ใน Windows

Extension .cmd สำคัญมากใน Windows

# NG: ไม่มี extension อาจไม่ทำงานใน Windows PowerShell
.\mvnw clean package

# OK: ระบุ .cmd อย่างชัดเจน
.\mvnw.cmd clean package
.\node\npm.cmd run build

ยังไง ถ้า working directory ไม่ใช่ project root .\mvnw.cmd จะ fail

# NG: เมื่ออยู่ใน subdirectory
cd infra/cdk
.\mvnw.cmd package  # ← Error: ไม่พบ mvnw.cmd

# OK: กลับไปยัง project root ก่อน execute
cd C:\Users\y_104\git\dvd-rental-admin
.\mvnw.cmd package

# หรือ execute ด้วย absolute path
C:\Users\y_104\git\dvd-rental-admin\mvnw.cmd package

---

การตั้งค่า VS Code Task

การกำหนดใน .vscode/tasks.json ของ VS Code ทำให้ build ได้โดยไม่ต้องเปิด terminal

{
  "version": "2.0.0",
  "tasks": [
    {
      "label": "build-backend",
      "type": "shell",
      "command": ".\\mvnw.cmd",
      "args": ["-DskipTests", "package"],
      "options": {
        "cwd": "${workspaceFolder}"  // ← ระบุ workspaceFolder อย่างชัดเจน
      },
      "group": "build"
    },
    {
      "label": "build-frontend",
      "type": "shell",
      "command": ".\\node\\npm.cmd",
      "args": ["run", "build"],
      "options": {
        "cwd": "${workspaceFolder}"
      },
      "group": "build"
    }
  ]
}

---

การตั้งค่า .gitignore

เราไม่ commit Node และ Maven caches ภายในโปรเจกต์

# Maven Wrapper download cache
.mvn/wrapper/maven-wrapper.jar  # Exclude JAR (Wrapper auto-downloads it)

# Node binaries (downloaded by frontend-maven-plugin)
node/node_modules/
node/node.exe
node/npm
node/npm.cmd
node/npx
node/npx.cmd

# แต่ track โฟลเดอร์ node/ เอง (เป็น empty directory)

---

การ Rollout ให้ทีม (Onboarding)

ด้วย configuration นี้ การ setup ในสภาพแวดล้อมใหม่ลดเหลือเพียง commands เหล่านี้:

# 1. Clone repository
git clone https://github.com/your-org/dvd-rental-admin.git
cd dvd-rental-admin

# 2. ติดตั้ง Node (frontend-maven-plugin auto-downloads)
.\mvnw.cmd generate-resources

# 3. Frontend build
.\node\npm.cmd install
.\node\npm.cmd run build

# 4. Backend build และ startup
.\mvnw.cmd spring-boot:run

การระบุ Java version จัดการด้วย .sdkmanrc (เมื่อใช้ SDKMAN) หรือ .java-version (เมื่อใช้ jenv)

---

สรุป

ปัญหา	วิธีแก้ไข
System Maven version ไม่ตรง	ใช้ mvnw / mvnw.cmd
System Node/npm ไม่พร้อมใช้หรือ version ไม่ตรง	ใช้ frontend-maven-plugin download ไว้ในโปรเจกต์
.\mvnw.cmd ไม่ทำงานบน Windows	Set working directory เป็น project root
การ setup environment ซับซ้อนสำหรับสมาชิกใหม่	Self-contained configuration ลดขั้นตอน clone-to-build ให้น้อยที่สุด

การบรรลุสถานะ “ทุกอย่างที่จำเป็นในการ build โปรเจกต์นี้อยู่ในโฟลเดอร์นี้”
ช่วยลดปัญหาจากความแตกต่างของ environment ได้อย่างมาก

---

แผนที่บทความของ Series นี้

→ การสร้างแอพ DVD Rental สำหรับผู้ใช้ควบคู่กับหน้าจัดการ — ภาพรวมโครงสร้าง Vue 3 + Spring Boot