Valdi Documentation

File: README.md Copy Chapter

Valdi

[!NOTE]
Beta Status: Valdi has been widely used in Snap's production apps for the last 8 years. We're calling this a beta because our tools and documentation need more battle testing in the open source world. Valdi will exit beta when we're happy with the developer experience.

Valdi is a cross-platform UI framework that delivers native performance without sacrificing developer velocity. Write your UI once in declarative TypeScript, and it compiles directly to native views on iOS, Android, and macOS—no web views, no JavaScript bridges.

Quick Example Copy Chapter

A basic Valdi component:

import { Component } from 'valdi_core/src/Component';

class HelloWorld extends Component {
  onRender() {
    const message = 'Hello World! 👻';
    <view backgroundColor='#FFFC00' padding={30}>
      <label color='black' value={message} />
    </view>;
  }
}

Quick Start Copy Chapter

Prerequisites: Xcode (macOS only) - everything else is automatic!

# Install Valdi CLI
npm install @snap/valdi

# One-command setup (installs all dependencies)
valdi dev_setup

# Create your first project
mkdir my_project && cd my_project
valdi bootstrap
valdi install ios  # or android

[!TIP]
Editor Extensions: For the best development experience, install the Valdi VSCode/Cursor extensions for syntax highlighting, debugging, and device logs during hot reload.

Quick Links Copy Chapter

• Getting Started Guide
• Documentation
• Codelabs
• API Reference
• Frequently Asked Questions
• Component Library
• GitHub Discussions
• Roadmap

Example Apps Copy Chapter

The apps/ directory contains runnable examples:

Why Choose Valdi? Copy Chapter

Valdi is a cross-platform UI framework designed to solve the fundamental problem of cross-platform development: velocity vs. runtime performance. For 8 years, it has powered a large portion of Snap's production apps.

True Native Performance Copy Section

Unlike frameworks that rely on web views or JavaScript bridges, Valdi compiles declaratively rendered TypeScript components into platform-native views. Valdi also includes several other performance advantages:

• Automatic view recycling - Global view pooling system reuses native views across all screens, dramatically reducing inflation latency
• Optimized component rendering - Components re-render independently without triggering parent re-renders, enabling fast incremental updates
• Optimized layout engine - C++ layout engine runs on the main thread with minimal marshalling overhead
• Viewport-aware rendering - Only visible views are inflated, making infinite scrolling performant by default

Learn more in our Performance Optimization Guide.

Developer Experience Built for Speed Copy Section

Valdi eliminates the traditional compile-test-debug cycle that slows native development:

• Instant hot reload - See changes in milliseconds on iOS, Android, or desktop without recompiling
• Full VSCode debugging - Set breakpoints, inspect variables, profile performance, and capture heap dumps directly in VSCode
• Familiar syntax - TSX components with TypeScript for type safety

Flexible Adoption Model Copy Section

Valdi integrates easily into existing apps - start small and scale as needed:

• Embed Valdi in native - Drop Valdi components into existing UIKit or Android view hierarchies
• Embed native in Valdi - Use platform-specific views within Valdi layouts via <custom-view>
• Polyglot modules - Write performance-critical code in C++, Swift, Kotlin, or Objective-C with type-safe bindings to TypeScript
• Full-stack architecture - Build entire features in Valdi with worker threads for background processing, eliminating platform-specific bridge code

Deep Native Integration Copy Section

Valdi generates type-safe bindings between TypeScript and native platforms:

• Automatic code generation - TypeScript interfaces compile to Kotlin, Objective-C, and Swift bindings
• Native API access - Direct access to platform APIs and third-party native libraries through polyglot modules
• Bidirectional communication - Pass complex data structures and callbacks between TypeScript and native code safely
• Native protobuf support - Seamless integration with protobuf for efficient data serialization

Proven at Scale Copy Section

• Powers critical features in production Snap apps.
• Supports advanced animations, real-time rendering, and complex gesture systems

Feature Highlights Copy Section

• Flexbox layout system with automatic RTL support
• Worker threads for multi-threaded JavaScript execution
• Native animations for native look and feel
• Advanced gesture recognition with platform-native handling
• Built-in testing framework with component-level unit tests
• Bazel integration for reproducible, incremental builds

Need Help? Copy Chapter

• GitHub Discussions — ask questions and share what you're building
• GitHub Issues — report bugs and request features

Contributing Copy Chapter

Please follow the contributing guidelines.

License Copy Chapter

Valdi is made available under the MIT License.

File: docs/README.md Copy Chapter

Valdi Docs

• What is Valdi?
• Getting Started with Valdi
• Valdi Code Labs
• Valdi Command Line References

Coming From Another Framework Copy Chapter

• Migrating from React
• Migrating from Flutter
• Migrating from Jetpack Compose

API Reference Copy Chapter

• API Reference - Comprehensive API documentation for all native elements
• Style Attributes Reference - Complete guide to all style attributes for each element type
• Quick Reference Guide - Quick lookup for commonly used properties

The Basics Copy Chapter

• Valdi Module
• The Mighty Component
• Component States
• Component Events
• Control Flow
• FlexBox Layout
• <layout> and <view>
• <label> and Text
• ``
• <video>
• <scroll>
• <slot>
• Style<>
• Touches and Gestures
• Navigation

Internals Copy Chapter

• Runtime Internals - Deep dive into Valdi::Value, memory management, and the binary protocol
• Renderer Internals - Detailed explanation of the diffing algorithm and slot optimizations
• Compiler Internals - Pipeline architecture and TSX transformation details
• Native Integration Internals - View factories, pooling, and attribute binding
• API Design & Extensibility - Philosophy, bridge modules, and layered architecture

Native Integration Copy Chapter

• Annotations
• Native Bindings
• Polyglot Modules
• Component Context
• View Model
• Type Conversions
• The <custom-view>
• Native CollectionViews

Client Libraries Copy Chapter

• Protobuf
• RxJS

Standard Library Copy Chapter

• Core Utilities - Array utilities, Base64, LRU Cache, MD5, UUID, and more
• HTTP Client - Promise-based HTTP client for network requests
• Persistent Storage - Key-value storage with encryption and TTL support
• File System - Low-level file I/O operations (internal use)
• Glossary - Comprehensive guide to Valdi terminology

Debugging Tools Copy Chapter

• Hermes Debugger
• Valdi Inspector

Advanced Topics Copy Chapter

• Animations
• Custom Image Loader
• Localization
• Element References
• Provider
• Native References
• Worker Service
• Full stack Valdi

Performance Copy Chapter

• Optimization
• Tracing
• Memory Leaks
• View Recycling

Workflow Copy Chapter

• SwiftPM, CocoaPods, Xcode and Gradle integration
• Releasing to app stores
• Building a CLI application
• Valdi rules for Bazel
• Valdi Style Guide
• Valdi Inspector
• Testing
• Hermes Debugger
• Disk Management

Example Apps Copy Chapter

• Hello World - minimal component with hot reload
• Navigation Example - screen navigation patterns
• Managed Context Example - shared state across components
• Valdi GPT - AI-driven dynamic UI rendered at runtime
• CLI Application Example - building a Valdi CLI app
• Benchmark - performance benchmarks

Misc Copy Chapter

• Roadmap
• Third party dependencies
• Frequently Asked Questions

Help Copy Chapter

• Support
• Troubleshooting