Yoga Layout Engine - Deployment and Usage Guide

Prerequisites

Before getting started with Yoga, ensure you have the following installed:

• C++20 compiler - Yoga's main implementation targets C++20
• CMake - Build system for the C++ implementation
• Node.js and npm - For JavaScript bindings and test generation
• Yarn Classic - Required for generating tests from HTML fixtures
• Ninja (optional but recommended) - For faster builds if available
• VSCode (optional) - For debugging with provided launch configurations

Installation

Building the C++ Library

1. Clone the repository:

   git clone https://github.com/facebook/yoga.git
   cd yoga
   

2. Build and run unit tests:

   ./unit_tests <Debug|Release>
   

   • Use Debug for development builds
   • Use Release for production builds

3. The script will automatically use ninja if installed for faster builds.

Using with Package Managers

Yoga is available through several package managers:

• npm: npm install yoga-layout
• Maven Central: com.facebook.yoga:yoga
• vcpkg: Available as part of the vcpkg collection

Configuration

Environment Variables

Yoga doesn't require specific environment variables for basic operation. However, for advanced usage:

• Experimental Features: Enable via the Config object in JavaScript bindings
• Errata Settings: Configure using getErrata() and setErrata() methods
• Web Defaults: Toggle with useWebDefaults() and setUseWebDefaults()

Configuration Files

No specific configuration files are required. Yoga can be configured programmatically through its API.

Build & Run

Local Development

1. Running Unit Tests:

   ./unit_tests Debug
   

2. Debugging with VSCode:

   • Open the project in VSCode
   • Use the provided "launch.json" configuration
   • Run "Debug C++ Unit tests (lldb)" (or "Debug C++ Unit tests (vsdbg)" on Windows)

Adding Tests

1. Create HTML fixtures in gentest/fixtures/:

   <div id="my_test" style="width: 100px; height: 100px; align-items: center;">
     <div style="width: 50px; height: 50px;"></div>
   </div>
   

2. Generate tests:

   yarn install  # Install dependencies
   yarn gentest  # Generate tests from fixtures
   

Production Build

./unit_tests Release

Deployment

Platform Recommendations

Yoga is designed as an embeddable layout engine, making it suitable for various deployment scenarios:

1. Web Applications:

   • Use the JavaScript bindings via npm
   • Deploy with any standard web hosting (Vercel, Netlify, AWS S3, etc.)

2. Native Applications:

   • Integrate the C++ library directly
   • Suitable for mobile apps (iOS, Android) and desktop applications

3. Cross-Platform Libraries:

   • Use as a dependency in other projects
   • Available through vcpkg for C++ projects

Deployment Steps

1. Build the library in Release mode
2. Package the appropriate bindings for your target platform
3. Include in your application's build process
4. Deploy your application using standard deployment methods for your platform

Troubleshooting

Common Issues and Solutions

Build Failures

• Issue: CMake configuration fails
• Solution: Ensure C++20 compiler is installed and properly configured

Test Generation Fails

• Issue: yarn gentest fails to run
• Solution:
  1. Ensure yarn classic is installed
  2. Run yarn install to install dependencies
  3. Verify Chrome is installed for rendering fixtures

Performance Issues

• Issue: Layout calculations are slow
• Solution:
  1. Use Release builds for production
  2. Consider using ninja for faster builds
  3. Review complex node structures that may cause performance bottlenecks

Version Compatibility

• Issue: Using outdated version
• Solution: Check vcpkg for the latest version or create an issue/pull request on the vcpkg repository

Debugging Issues

• Issue: Unable to debug unit tests
• Solution:
  1. Use the provided VSCode "launch.json" configuration
  2. Ensure lldb (or vsdbg on Windows) is installed
  3. Add breakpoints before running the debug configuration

Missing Dependencies

• Issue: Build fails due to missing dependencies
• Solution:
  1. Verify all prerequisites are installed
  2. For JavaScript bindings, ensure Node.js and npm are up to date
  3. For C++ builds, ensure CMake and a C++20 compiler are available

Getting Help

• Check the GitHub Issues for known problems
• Review the source code in javascript/src/ for API documentation
• Use the generated enums in javascript/src/generated/YGEnums.ts as reference for available options