Managed Workflow

Vue Native's managed workflow provides a low-config development experience similar to Expo. The CLI handles iOS and Android project scaffolding, native project generation, simulator management, and hot reload.

Creating a Project

npx @thelacanians/vue-native-cli create my-app
cd my-app
bun install

Templates

Use --template to start with a pre-configured layout:

# Blank app with a single screen (default)
vue-native create my-app --template blank

# Tab-based navigation with two screens
vue-native create my-app --template tabs

# Drawer navigation with sidebar menu
vue-native create my-app --template drawer

Template contents:

All templates include:

• Complete iOS Xcode project (ios/) with XcodeGen spec
• Complete Android Gradle project (android/) with Kotlin
• Vite configuration with Vue Native plugin
• TypeScript configuration
• vue-native.config.ts configuration file
• .gitignore with common exclusions

Project Configuration

Configure your app with vue-native.config.ts in the project root:

import { defineConfig } from '@thelacanians/vue-native-cli'

export default defineConfig({
  name: 'MyApp',
  bundleId: 'com.example.myapp',
  version: '1.0.0',
  ios: {
    deploymentTarget: '16.0',
  },
  android: {
    minSdk: 21,
    targetSdk: 35,
  },
})

The CLI validates this file on dev, run, and build. bundleId, ios.scheme, and android.packageName provide launch/build defaults. Native deployment targets are written into the generated Xcode/Gradle files at scaffold time; if you change those values later, update the native project too.

Configuration Reference

Development Server

vue-native dev

Starts the Vite build watcher and WebSocket hot reload server. The app on your simulator or device will reload automatically when you save changes.

Options

Auto-launching Simulators

# Auto-detect and boot an iOS simulator
vue-native dev --ios

# Boot a specific simulator
vue-native dev --ios --simulator "iPhone 16 Pro"

# Detect Android emulator
vue-native dev --android

# Build a macOS development bundle
vue-native dev --platform macos

Each development bundle has one compile-time platform target. Run separate dev commands when switching targets; --ios --android is rejected. A --platform value must also match any --ios or --android launch flag.

When using --ios, the CLI will:

1. Query available simulators via xcrun simctl list
2. Boot an available iPhone simulator (or the specified one)
3. Open Simulator.app
4. Start the hot reload server

When using --android, the CLI will check for connected devices/emulators via adb devices.

Building and Running

# Build JS bundle and run on iOS simulator
vue-native run ios

# Build and run on Android emulator
vue-native run android

# Run on a physical device
vue-native run ios --device

Run Options

Project Structure

After vue-native create, your project looks like:

my-app/
  app/                   # Vue 3 source code
    main.ts              # Entry point
    App.vue              # Root component
    pages/               # Screen components
      Home.vue
  ios/                   # iOS native project
    project.yml          # XcodeGen specification
    Sources/
      AppDelegate.swift
      SceneDelegate.swift
      Info.plist
  android/               # Android native project
    app/
      build.gradle.kts
      src/main/
        AndroidManifest.xml
        kotlin/.../MainActivity.kt
    build.gradle.kts
    settings.gradle.kts
  dist/                  # Built JS bundle (generated)
  vue-native.config.ts   # App configuration
  vite.config.ts         # Vite build config
  package.json
  tsconfig.json

Typical Workflow

1. Create a project: vue-native create my-app --template tabs
2. Install dependencies: cd my-app && bun install
3. Develop with hot reload: vue-native dev --ios
4. Edit Vue components in app/ -- changes appear instantly
5. Build for testing: vue-native run ios or vue-native run android
6. Release via Xcode (iOS) or Gradle (Android)