Valdi

Valdi Framework Development Skill

Specialized guidance for developing cross-platform applications with Valdi, Snapchat's native UI framework that compiles TypeScript/TSX to native iOS, Android, and macOS views.

Overview

Valdi is NOT a WebView-based framework. It compiles TypeScript components directly into native platform code, delivering native performance without JavaScript bridges. The framework has been used in Snap's production apps for over 8 years.

When to Use This Skill

Invoke this skill when:

• Working on any Valdi framework project
• Creating new Valdi components or modules
• Configuring Bazel build files for Valdi
• Implementing native bindings (CppModule, NativeModule)
• Debugging cross-platform rendering issues
• Setting up Valdi development environment
• Understanding Valdi's TSX element system

Key Principles

1. Bazel is Mandatory

Valdi uses Bazel exclusively for builds. Never suggest alternative build systems.

Common commands:

# Install CLI globally
pnpm install -g @snap/valdi

# Setup development environment
valdi dev_setup

# Check environment health
valdi doctor

# Bootstrap new project
valdi bootstrap

# Install platform dependencies
valdi install ios
valdi install android

# Enable hot reload during development
valdi hotreload

# Sync project configuration
valdi projectsync

2. Component Architecture

Valdi components are class-based with lifecycle methods:

import { Component, ComponentContext } from 'valdi_core';

interface ViewModel {
  title: string;
  count: number;
}

class MyComponent extends Component<ViewModel, ComponentContext> {
  onCreate(): void {
    // Initialize component
    console.log('Component created');
  }

  onMount(): void {
    // Component mounted to view hierarchy
  }

  onUnmount(): void {
    // Cleanup before removal
  }

  onRender() {
    return (
      <view style={styles.container}>
        <label style={styles.title}>{this.viewModel.title}</label>
      </view>
    );
  }
}

3. Native TSX Elements

Valdi provides native UI elements (NOT HTML):

Element attributes use native styling, not CSS:

const styles = {
  container: {
    alignItems: 'center',
    justifyContent: 'center',
    backgroundColor: '#FFFFFF',
    padding: 16,
  },
  title: {
    fontSize: 24,
    fontWeight: 'bold',
    color: '#000000',
  },
};

4. Project Structure

Standard Valdi project layout:

my_project/
├── BUILD.bazel              # Main Bazel build file
├── package.json             # Node dependencies (use pnpm)
├── .eslintrc.js            # ESLint configuration
├── app_assets/             # Application assets
│   └── images/
├── src/
│   ├── android/            # Android-specific code
│   ├── cpp/                # C++ native modules
│   ├── ios/                # iOS-specific code
│   └── valdi/              # Valdi TypeScript/TSX
│       ├── _configs/       # Valdi configs
│       ├── tsconfig.json
│       ├── .terserrc.json
│       └── my_module/      # Your module
│           ├── BUILD.bazel
│           ├── tsconfig.json
│           ├── res/        # Module resources
│           └── src/
│               ├── index.ts
│               └── MyComponent.tsx
└── standalone_app/         # Standalone app config

5. Bazel Build Configuration

Application BUILD.bazel:

load("//bzl:valdi.bzl", "valdi_application", "valdi_exported_library")

valdi_application(
    name = "my_app",
    title = "My Valdi App",
    version = "1.0.0",
    ios_bundle_id = "com.example.myapp",
    ios_device_families = ["iphone"],
    android_theme = "Theme.MyApp.Launch",
    android_app_icon = "app_icon",
    root_component = "App@my_module/src/MyApp",
    assets = glob(["app_assets/**/*"]),
    deps = ["//path/to/src/valdi/my_module"],
)

valdi_exported_library(
    name = "my_app_export",
    ios_bundle_id = "com.example.myapp.lib",
    bundle_name = "MyApp",
    deps = ["//path/to/src/valdi/my_module"],
)

Module BUILD.bazel:

load("//bzl:valdi.bzl", "valdi_module")

valdi_module(
    name = "my_module",
    srcs = glob(["src/**/*.ts", "src/**/*.tsx"]) + ["tsconfig.json"],
    assets = glob(["res/**/*.{jpeg,jpg,png,svg,webp}"]),
    android = struct(
        class_path = "com.example.valdi.modules.my_module",
        native_deps = ["//path/to/android:native_module"],
        release = True,
    ),
    ios = struct(
        module_name = "SCCMyModule",
        native_deps = ["//path/to/ios:native_module"],
        release = True,
    ),
    native = struct(
        deps = ["//path/to/cpp:native_module_cpp"],
    ),
    deps = [
        "//src/valdi_modules/valdi_core",
        "//src/valdi_modules/valdi_tsx",
    ],
    visibility = ["//visibility:public"],
)

6. Native Bindings

Valdi supports type-safe bindings to native code:

CppModule.d.ts:

