Migration Guide

This guide helps you migrate existing WordPress themes or projects to LamaPress.

Table of Contents

• Overview
• Pre-Migration Planning
• Migration Steps
• Component Migration
• ACF Migration
• JavaScript Migration
• Styling Migration
• Post-Migration

Overview

Migrating to LamaPress involves:

1. Setting up LamaPress structure
2. Converting existing components
3. Migrating ACF fields
4. Converting JavaScript
5. Migrating styles
6. Testing and validation

Pre-Migration Planning

Assessment

Before migrating, assess:

1. Current Structure

   • How are components organized?
   • What ACF field structure exists?
   • What JavaScript frameworks are used?
   • What styling approach is used?

2. Dependencies

   • Required plugins
   • Custom functionality
   • Third-party integrations

3. Content

   • Existing ACF fields
   • Custom post types
   • Taxonomies

Planning

Create a migration plan:

1. Inventory Components

   • List all components to migrate
   • Identify reusable vs. one-off
   • Plan component structure

2. Field Mapping

   • Map existing ACF fields
   • Plan field organization
   • Identify reusable fields

3. Timeline

   • Break into phases
   • Set milestones
   • Plan testing phases

Migration Steps

Step 1: Set Up LamaPress

1. Clone LamaPress repository
2. Install dependencies (npm install, composer install)
3. Set up development environment
4. Configure WordPress constants

Step 2: Migrate Structure

1. Create component directories
2. Set up function files
3. Configure ACF
4. Set up build system

Step 3: Migrate Components

1. Convert templates to LamaPress format
2. Migrate ACF fields
3. Convert JavaScript
4. Migrate styles

Step 4: Test

1. Test each component
2. Verify ACF fields
3. Test JavaScript functionality
4. Check styling

Component Migration

Template Conversion

Before (Traditional WordPress):

<?php
$title = get_field('title');
$content = get_field('content');
?>

<div class="section">
    <h1><?php echo $title; ?></h1>
    <div><?php echo $content; ?></div>
</div>

After (LamaPress):

<?php

/**
 * Hero section component.
 */

defined('ABSPATH') || exit;

$section ??= false;
$key ??= false;

$title = llField('title', $key, $section);
$content = llField('content', $key, $section);
?>

<?php llSectionHeader(name: 'hero_basic'); ?>

<?php if ($title): ?>
    <h1 class="ll-heading-2xl"><?= esc_html($title) ?></h1>
<?php endif; ?>

<?php if ($content): ?>
    <div class="ll-body-lg"><?= wp_kses_post($content) ?></div>
<?php endif; ?>

<?php llSectionFooter(); ?>

Key Changes

1. File Header - Add DocBlock and security check
2. Field Access - Use llField() instead of get_field()
3. Output - Use <?= ?> shorthand and escape output
4. Structure - Use llSectionHeader() and llSectionFooter()
5. Classes - Use design system classes

ACF Migration

Field Group Conversion

Before (ACF UI):

• Fields created in ACF UI
• Field groups attached to templates
• Manual field management

After (LamaPress):

<?php
// components/sections/hero_basic/acf.php
$title = 'Hero Basic';
$name = 'hero_basic';
$category = 'common';
$key = 'a1b2c3d4e5f6';  // Unique 12-char key

$groupFields = [
    [
        'key' => $name . '_01',
        'label' => 'Title',
        'name' => 'title',
        'type' => 'text',
        'instructions' => 'Enter the hero title',
    ],
    [
        'key' => $name . '_02',
        'label' => 'Content',
        'name' => 'content',
        'type' => 'wysiwyg',
    ],
];
?>

Field Key Migration

Important: Field keys must be migrated carefully:

1. Export Existing Fields

   • Export ACF field groups as JSON
   • Note existing field keys

2. Map Field Keys

   • Create mapping of old to new keys
   • Update field references in code

3. Update Database

   • May need to update post meta keys
   • Test thoroughly after migration

JavaScript Migration

Component Conversion

Before (jQuery/vanilla JS):

$(document).ready(function() {
    $('.accordion').each(function() {
        $(this).find('.accordion-header').click(function() {
            $(this).next('.accordion-content').slideToggle();
        });
    });
});

After (LamaPress):

import { gsap } from 'gsap/all'
import { app } from '@src/js/core/app'

export default class Accordion {
  constructor(element) {
    this.element = element
    this.button = this.element.querySelector('.js-accordion-button')
    this.content = this.element.querySelector('.js-accordion-content')
    this.isOpen = false
    this.init()
  }

  init = () => {
    this.bindEvents()
    this.setInitialState()
  }

  setInitialState = () => {
    gsap.set(this.content, { height: 0, overflow: 'hidden' })
  }

  bindEvents = () => {
    this.button.addEventListener('click', this.toggle)
  }

  toggle = () => {
    if (this.isOpen) {
      this.close()
    } else {
      this.open()
    }
  }

  open = () => {
    this.isOpen = true
    gsap.to(this.content, {
      height: 'auto',
      duration: 0.4
    })
  }

  close = () => {
    this.isOpen = false
    gsap.to(this.content, {
      height: 0,
      duration: 0.4
    })
  }

  destroy = () => {
    this.button.removeEventListener('click', this.toggle)
  }
}

Key Changes

1. ES6 Modules - Use import/export
2. Class-Based - Convert to component classes
3. GSAP - Use GSAP for animations
4. Lifecycle - Implement standard methods
5. Cleanup - Add destroy() method

Styling Migration

CSS to Tailwind

Before (Custom CSS):

.hero-section {
    padding: 60px 20px;
    background: #ffffff;
    text-align: center;
}

.hero-title {
    font-size: 48px;
    font-weight: bold;
    margin-bottom: 20px;
}

After (Tailwind + Design System):

<section class="ll-section ll-section--hero">
    <div class="ll-container py-12 md:py-16">
        <h1 class="ll-heading-2xl mb-5">Title</h1>
    </div>
</section>

Key Changes

1. Utility Classes - Use Tailwind utilities
2. Design System - Use design system classes
3. Responsive - Use responsive prefixes
4. Minimal Custom CSS - Only when Tailwind insufficient

Post-Migration

Testing Checklist

• [ ] All components render correctly
• [ ] ACF fields display and save
• [ ] JavaScript functionality works
• [ ] Styles apply correctly
• [ ] Responsive design works
• [ ] Page transitions work
• [ ] No console errors
• [ ] Performance is acceptable

Validation

1. Functionality

   • Test all features
   • Verify data flow
   • Check interactions

2. Styling

   • Visual comparison
   • Responsive testing
   • Browser testing

3. Performance

   • Run Lighthouse audit
   • Check bundle size
   • Verify optimization

Common Issues

Field Values Missing:

• Check field key migration
• Verify ACF field groups
• Check field references

Styles Not Applying:

• Verify Tailwind classes
• Check custom SCSS
• Verify build completed

JavaScript Not Working:

• Check component initialization
• Verify data-component attribute
• Check for JavaScript errors

Best Practices

1. Migrate Incrementally

Don't migrate everything at once:

• Start with simple components
• Migrate section by section
• Test after each migration

2. Keep Old Code

Keep old code until migration is complete:

• Comment out old code
• Keep as reference
• Remove after validation

3. Document Changes

Document migration decisions:

• Why components were structured a certain way
• Field key mappings
• Custom functionality

4. Test Thoroughly

Test everything:

• All pages
• All components
• All functionality
• All browsers

Related Documentation

• Getting Started - Initial setup
• Component System - Component structure
• ACF Integration - ACF patterns
• Troubleshooting - Common issues

---

Need Help? Check the Troubleshooting Guide or ask the team!