Modern WordPress development environment on Windows

As WordPress development evolves, modern workflows have become increasingly important. Roots.io provides a powerful suite of tools for WordPress development, but setting up a proper development environment on Windows requires careful consideration. In this guide, we’ll walk through creating a robust development environment that combines Laravel Homestead, WSL, and NVM for optimal WordPress development with Roots.

Prerequisites

Before we begin, ensure you have the following installed:

• Windows 10 or 11
• Virtual Box
• Vagrant
• Windows Subsystem for Linux (WSL1)
• Visual Studio Code
• Git for Windows

1. Setting Up Laravel Homestead

Laravel Homestead provides an excellent pre-packaged Vagrant box that includes everything we need for WordPress development.

Installing Homestead

# Clone Homestead repository
git clone https://github.com/laravel/homestead.git ~/Homestead

# Navigate to Homestead directory
cd ~/Homestead

# Initialize Homestead
# Use init.bat for Windows
init.bat

Configuring Homestead.yaml

Create or modify your Homestead.yaml file:

---
ip: "192.168.56.56"
memory: 2048
cpus: 2
provider: virtualbox

authorize: ~/.ssh/id_rsa.pub

keys:
    - ~/.ssh/id_rsa

folders:
    - map: "C:/Projects"
      to: "/home/vagrant/Projects"

sites:
    - map: wordpress.test
      to: /home/vagrant/Projects/wordpress/public

databases:
    - wordpress

features:
    - mysql: true
    - mariadb: false
    - postgresql: false
    - php: true

Configuring Windows Hosts File

1. Open Notepad as Administrator (right-click Notepad and select "Run as administrator")
2. Open the hosts file located at: C:\Windows\System32\drivers\etc\hosts
3. Add the following line at the bottom of the file:

   192.168.56.56   wordpress.test
   

4. Save the file (you might need to change the file type to "All Files" when saving)

Note: If you’re working on multiple projects, you can add additional domains following the same pattern:

192.168.56.56   wordpress.test
192.168.56.56   project2.test
192.168.56.56   project3.test

Testing the Configuration

After configuring both Homestead.yaml and the hosts file:

1. If Homestead is running, reload it to apply changes:

   vagrant reload --provision
   

2. Test the connection by:
   • Pinging the domain: ping wordpress.test
   • Opening the domain in your browser: http://wordpress.test
   • If you see the default nginx page, the configuration is working

2. Setting Up WSL for Sage Theme Development

While Homestead handles our server environment, WSL1 is recommended for Sage theme development due to better performance with hot reloading.

Installing WSL1

1. First, enable the Windows Subsystem for Linux feature:

   # Open PowerShell as Administrator and run:
   dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart
   

2. By default, when you install WSL now, it installs WSL2. To specifically use WSL1:
   • After installing your Linux distribution from the Microsoft Store
   • Before launching it for the first time, open PowerShell as Administrator and run:

     wsl --set-version Ubuntu-20.04 1
     

3. You can verify the WSL version of your installation:

   wsl -l -v
   

Installing Ubuntu on WSL

1. Open Microsoft Store
2. Search for "Ubuntu"
3. Install Ubuntu 20.04 LTS
4. BEFORE launching Ubuntu for the first time, set it to use WSL1 using the command above
5. Launch Ubuntu and set up your username/password

3. Node Version Management with NVM

Installing NVM on Windows

# Download and run nvm-setup.exe from:
# https://github.com/coreybutler/nvm-windows/releases

# Install Node.js versions
nvm install 16.20.0
nvm install 18.16.0

# Set default version
nvm use 16.20.0

Installing NVM in WSL

# In your WSL terminal:
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash

# Reload shell configuration
source ~/.bashrc

# Install Node.js versions
nvm install 16.20.0
nvm install 18.16.0

4. Setting Up a Roots.io Project

Installing Bedrock

Since Composer is available inside the Homestead VM, we need to perform the Bedrock installation from there:

# SSH into your Homestead VM
cd ~/Homestead
vagrant ssh

# Navigate to your project directory (mapped in Homestead.yaml)
cd ~/Projects

# Create new Bedrock installation
composer create-project roots/bedrock wordpress

# Set proper permissions
chmod -R 755 wordpress

Important Notes:

• Always run Composer commands from within Homestead to ensure proper PHP compatibility
• The wordpress directory will be accessible from your Windows host at C:/Projects/wordpress (or whatever path you mapped in Homestead.yaml)
• Make sure your web server has proper permissions to read/write to the WordPress directory

Installing Sage Theme

For theme development, you can either:

1. Install Sage from within Homestead (for Composer operations):

   # From within Homestead VM
   cd ~/Projects/wordpress/web/app/themes
   composer create-project roots/sage your-theme-name
   

2. Then switch to WSL for development operations:

   # In your WSL terminal
   cd /mnt/c/Projects/wordpress/web/app/themes/your-theme-name
   
   # Install Node.js dependencies and start development
   yarn
   yarn dev
   

This workflow combines:

• Homestead for PHP/Composer operations
• WSL1 for theme development and build processes

5. Development Workflow

Starting the Development Environment

1. Start Homestead:

   cd ~/Homestead
   vagrant up
   

2. Access your WordPress site at http://wordpress.test

Theme Development with Sage

In your WSL terminal:

# Navigate to theme directory
cd /mnt/c/Projects/wordpress/web/app/themes/your-theme-name

# Start development server
yarn dev

Tips and Troubleshooting

Hot Reloading with WSL1

To ensure optimal hot reloading performance:

1. Use WSL1 instead of WSL2 for Sage development
2. Add your project path to Windows Defender exclusions
3. Configure your .bud.config.js:

export default async (config) => {
  config.watch = {
    usePolling: true,
    poll: 1000,
  }
}

PHP Version Management in Homestead

To switch PHP versions in Homestead:

# SSH into Homestead
vagrant ssh

# Switch PHP version
sudo update-alternatives --set php /usr/bin/php8.1

Common Issues and Solutions

1. Slow Performance:
   • Ensure antivirus exclusions are set for project directory
   • Use WSL1 instead of WSL2 for better file system performance
   • Increase VM resources in Homestead.yaml if needed
2. Node.js Compatibility:
   • Use NVM to switch Node versions based on project requirements
   • Sage 10 works best with Node.js 16.x
3. Composer Memory Issues:
   • Increase memory limit in php.ini
   • Run Composer with increased memory: php -d memory_limit=-1 composer install

Conclusion

This setup provides a robust development environment that combines the best of both worlds: Homestead for a stable server environment and WSL1 for efficient theme development. While it might seem complex initially, this configuration offers flexibility and performance for modern WordPress development with Roots.io tools.

Remember to:

• Keep your environments updated
• Use version control for your projects
• Regularly backup your databases
• Document your specific environment configurations

This setup allows you to take full advantage of modern WordPress development tools while maintaining a stable and efficient workflow on Windows.