declare module 'CppModule' {
  export function performCalculation(value: number): number;
  export function getNativeString(): string;
}

NativeModule.d.ts:

declare module 'NativeModule' {
  export function showNativeAlert(message: string): void;
  export function getPlatformInfo(): { os: string; version: string };
}

Usage in component:

import * as CppModule from 'CppModule';
import * as NativeModule from 'NativeModule';

class MyComponent extends Component<ViewModel, ComponentContext> {
  onMount() {
    const result = CppModule.performCalculation(42);
    const platform = NativeModule.getPlatformInfo();
  }
}

7. Cross-Platform Best Practices

All changes must work across iOS, Android, and macOS:

• Test on multiple platforms before committing
• Platform-specific code goes in dedicated directories (src/ios/, src/android/)
• Use Valdi's abstraction layer for platform differences
• Check AGENTS.md in repository for platform-specific guidance

Performance is critical:

• Valdi emphasizes rendering efficiency
• Use view recycling through Valdi's pooling systems
• Components render independently (no parent re-renders)
• Viewport-aware rendering for efficient scrolling

8. Development Workflow

Initial setup:

# Install Valdi CLI
pnpm install -g @snap/valdi

# Setup development environment (takes 10-20 minutes first time)
valdi dev_setup

# Verify installation
valdi doctor

Creating a new project:

mkdir my_project && cd my_project
valdi bootstrap
valdi install ios  # or android

Development cycle:

# Start hot reload for live updates
valdi hotreload

# After changing dependencies or resources
valdi projectsync

Editor setup (VSCode/Cursor):

1. Install shell commands from editor
2. Install extensions from Valdi release:
   • valdi-vivaldi.vsix (device logs, language support)
   • valdi-debug.vsix (JavaScript debugger)
3. Configure TypeScript workspace version

Common Pitfalls

1. Using Web/React Patterns

Problem: Treating Valdi like React or web development.

// WRONG - HTML elements don't exist
<div className="container">
  <span>Hello</span>
</div>

// CORRECT - Use Valdi native elements
<view style={styles.container}>
  <label>Hello</label>
</view>

2. CSS-Style Styling

Problem: Using CSS syntax for styles.

// WRONG - CSS syntax
const styles = {
  container: {
    'background-color': '#fff',
    'font-size': '16px',
  }
};

// CORRECT - Camel case, numeric values
const styles = {
  container: {
    backgroundColor: '#FFFFFF',
    fontSize: 16,
  }
};

3. Modifying Auto-Generated Code

Problem: Editing Djinni-generated native bindings directly.

Solution: Always modify source files, never generated code. Regenerate bindings after source changes.

4. Wrong Build System

Problem: Using npm/yarn scripts, webpack, or other bundlers.

Solution: Valdi uses Bazel exclusively. Use valdi CLI commands.

5. Missing Platform Testing

Problem: Only testing on one platform.

Solution: Always verify changes work on iOS, Android, and macOS where applicable.

ESLint Configuration

Standard Valdi ESLint setup:

// .eslintrc.js
module.exports = {
  parser: '@typescript-eslint/parser',
  parserOptions: {
    project: './tsconfig.json',
    ecmaVersion: 2020,
    sourceType: 'module',
    ecmaFeatures: {
      jsx: true,
    },
  },
  plugins: [
    '@typescript-eslint',
    'eslint-plugin-valdi',
    'rxjs',
    'import',
    'unused-imports',
  ],
  extends: [
    'eslint:recommended',
    'plugin:@typescript-eslint/recommended',
  ],
  rules: {
    // Valdi-specific rules
  },
};

TypeScript Configuration

Standard tsconfig.json for Valdi modules:

{
  "extends": "../../_configs/tsconfig.json",
  "compilerOptions": {
    "jsx": "react",
    "jsxFactory": "Valdi.createElement",
    "strict": true,
    "moduleResolution": "node",
    "esModuleInterop": true
  },
  "include": ["src/**/*"]
}

Available Libraries

Valdi provides these core modules:

Debugging

Using Hermes Debugger:

• Available for JavaScript debugging
• Set breakpoints in VSCode with valdi-debug extension

Using Valdi Inspector:

• Inspect UI hierarchy
• View component state
• Performance profiling

Quick Reference

CLI Commands

Lifecycle Methods

Native Elements

References

For more details:

• references/component-patterns.md - Advanced component patterns
• references/bazel-configuration.md - Detailed Bazel setup
• references/native-bindings.md - Native code integration

Additional Resources

• Valdi GitHub: https://github.com/Snapchat/Valdi
• AGENTS.md in repository for AI coding guidelines
• Discord community for support
• Codelabs in docs/ for guided tutorials

Remember: Valdi compiles to native code - think native, not web. Use Bazel for builds, pnpm for Node dependencies, and test on all target platforms.