Guide · Open source

How to use Valdi: install, run your first component and tips

Updated 2026-10-29 · written with AI from the project's own documentation and checked against our catalogue data

Valdi is an open-source cross-platform UI framework from Snap. You write declarative TypeScript (TSX) components, and Valdi compiles them into native platform views rather than web views or a JavaScript bridge. This guide walks through prerequisites, installing the Valdi CLI, creating a first project and the main features, so you know what to expect after your first run.

ValdiSnapchat/Valdi · ★ 16.4k · MIT Install options & downloads

Quick start

1Check prerequisites. Install Node.js 18 or later (22 recommended). On macOS, install Xcode 26.5 or 27.
2Install the CLI. Run npm install -g @snap/valdi to add the valdi command.
3Run dev_setup. Run valdi dev_setup to install the remaining dependencies in one step.
4Create a project. Run mkdir my_project && cd my_project to make and enter a project folder.
5Bootstrap the project. Run valdi bootstrap inside the folder to set up the project.
6Run on a device. Run valdi install ios or valdi install android to launch the app and start editing components.

What you need before installing Valdi

Valdi requires Node.js 18 or later, and Node.js 22 is recommended. On macOS you also need Xcode 26.5 or 27.

The README says the command `valdi dev_setup` installs the rest of the dependencies, so you do not need to set those up by hand. Valdi is aimed at developers who are comfortable with TypeScript and with mobile or build tooling. Setup involves Node.js and, on macOS, Xcode, so it is not a beginner-friendly first project.

Node.js 18 or later (22 recommended)
On macOS: Xcode 26.5 or 27
Basic comfort with TypeScript

Install the Valdi CLI and run dev_setup

Install the Valdi command-line tool with npm, then run the one-command setup. The setup installs all dependencies the README lists.

npm install -g @snap/valdi
valdi dev_setup

Create and run your first Valdi project

Make a folder for your project, move into it, and bootstrap a Valdi project inside it. Then install the app on the platform you want to test: the README shows `ios` or `android` as the options.

Valdi's README describes instant hot reload, so changes can show up on iOS, Android or desktop without a full recompile.

Use `valdi install ios` or `valdi install android` to run the example on a device or simulator
Edit the component file and watch the change appear

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

Write a component in TSX

A Valdi component extends `Component` and returns its layout from `onRender()`. The README's HelloWorld example sets a yellow view with padding and a black label inside it.

The README calls out the familiar TSX syntax with TypeScript for type safety, so the tags you write, such as view and label, map onto native platform views.

Import Component from valdi_core/src/Component
Put your layout inside onRender()
Use typed props and TypeScript interfaces for safer code

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>;
  }
}

Add Valdi to an existing native app gradually

You do not have to rewrite an app to try Valdi. The README describes embedding Valdi components in existing UIKit or Android view hierarchies, and embedding native views inside Valdi layouts with `<custom-view>`.

For performance-critical or platform-specific code, the README lists polyglot modules written in C++, Swift, Kotlin or Objective-C with type-safe bindings to TypeScript.

Embed Valdi in native: see the native bindings guide in the docs
Embed native in Valdi: use <custom-view> in your layout
Polyglot modules: C++, Swift, Kotlin or Objective-C

Know the build, debug and testing tools

Valdi builds use Bazel for reproducible, incremental builds. The README also lists full VSCode debugging, which covers breakpoints, variable inspection, profiling and heap dumps. A built-in testing framework supports component-level unit tests.

The README says no Valdi-specific editor extension is needed. For editor setup, it points to the VSCode/Cursor setup section of the install guide, which covers using the workspace TypeScript version.

Bazel integration for builds
VSCode debugging with breakpoints and profiling
Component-level unit tests
Editor setup: see the VSCode/Cursor section of the install guide

Explore the example apps

The apps directory in the repository contains runnable examples. Start with helloworld for the smallest working component, then move to navigation_example or managed_context_example for screen navigation and shared state.

helloworld: minimal component
navigation_example: screen navigation patterns
managed_context_example: sharing state across components
valdi_gpt: AI-driven dynamic UI
cli_example: building a Valdi CLI application
benchmark: performance benchmarks

What people use it for

Building one UI codebase shared between iOS and Android
Adding Valdi components gradually into an existing native app
Writing screens with TypeScript and native-looking views
Using worker threads for background processing in a full-stack Valdi feature

Frequently asked questions

Is Valdi free to use?

Yes. The README says Valdi is made available under the MIT License, which is a permissive open-source licence. Check the LICENSE file in the repository for the full terms.

What are the requirements to install Valdi?

You need Node.js 18 or later, with Node.js 22 recommended. On macOS you also need Xcode 26.5 or 27. The README says valdi dev_setup installs the other dependencies.

How do I install Valdi?

Run npm install -g @snap/valdi to install the Valdi CLI, then run valdi dev_setup. Create a project folder and run valdi bootstrap inside it.

Is Valdi production ready?

The README labels Valdi as beta. It says Valdi has been used in Snap's production apps for about 8 years, but the tools and documentation still need more testing in the open-source world, and it will exit beta when the developer experience is ready.

How does Valdi compare to React Native or Flutter?

Valdi compiles TypeScript components into native views instead of web views or a JavaScript bridge. React Native, Flutter and Kotlin Multiplatform are often compared with it, but this guide does not benchmark them, so test each against your own needs.

Where can I get help with Valdi?

The README points to GitHub Discussions for questions and to GitHub Issues for bug reports and feature requests. The docs include a Frequently Asked Questions page and an API reference.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Valdi suits mobile teams that know TypeScript and want one UI codebase for iOS and Android, or want to add Valdi components into an existing native app step by step. Teams that need a stable, fully supported release or a mature community should wait for it to leave beta or choose a more established option such as React Native or Flutter.

Install options & downloads