Development Setup

​

Prerequisites

​

Required Software

• PHP >= 7.2 - Required for WordPress compatibility
• Node.js >= 18.0 - For building JavaScript and CSS assets
• Composer >= 2.0 - For PHP dependency management
• Docker - For running the WordPress test environment
• Git - For version control

​

Verify Installation

php --version
node --version
npm --version
composer --version
docker --version

​

Installation

​

1. Clone the Repository

git clone https://github.com/nk-crew/visual-portfolio.git
cd visual-portfolio

​

2. Install Dependencies

# Install Node.js dependencies
npm install

# Composer dependencies are installed automatically via postinstall hook
# Or manually run:
composer install

• Install all npm packages
• Set up Husky git hooks
• Automatically run composer install

​

3. Configure Git Hooks

• PHP CodeSniffer (WPCS)
• ESLint (JavaScript)
• Stylelint (SCSS)

• Additional lint checks
• Ensure code quality before pushing

​

Development Commands

​

Build Commands

​

Start Development Mode

npm run dev

• Watches for file changes
• Automatically rebuilds assets
• Enables hot module replacement
• Shows detailed progress
• Generates source maps for debugging

​

Build for Development

npm run build

​

Build for Production

npm run build:prod

• Generates translation files (.pot and .json)
• Builds minified production assets
• Creates a plugin zip file
• Should only be run for releases

​

Code Quality

​

Linting

# Check all JavaScript and CSS
npm run lint

# Check JavaScript only
npm run lint:js

# Check CSS/SCSS only
npm run lint:css

# Check PHP code (requires wp-env to be running)
npm run lint:php

​

Auto-Fixing

# Fix JavaScript issues
npm run format:js

# Fix CSS/SCSS issues
npm run format:css

# Fix PHP issues (requires wp-env to be running)
npm run format:php

​

Testing

​

WordPress Test Environment

# Start the WordPress environment
npm run env:start

# Stop the environment
npm run env:stop

# Destroy the environment (clean slate)
npm run env:destroy

• WordPress site: http://localhost:8888
• Admin: http://localhost:8888/wp-admin
• Username: admin
• Password: password

​

Running Tests

# Run all tests (lint + unit + e2e)
npm run test

# Run PHP unit tests only
npm run test:unit:php

# Run E2E tests (Playwright)
npm run test:e2e

# Run E2E tests in UI mode
npm run test:e2e:ui

npm run env:start
npm run test:unit:php

​

Development Workflow

​

Typical Development Session

1. Start development build:
   npm run dev
   
2. Start WordPress environment (in another terminal):
   npm run env:start
   
3. Make your changes to PHP, JavaScript, or SCSS files
4. Test your changes in the browser at http://localhost:8888
5. Run linters before committing:
   npm run lint:js
   npm run lint:css
   npm run lint:php
   
6. Commit your changes (hooks will run automatically):
   git add .
   git commit -m "Your commit message"
   

​

Working with PHP

1. Edit the file in classes/ or main plugin file
2. Always run PHP linter after changes:
   npm run lint:php
   
3. Fix any issues reported by WPCS:
   npm run format:php
   
4. Refresh the WordPress site to see changes

​

Working with JavaScript

1. Edit the file with ES6+ syntax
2. Webpack auto-rebuilds (if npm run dev is running)
3. Check browser console for errors
4. Run linter:
   npm run lint:js
   
5. Auto-fix issues:
   npm run format:js
   

​

Working with SCSS

1. Edit the .scss file
2. Webpack auto-rebuilds CSS (if npm run dev is running)
3. Check browser for style changes
4. Run linter:
   npm run lint:css
   
5. Auto-fix issues:
   npm run format:css
   

​

Working with Gutenberg Blocks

1. Edit React component files
2. Webpack auto-rebuilds (if npm run dev is running)
3. Refresh the block editor to see changes
4. Check browser console for React errors
5. Test in block editor at http://localhost:8888/wp-admin/post-new.php

​

Build Output

build/
├── admin.css              # Admin styles
├── admin.css.map          # Source map for debugging
├── gutenberg.js           # Gutenberg block editor
├── gutenberg.js.map       # Source map
├── style.css              # Frontend styles
├── style-rtl.css          # RTL version (auto-generated)
└── ...                    # Additional compiled assets

• assets/ for CSS and JavaScript
• gutenberg/ for React components
• classes/ for PHP

​

Debugging

​

Enable WordPress Debug Mode

npm run wp-env run cli wp config set WP_DEBUG true --raw
npm run wp-env run cli wp config set WP_DEBUG_LOG true --raw
npm run wp-env run cli wp config set WP_DEBUG_DISPLAY true --raw

​

Source Maps

• JavaScript: build/*.js.map
• CSS: build/*.css.map

​

PHP Debugging

error_log( print_r( $variable, true ) );

npm run wp-env run cli tail -f /var/www/html/wp-content/debug.log

​

Troubleshooting

​

Port Already in Use

npm run env:stop
# Or kill the process using the port
lsof -ti:8888 | xargs kill -9

​

Node Modules Issues

rm -rf node_modules package-lock.json
npm install

​

Composer Issues

rm -rf vendors composer.lock
composer install

​

wp-env Issues

npm run env:destroy
npm run env:start

​

Build Issues

rm -rf .cache build
npm run build

​

IDE Configuration

​

VS Code

• ESLint integration
• Stylelint integration
• PHP formatting
• Recommended extensions

​

PHP IntelliSense

composer require --dev php-stubs/wordpress-stubs

​

Next Steps

• Architecture Deep Dive - Learn about the plugin’s class structure
• Contributing Guidelines - Learn how to contribute