Valdi Skill: Разработка и отладка компонентов

--- name: valdi description: This skill should be used when working on Valdi framework projects. Valdi is Snapchat's cross-platform UI framework that compiles TypeScript/TSX components into native views for iOS, Android, and macOS. It provides specialized knowledge for component architecture, Bazel build system, native bindings, TSX elements, and cross-platform development. Use this skill when implementing Valdi components, debugging build issues, or creating new Valdi projects. --- # 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:** ```bash # 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: ```tsx 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:** ```tsx 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:** ```python 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:** ```python 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:** ```typescript declare module 'CppModule' { export function performCalculation(value: number): number; export function getNativeString(): string; } ``` **NativeModule.d.ts:** ```typescript declare module 'NativeModule' { export function showNativeAlert(message: string): void; export function getPlatformInfo(): { os: string; version: string }; } ``` **Usage in component:** ```tsx 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:** ```bash # 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:** ```bash mkdir my_project && cd my_project valdi bootstrap valdi install ios # or android ``` **Development cycle:** ```bash # 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. ```tsx // 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. ```tsx // 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: ```javascript // .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: ```json { "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.