README.md

Devbox Plugins Documentation

Welcome to the devbox-plugins documentation. This wiki provides comprehensive guides, references, and contributor documentation for the Android, iOS, and React Native devbox plugins.

Quick Links

• New to devbox-plugins? Start with the Quick Start Guide
• Need a quick reference? Check the Cheatsheets
• Looking for API docs? Browse the Reference
• Want to contribute? Read the Contributing Guide

Documentation Structure

Guides

Step-by-step tutorials and practical workflows for using the plugins:

• Quick Start - Set up your first project
• Android Guide - Complete Android workflow
• iOS Guide - Complete iOS workflow
• React Native Guide - Complete React Native workflow
• Device Management - Managing emulators and simulators
• Testing Guide - Testing strategies and best practices
• Troubleshooting - Common issues and solutions

Cheatsheets

One-page quick references with the most common commands:

• Android Cheatsheet
• iOS Cheatsheet
• React Native Cheatsheet

Reference

Exhaustive API documentation for all public interfaces:

• Android Reference - Complete Android plugin API
• iOS Reference - Complete iOS plugin API
• React Native Reference - Complete React Native plugin API
• Environment Variables - All environment variables across plugins
• CLI Commands - All CLI commands and scripts
• Configuration - devbox.json configuration options

Project

Documentation for contributors and maintainers:

• Contributing Guide - How to contribute to the project
• Architecture - Project structure and design
• Conventions - Code and naming conventions
• Testing - Testing infrastructure and practices
• CI/CD - Continuous integration and deployment
• Release Process - Versioning and release procedures

Plugins Overview

Android Plugin

Provides reproducible Android development environments with:

• Nix-managed Android SDK
• AVD (Android Virtual Device) management
• Device definitions for min/max testing
• Project-local state (no ~/.android pollution)

Include in devbox.json:

{
  "include": ["github:segment-integrations/devbox-plugins?dir=plugins/android"]
}

iOS Plugin

Provides reproducible iOS development environments with:

• Xcode toolchain integration
• iOS Simulator management
• Device definitions for min/max testing
• Runtime auto-download support

Include in devbox.json:

{
  "include": ["github:segment-integrations/devbox-plugins?dir=plugins/ios"]
}

Requirements: macOS with Xcode installed

React Native Plugin

Composition layer over Android and iOS plugins with:

• Metro bundler management
• Parallel test execution
• Cross-platform development workflows
• Web build support

Include in devbox.json:

{
  "include": ["github:segment-integrations/devbox-plugins?dir=plugins/react-native"]
}

Key Features

• Project-Local State - All emulators, simulators, and caches are project-local, not global
• Reproducible Environments - Lock files ensure consistent SDK versions across machines
• Parallel Execution - Run multiple test suites simultaneously with --pure isolation
• Device-Driven Configuration - Define devices as JSON, sync AVDs/simulators declaratively
• CI/CD Optimized - Device filtering and platform skipping for fast CI builds

Getting Help

• Found a bug? Open an issue
• Have a question? Check Troubleshooting first
• Want to contribute? Read the Contributing Guide

Examples

Example projects are available in the repository:

• examples/android/ - Minimal Android app
• examples/ios/ - Swift package example
• examples/react-native/ - React Native app with Android, iOS, and Web

Each example includes device definitions, test suites, and build scripts.