Development Environment Setup

This guide will walk you through setting up a complete development environment for LamaPress using Laravel Herd.

Prerequisites

Before starting, ensure you have:

• macOS (This guide uses Laravel Herd, which is macOS-only. The theme code itself works on any platform, but our development workflow is optimized for macOS.)
• Administrator access (for installing Herd)
• Basic terminal knowledge

Step 1: Install Laravel Herd

Laravel Herd is a native macOS application that provides a lightning-fast local development environment.

Download and Install

1. Visit https://herd.laravel.com
2. Download the latest version for macOS
3. Open the downloaded .dmg file
4. Drag Herd to your Applications folder
5. Launch Herd from Applications
6. Follow the installation wizard

Activate Herd Pro License

We use Herd Pro for additional features. To activate your license:

1. Open 1Password and search for "Herd Pro" or "Laravel Herd"
2. Copy the license key from 1Password
3. In Herd, go to Settings > License (or click the license icon)
4. Paste your license key and activate

Note: If you don't have access to the license in 1Password, ask a team member for access.

Verify Installation

Open Terminal and run:

herd version

You should see the Herd version number. If not, make sure Herd is running and try again.

Step 2: Install Node.js

LamaPress requires Node.js for the build system. We use Node.js v24 LTS.

Check if Node.js is Installed

node --version
npm --version

Install Node.js (if needed)

1. Visit https://nodejs.org
2. Download Node.js v24 LTS
3. Run the installer
4. Verify installation:

node --version  # Should show v24.x.x (LTS)
npm --version   # Should show 9.x.x or higher

Step 3: Set Up Your WordPress Site

Option A: New WordPress Installation

1. Create a new site in Herd:

   • Open Herd application
   • Click "Add Site" or use the + button
   • Choose "WordPress" as the site type
   • Enter your site name (e.g., my-project)
   • Herd will create the site at http://my-project.test

2. Install WordPress:

   • Visit http://my-project.test in your browser
   • Follow the WordPress installation wizard
   • Complete the setup with your preferred credentials

Option B: Existing WordPress Installation

1. Point Herd to existing WordPress:
   • Open Herd application
   • Click "Add Site"
   • Choose "Existing Site"
   • Select your WordPress directory
   • Herd will detect and configure it

Step 4: Install LamaPress Theme

Clone or Copy Theme

# Navigate to your WordPress themes directory
cd ~/path/to/wordpress/wp-content/themes

# If cloning from GitHub
git clone https://github.com/lamalamanl/lamapress.git lamapress

# Or if copying from another location
cp -r /path/to/lamapress ./

# Navigate into the theme directory
cd lamapress

Install Dependencies

# Install PHP dependencies (if using Composer)
composer install

# Install Node.js dependencies
npm install

Step 5: Configure WordPress

Add Required Constants

Edit your wp-config.php file (usually in the WordPress root directory):

// Optional: Google Tag Manager
define('LL_GTM_ID', ''); // e.g., 'GTM-WV2VZWQ'

// Optional: Cookie Consent
define('LL_COOKIE_CONSENT', ''); // 'cookiebot' or 'lamapress'
define('LL_COOKIEBOT_ID', ''); // Required if using Cookiebot

// Optional: Bunny.net Integration
define('LL_BUNNY_API_KEY', '');
define('LL_BUNNY_LIBRARY_ID', '');
define('LL_BUNNY_PULL_ZONE', '');

Activate the Theme

1. Log in to WordPress admin (http://your-site.test/wp-admin)
2. Navigate to Appearance > Themes
3. Find "LamaPress" and click Activate

Step 6: Start Development Server

Start Vite Development Server

In your terminal, navigate to the theme directory and run:

npm run dev

You should see output like:

VITE v5.x.x  ready in xxx ms

➜  Local:   http://localhost:5173/
➜  Network: use --host to expose

Important Notes:

• The Vite server runs on http://localhost:5173 for Hot Module Replacement (HMR)
• Do not access your site via localhost:5173 directly
• Access your site via your Herd URL (e.g., http://your-site.test)
• Vite automatically injects the necessary scripts and styles

Verify Everything Works

1. Visit your site in the browser (via Herd URL)
2. Open browser DevTools (F12 or Cmd+Option+I)
3. Check the Console tab for any errors
4. Verify that styles are loading (check Network tab)
5. Make a small change to a component and verify hot reload works

Step 7: Install Required WordPress Plugins

LamaPress requires (or works best with) these plugins:

Essential Plugins

1. Advanced Custom Fields Pro - Required for flexible content

   • Install via ACF website or your license
   • Activate the plugin

2. Gravity Forms (if using forms)

   • Install and activate if your project uses forms

Development Workflow

Daily Development

1. Start Herd (if not already running)

   • Herd runs in the background, but verify it's active

2. Start Vite dev server:

   npm run dev

3. Access your site:

   • Use your Herd URL: http://your-site.test
   • Make changes to PHP, JavaScript, or SCSS files
   • Changes should hot-reload automatically

4. Build for production:

   npm run build

File Watching

Vite automatically watches for changes in:

• src/js/**/*.js - JavaScript files
• src/scss/**/*.scss - SCSS files
• components/**/*.js - Component JavaScript
• components/**/*.php - PHP files (triggers page reload)

Environment-Specific Configuration

Development

• Vite dev server running
• Hot module replacement enabled
• Source maps enabled
• Unminified assets

Staging (Laravel Forge)

• Built assets (npm run build)
• Minified JavaScript and CSS
• Optimized for performance
• See Deployment Guide for details

Production

• Fully optimized build
• All assets minified
• Caching enabled
• Performance monitoring

Useful Herd Commands

# List all sites
herd list

# Start/stop/restart a site
herd start
herd stop
herd restart

# Open site in browser
herd open <site-name>

# Check PHP version
herd php

# Switch PHP version
herd use php@8.4

# View logs
herd logs

Additional Resources

• Laravel Herd Documentation
• Vite Documentation
• WordPress Development Handbook

Related Documentation

• Getting Started Guide - Quick start guide
• Component System - Component development
• Styling System - Styling approach
• Troubleshooting - Common issues

---

Next Steps:

• Verify everything works in your environment
• Read Getting Started Guide for next steps
• Learn about Component System to start building
• Explore Styling System for design system

Having issues? Check the Troubleshooting Guide or ask the team for help!