Development Setup - Visual Portfolio

This guide will walk you through setting up a local development environment for contributing to or extending the Visual Portfolio plugin.

Prerequisites

Before you begin, ensure you have the following installed on your system:

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

Check your versions:

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 both npm and Composer dependencies:

# Install Node.js dependencies
npm install

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

The npm install command will:

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

3. Configure Git Hooks

Git hooks are automatically configured via Husky during npm install. These hooks run: Pre-commit:

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

Pre-push:

Additional lint checks
Ensure code quality before pushing

Development Commands

Build Commands

Start Development Mode

Run webpack in watch mode with hot module replacement:

npm run dev

This command:

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

Build for Development

Create a one-time development build:

npm run build

This generates unminified assets with source maps in the build/ directory.

Build for Production

npm run build:prod

⚠️ Warning: This command:

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

Do not run build:prod during regular development.

Code Quality

Linting

Check code quality without making changes:

# 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

Automatically fix linting issues:

# 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

Visual Portfolio uses wp-env (WordPress’s official testing environment powered by Docker):

# Start the WordPress environment
npm run env:start

# Stop the environment
npm run env:stop

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

After starting the environment:

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

Note: Ensure wp-env is running before executing tests:

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

Development Workflow

Typical Development Session

Start development build:
npm run dev
Start WordPress environment (in another terminal):
npm run env:start
Make your changes to PHP, JavaScript, or SCSS files
Test your changes in the browser at http://localhost:8888

Run linters before committing:

npm run lint:js
npm run lint:css
npm run lint:php

Commit your changes (hooks will run automatically):

git add .
git commit -m "Your commit message"

Working with PHP

When modifying PHP files:

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

Working with JavaScript

When modifying JavaScript files in assets/js/ or gutenberg/:

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

Working with SCSS

When modifying styles in assets/css/, gutenberg/, or templates/:

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

Working with Gutenberg Blocks

For React components in gutenberg/:

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

Build Output

Webpack compiles source files into the build/ directory:

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

Do not edit files in build/ directly - they will be overwritten. Always edit source files in:

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

Debugging

Enable WordPress Debug Mode

Edit wp-config.php in your wp-env environment:

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

Development builds include source maps for debugging:

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

Use browser DevTools to debug with original source files.

PHP Debugging

Add debug output:

error_log( print_r( $variable, true ) );

View logs:

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

Troubleshooting

Port Already in Use

If port 8888 is already in use:

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

Node Modules Issues

If you encounter dependency issues:

rm -rf node_modules package-lock.json
npm install

Composer Issues

If PHP dependencies are problematic:

rm -rf vendors composer.lock
composer install

wp-env Issues

Reset the WordPress environment:

npm run env:destroy
npm run env:start

Build Issues

Clear webpack cache:

rm -rf .cache build
npm run build

IDE Configuration

VS Code

The project includes VS Code settings in .vscode/:

ESLint integration
Stylelint integration
PHP formatting
Recommended extensions

Install recommended extensions when prompted.

PHP IntelliSense

For better PHP autocomplete, install WordPress stubs:

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

​Prerequisites

​Required Software

​Verify Installation

​Installation

​1. Clone the Repository

​2. Install Dependencies

​3. Configure Git Hooks

​Development Commands

​Build Commands

​Start Development Mode

​Build for Development

​Build for Production

​Code Quality

​Linting

​Auto-Fixing

​Testing

​WordPress Test Environment

​Running Tests

​Development Workflow

​Typical Development Session

​Working with PHP

​Working with JavaScript

​Working with SCSS

​Working with Gutenberg Blocks

​Build Output

​Debugging

​Enable WordPress Debug Mode

​Source Maps

​PHP Debugging

​Troubleshooting

​Port Already in Use

​Node Modules Issues

​Composer Issues

​wp-env Issues

​Build Issues

​IDE Configuration

​VS Code

​PHP IntelliSense

​Next Steps