Skip to content

feat(plugins): add default start commands for better discoverability#47

Open
abueide wants to merge 2 commits intomainfrom
feat/add-default-start-commands
Open

feat(plugins): add default start commands for better discoverability#47
abueide wants to merge 2 commits intomainfrom
feat/add-default-start-commands

Conversation

@abueide
Copy link
Copy Markdown
Contributor

@abueide abueide commented Apr 29, 2026

Summary

Adds convenience devbox run commands to all plugins for better out-of-the-box developer experience:

Android Plugin:

  • devbox run start:android - Full workflow (start emulator, build, deploy)

iOS Plugin:

  • devbox run start:ios - Full workflow (start simulator, build, deploy)

React Native Plugin:

  • devbox run start:metro - Start Metro bundler
  • devbox run stop:metro - Stop Metro bundler
  • devbox run start:android - Full Android workflow
  • devbox run start:ios - Full iOS workflow

Problem

Previously, users had to:

  1. Manually define these commands in every project's devbox.json
  2. Remember the CLI script names (android.sh run, ios.sh run, metro.sh start)
  3. Commands weren't discoverable via devbox run --list

Solution

Plugin-Provided Defaults

Commands are now built into the plugins and work immediately for simple projects:

# Works out-of-the-box (just needs build:android or build script defined)
devbox run start:android

# Also works
devbox run start:ios
devbox run start:metro

Still Overridable

Projects can override for custom workflows:

{
  "shell": {
    "scripts": {
      "start:android": [
        "process-compose -f dev-android.yaml --tui=${DEVBOX_TUI:-false}"
      ]
    }
  }
}

Clear Error Messages

Already implemented in the CLI scripts:

When no build script exists:

ERROR: No build:android or build script found in devbox.json.
Define a build script using native tools (e.g., gradle assembleDebug).

When no APK/.app artifact found:

ERROR: No APK found. Searched: ANDROID_APP_APK env var, project root, current directory.
Set ANDROID_APP_APK in devbox.json env, or pass a path: android.sh run /path/to/app.apk
See: plugins/android/REFERENCE.md for APK resolution details.

Build Detection

The commands automatically detect and use:

  1. Platform-specific scripts first: build:android, build:ios
  2. Generic fallback: build
  3. Clear error if neither exists

Benefits

  1. Better discoverability - Commands appear in devbox run --list
  2. Consistent UX - Same command names across all projects using the plugins
  3. Works immediately - No config needed for simple projects with build scripts
  4. Still flexible - Full override capability for complex workflows
  5. Clear errors - Helpful messages guide users when build scripts or artifacts are missing

Testing

  • Error messages verified in android.sh run and ios.sh run
  • Build detection logic already implemented (tries platform-specific, then generic)
  • README files updated with new command examples
  • Will test in analytics-react-native after merge

Documentation Updates

  • Updated plugins/android/README.md quickstart
  • Updated plugins/ios/README.md quickstart
  • Updated plugins/react-native/README.md with full command reference

🤖 Generated with Claude Code

abueide added 2 commits April 29, 2026 15:44
Add convenience commands to plugin.json files:
- Android: 'devbox run start:android' - Full workflow (start emulator, build, deploy)
- iOS: 'devbox run start:ios' - Full workflow (start simulator, build, deploy)
- React Native: 'devbox run start:metro/stop:metro' - Metro bundler management
- React Native: Includes start:android and start:ios from composed plugins

These commands provide better discoverability via 'devbox run --list' and
work out-of-the-box for simple projects while remaining overridable.

Error handling:
- android.sh run and ios.sh run already provide clear error messages
- When no build:android/build:ios script exists, shows: 'No build:android or build script found in devbox.json'
- When no APK/.app artifact found, shows detailed resolution paths and suggests IOS_APP_ARTIFACT/ANDROID_APP_APK env vars
- Build detection tries platform-specific scripts first (build:android, build:ios), then falls back to generic 'build'

Benefits:
- Works immediately for projects with build scripts defined
- Consistent command names across all plugin users
- Still fully overridable for complex workflows (e.g., process-compose orchestration)
- Better developer experience via clear, predictable command names
Update quickstart examples to use the new default commands:
- start:android (was start-android)
- start:ios (new)
- start:metro / stop:metro (new)

Clarify that these commands require build scripts defined in devbox.json.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant