Frequently Asked Questions

Common questions and answers about LamaPress development.

Table of Contents

• Getting Started
• Components
• ACF Fields
• JavaScript
• Styling
• Build & Deployment
• Troubleshooting

Getting Started

Q: How do I set up a new project?

A: See the Getting Started Guide for step-by-step instructions. You'll need:

1. Laravel Herd installed
2. Node.js v24 LTS
3. Clone the repository
4. Run npm install
5. Start development server with npm run dev

Q: Do I need ACF Pro?

A: Yes, ACF Pro is required for LamaPress. The flexible content feature is essential for the component system.

Q: What PHP version do I need?

A: PHP 8.4 is recommended. Check your Herd PHP version with herd php.

Components

Q: What's the difference between sections, blocks, and parts?

A:

• Sections - Full-width page sections (hero, content sections)
• Blocks - Reusable UI components (accordions, sliders)
• Parts - Small atomic components (buttons, icons)

See Component System for details.

Q: When should I create a new component vs. modifying an existing one?

A: Create a new component when:

• The functionality is significantly different
• It will be reused in multiple places
• It has its own ACF fields

Modify existing when:

• Small styling changes
• Minor functionality additions
• Bug fixes

Q: How do I pass data to a component?

A: Use the props parameter:

llBlock('my-component', [
    'fields' => ['title' => 'Hello'],
    'classes' => 'custom-class'
]);

See Component System for details.

Q: Why isn't my component JavaScript loading?

A: Check:

1. data-component attribute matches file path
2. JavaScript file exists and exports default class
3. No JavaScript errors in console
4. Component is in the DOM when loaded

See Troubleshooting for more help.

ACF Fields

Q: Why aren't my ACF fields showing?

A: Check:

1. ACF Pro is installed and activated
2. Field group key is unique
3. Template is using correct section key
4. Clear any caching

See ACF Integration for details.

Q: How do I make fields conditional?

A: Use conditional_logic in field definition:

'conditional_logic' => [
    [
        [
            'field' => $name . '_01',
            'operator' => '==',
            'value' => '1',
        ],
    ],
],

Q: Can I reuse fields from other components?

A: Yes, use llGetFields():

$blockFields = llGetFields('block', 'accordion', $key);
$groupFields = array_merge($myFields, $blockFields);

Q: What's the difference between section and block ACF files?

A:

• Sections - Must define $key, $name, $title, $category, and $groupFields
• Blocks/Parts - Only return $groupFields array

JavaScript

Q: How do I access other component instances?

A: Use the app instance:

const otherComponent = app.instances.get('page').instances.get(element);

Q: Why are my animations not working?

A: Check:

1. GSAP is imported correctly
2. ScrollTrigger is registered
3. Element exists when animation is created
4. Timeline is bound to component instance

Q: How do I handle page transitions?

A: Components automatically handle transitions:

• destroy() is called on page leave
• enter() is called on page enter
• Clean up timelines and listeners in destroy()

See JavaScript Architecture for details.

Q: How do I add event listeners?

A: Add them in bindEvents() method:

bindEvents = () => {
  this.element.addEventListener('click', this.handleClick)
}

Clean up in destroy():

destroy = () => {
  this.element.removeEventListener('click', this.handleClick)
}

Styling

Q: When should I use custom SCSS vs. Tailwind?

A: Use Tailwind classes whenever possible. Only create custom SCSS when:

• Tailwind doesn't have the utility you need
• Complex animations or transitions
• Component-specific styling that doesn't fit utilities

Q: How do I use the design system classes?

A: Use the predefined classes:

<h1 class="ll-heading-2xl">Title</h1>
<p class="ll-body-lg">Content</p>
<div class="ll-container">Container</div>

See Styling System for all available classes.

Q: How do I make responsive styles?

A: Use Tailwind responsive prefixes:

<div class="p-4 md:p-8 lg:p-12">

See Styling System for responsive patterns.

Build & Deployment

Q: Why aren't my styles loading?

A: Check:

1. npm run dev is running (development)
2. npm run build completed successfully (production)
3. dist/ directory exists
4. Access site via Herd URL, not localhost:5173

Q: Do I need to commit the dist/ directory?

A: Yes, commit dist/ with production builds. It's required for deployment.

Q: How do I analyze bundle size?

A: Run:

npm run analyze

This generates a visual report of your bundle.

Q: What's the difference between development and production builds?

A:

• Development - Unminified, source maps, HMR
• Production - Minified, optimized, hashed filenames

Troubleshooting

Q: My component isn't rendering

A: Check:

1. Component file exists
2. Function call is correct
3. Data is being passed
4. No PHP errors in logs

Q: Vite server won't start

A: Check:

1. Port 5173 is available
2. Node.js version is correct (v24 LTS)
3. Dependencies installed (npm install)

Q: Assets not loading after deployment

A: Check:

1. Build completed successfully
2. dist/ directory committed
3. File permissions correct
4. Manifest file exists

Q: Where can I get more help?

A:

1. Check Troubleshooting Guide
2. Review relevant documentation
3. Check existing components for examples
4. Ask the team

Related Documentation

• Getting Started - Setup guide
• Troubleshooting - Common issues
• Component System - Component guide

---

Still have questions? Check the Troubleshooting Guide or ask the team!