WordPress
Plugin Dev
Guide
Flow source → build → release cho team. Đủ để dev local, đóng ZIP, cài lên WordPress production.
PHP 8.x
WordPress hooks API
@wordpress/scripts
React (Admin UI)
Webpack 5
npm scripts
Node.js ≥ 18
ZIP release
Cấu trúc thư mục
Source (dev)
my-plugin.php ← file plugin chính
includes/ ← PHP runtime
class-core.php
class-admin.php
admin/
src/ ← viết code ở đây
index.js ← entry point
components/
dist/ ← output build
index.js
index.asset.php
index.css
languages/ ← i18n
node_modules/ ← .gitignore
releases/ ← .gitignore
Config files
package.json
webpack.config.js ← nếu cần custom
.gitignore
BUILD.md
readme.txt
uninstall.php
// ✓ Đúng — enqueue từ dist
plugins_url(‘admin/dist/index.js’)
// ✗ Sai — không enqueue src
plugins_url(‘admin/src/index.js’)
Workflows
Local Development
Dev local
Chạy watch mode, sửa JS/React → build tự động, F5 WP là thấy ngay.
01
Cài dependencies
Chỉ cần lần đầu. Yêu cầu Node.js ≥ 18.
npm install
02
Bật watch mode
Webpack watch: save file trong
admin/src/ → tự build ra admin/dist/. Cần F5 tay trong WP.npm run start
03
Test trên WP local
Symlink vào
wp-content/plugins/ hoặc dùng Local by Flywheel.Build & Release
Đóng ZIP, cài WP
Build production, đóng gói ZIP sạch — không cần npm trên server.
01
Build production
Webpack build với minify + tree-shaking.
npm run build
02
Đóng gói ZIP
Script copy đúng file, loại
node_modules và admin/src.npm run package
# → releases/plugin-v1.0.0.zip
# → releases/plugin-v1.0.0.zip
03
Verify SHA256
sha256sum releases/plugin-v1.0.0.zip
✓
Upload lên WordPress
Admin → Plugins → Add New → Upload. Activate. Không cần npm trên server.
npm scripts — cheat sheet
npm run start
Watch mode — dev hằng ngày
webpack –watch –mode development
npm run build
Production build — trước khi release
webpack –mode production + minify
npm run package
Đóng ZIP sạch vào releases/
exclude src/ node_modules/ .git/
npm run lint:js
Lint JS theo chuẩn WP
wp-scripts lint-js
npm run format
Format code tự động
wp-scripts format (prettier)
npm run release
Lint → build → package
check + build + package in 1 cmd
ZIP release — trong và ngoài
✓ Có trong ZIP
my-plugin.phpfile plugin chính
includes/PHP runtime toàn bộ
admin/dist/JS/CSS đã build sẵn
languages/i18n nếu có
readme.txtWP.org format
uninstall.phpcleanup khi xoá plugin
✗ Không có trong ZIP
node_modules/deps dev only
admin/src/source, không chạy
.git/metadata repo
package.json / webpack.config.jsconfig build
*.test.js / debug-*.phpfile test nội bộ
.env / .DS_Storefile local machine
Quy tắc quan trọng
Làm đúng
Enqueue từ
admin/dist/Đọc
index.asset.php lấy deps + versionDùng
wp_localize_script() pass data PHP → JSChạy
npm run build trước npm run packageConditional load — chỉ enqueue đúng page cần
Prefix tất cả:
dps_, DPS_Đừng làm
Enqueue từ
admin/src/Hardcode version hash trong PHP
Để
node_modules/ trong ZIPnpm install trên production server
Chạy DB query nặng ở
init hookecho $_POST['x'] không sanitize/escapeChecklist production-ready
Build & Release
✓
npm run build không lỗi → admin/dist/✓
ZIP cài được, Activate không lỗi — không cần npm server
✓
ZIP không chứa
node_modules/ hay src/✓
Báo lại: danh sách file + ZIP path + SHA256
Security
✓
Mọi file PHP có
if (!defined('ABSPATH')) exit;✓
Mọi AJAX/form: nonce verify +
current_user_can()✓
Input sanitized, output escaped
Performance
✓
Asset load conditional — không load toàn site
✓
Script:
in_footer: true + strategy: defer✓
Không query DB nặng ở
init hookStandards
✓
Mọi function/class/option có prefix
dps_✓
Plugin header:
Requires at least, Requires PHP✓
Tất cả string dùng i18n,
uninstall.php cleanup sạch✓
BUILD.md đầy đủ: install, build, package, test
