WordPress
Plugin Dev
Guide
Source → build → release flow for teams. Sufficient for local dev, ZIP packaging, and WordPress production installation.
PHP 8.x
WordPress hooks API
@wordpress/scripts
React (Admin UI)
Webpack 5
npm scripts
Node.js ≥ 18
ZIP release
Directory structure
Source (dev)
my-plugin.php ← main plugin file
includes/ ← PHP runtime
class-core.php
class-admin.php
admin/
src/ ← write code here
index.js ← entry point
components/
dist/ ← build output
index.js
index.asset.php
index.css
languages/ ← i18n
node_modules/ ← .gitignore
releases/ ← .gitignore
Config files
package.json
webpack.config.js ← if custom is needed
.gitignore
BUILD.md
readme.txt
uninstall.php
// ✓ Correct — enqueue from dist
plugins_url(‘admin/dist/index.js’)
// ✗ Incorrect — do not enqueue src
plugins_url(‘admin/src/index.js’)
Workflows
Local Development
Local dev
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
Zip, install 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 and 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 to WordPress
Admin → Plugins → Add New → Upload. Activate. Không cần npm trên server.
npm scripts — cheat sheet
npm run start
Watch mode — daily dev
webpack –watch –mode development
npm run build
Production build — before release
webpack –mode production + minify
npm run package
Zip clean into releases/
exclude src/ node_modules/ .git/
npm run lint:js
Lint JS according to WP standards
wp-scripts lint-js
npm run format
Auto code formatting
wp-scripts format (prettier)
npm run release
Lint → build → package
check + build + package in 1 cmd
ZIP release — inside and out
✓ Included in ZIP
my-plugin.phpmain plugin file
includes/Full PHP runtime
admin/dist/Pre-built JS/CSS
languages/i18n if applicable
readme.txtWP.org format
uninstall.phpcleanup on plugin deletion
✗ Not included in ZIP
node_modules/deps dev only
admin/src/source, không chạy
.git/repo metadata
package.json / webpack.config.jsconfig build
.test.js / debug-.phpinternal test files
.env / .DS_Storelocal machine files
Important rules
Do it right
Enqueue from
admin/dist/Read
index.asset.php lấy deps + versionUse
wp_localize_script() pass data PHP → JSRun
npm run build before npm run packageConditional load — chỉ enqueue đúng page cần
Prefix tất cả:
dps_, DPS_Don't do
Enqueue from
admin/src/Hardcode version hash in PHP
To
node_modules/ trong ZIPnpm install on 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 does not contain
node_modules/ or 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
