Valdi Framework Development Skill Skill

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 | Purpose | |---------|---------| | <view> | Container view (like div) | | <layout> | Flexbox layout container | | <scroll> | Scrollable container | | <label> | Text display | | <image> | Image display | | <video> | Video player | | <slot> | Content projection |

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):

Install shell commands from editor
Install extensions from Valdi release:
- valdi-vivaldi.vsix (device logs, language support)
- valdi-debug.vsix (JavaScript debugger)
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:

| Module | Purpose | |--------|---------| | valdi_core | Core component system, lifecycle | | valdi_tsx | TSX/JSX support | | valdi_protobuf | Protobuf serialization | | valdi_http | HTTP client | | valdi_storage | Persistent encrypted storage | | valdi_navigation | Navigation system | | valdi_rxjs | RxJS integration |

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

| Command | Purpose | |---------|---------| | valdi dev_setup | Setup development environment | | valdi doctor | Check environment health | | valdi bootstrap | Create new project | | valdi install [platform] | Install platform dependencies | | valdi hotreload | Enable live updates | | valdi projectsync | Sync project configuration |

Lifecycle Methods

| Method | When Called | |--------|-------------| | onCreate() | Component initialization | | onMount() | Added to view hierarchy | | onUnmount() | Before removal from hierarchy | | onRender() | Render component UI |

Native Elements

| Element | HTML Equivalent | |---------|-----------------| | <view> | <div> | | <layout> | Flexbox container | | <scroll> | Scrollable div | | <label> | <span> / <p> | | <image> | <img> | | <video> | <video> |

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.

Agent Skills: Valdi Framework Development Skill

Install this agent skill to your local

Skill Files