Skip to content

INSTALL.md

Latest commit

 

History

History
191 lines (134 loc) · 5.51 KB

INSTALL.md

File metadata and controls

191 lines (134 loc) · 5.51 KB

Getting Started with Valdi

Install the Valdi CLI from npm. This guide assumes you install the CLI with npm install -g @snap/valdi. If you are contributing to Valdi itself, see DEV_SETUP.md instead.

This guide will help you set up your development environment and get started with your first project.

Prerequisites

macOS

Install Xcode from the App Store - this is required for iOS development.

Linux

No prerequisites! The Valdi CLI will install everything you need.

All Platforms

That's it! The valdi dev_setup command handles all other dependencies automatically, including:

  • Homebrew (macOS)
  • Bazelisk
  • Java JDK 17
  • Android SDK command-line tools
  • Git LFS
  • Watchman
  • Shell autocomplete, JDK symlink (macOS), Android env vars, and platform-specific extras (e.g. ios-webkit-debug-proxy on macOS; adb, zlib/fontconfig dev libs on Linux)

Tip

For manual installation details, see the macOS or Linux reference guides.

Installation

1. Install the Valdi CLI

npm install -g @snap/valdi

2. Set Up Your Development Environment

# Set up your development environment (installs all dependencies)
valdi dev_setup

# Verify everything is working
valdi doctor

Note

The first time you run valdi dev_setup, it will download and install several gigabytes of dependencies. This may take 10-20 minutes depending on your internet connection.

Tip

Contributing to Valdi? If you're developing Valdi itself (not just using it), clone the repository and install from source:

git clone git@github.com:Snapchat/Valdi.git
cd Valdi/npm_modules/cli/
npm run cli:install

Creating Your First Project

The best way to start a new project is to bootstrap it using the Valdi CLI. The bootstrap command will create all of the necessary directories, source, and configuration files.

1. Bootstrap a New Project

# Create and enter your project directory
mkdir my_project
cd my_project

# Initialize a new Valdi project
valdi bootstrap

This will create all necessary files for a new Valdi project in your current directory.

2. Run Your Project

Choose your target platform and install dependencies:

# For iOS
valdi install ios

# For Android
valdi install android

Note

The first build may take several minutes as it sets up the bazel WORKSPACE.

3. Enable Hot Reloading

Once your app is running in a simulator or emulator, start the hot reloader to see your changes in real-time:

valdi hotreload

VSCode/Cursor Setup (Optional but Recommended)

Valdi provides editor extensions for syntax highlighting, debugging, and device logs during hot reload.

1. Install VSCode or Cursor

2. Add Shell Command to PATH

For VSCode:

  • Launch VSCode
  • Open Command Palette (Cmd+Shift+P or Ctrl+Shift+P)
  • Type shell command and select > Install 'code' command in PATH
  • Restart your terminal

For Cursor:

  • Launch Cursor
  • Open Command Palette (Cmd+Shift+P or Ctrl+Shift+P)
  • Type shell command and select > Install 'cursor' command in PATH
  • Restart your terminal

3. Install Valdi Extensions

Download the extension files from the latest release:

  • valdi-vivaldi.vsix - Device logs and Valdi language support
  • valdi-debug.vsix - JavaScript debugger for Valdi apps

Install the extensions:

# For VSCode
code --install-extension /path/to/valdi-vivaldi.vsix
code --install-extension /path/to/valdi-debug.vsix

# For Cursor
cursor --install-extension /path/to/valdi-vivaldi.vsix
cursor --install-extension /path/to/valdi-debug.vsix

4. Configure TypeScript

After creating your first Valdi project:

  • Open any TypeScript file (.tsx) in your project
  • Press Cmd+Shift+P (or Ctrl+Shift+P)
  • Select "TypeScript: Select TypeScript Version..."
  • Choose Use Workspace Version

Important

Selecting the workspace TypeScript version is crucial for proper development and cannot be automated.

Project Synchronization

When you make changes to any of the following:

  • Dependencies
  • Localization files
  • Resource files

Run this command to update your project configuration:

valdi projectsync

Troubleshooting

If you encounter any issues during setup:

  1. Run diagnostics:

    valdi doctor

    This will check your environment and provide specific fix suggestions.

  2. Check prerequisites:

    • macOS: Ensure Xcode is installed and configured (sudo xcode-select -s /Applications/Xcode.app)
    • All platforms: Ensure you have a stable internet connection for downloading dependencies

  3. Review detailed setup guides:

  4. Get help:

Next Steps

Ready to start building? Check out: