Quick Start Guide

This guide takes you through creating your first Neon Framework project, launching the development server, running the native Android/iOS shell, and experimenting with Hot Reload.

1. Create a New Project

Use the neon create command to scaffold a project:

neon create my_neon_app --template app

Template Options:

  • --template app (Default): Full starter app featuring a multi-screen architecture, reactive state management, and sample UI controls.
  • --template minimal: A lightweight single-file starter app with a single StatelessWidget.

Navigate into your new project directory:

cd my_neon_app
dart pub get

2. Project Directory Anatomy

A Neon project combines a clean Dart logic layer with native platform shells:

my_neon_app/
├── lib/
│   ├── main.dart               # NeonApp.run() initialization
│   └── screens/
│       ├── home_screen.dart    # Primary screen widget
│       └── settings_screen.dart
├── android/                    # Native Android Gradle project
│   ├── app/
│   │   ├── src/main/kotlin/com/neon/myapp/MainActivity.kt
│   │   └── build.gradle
│   ├── build.gradle
│   └── gradlew
├── NeonApp/                    # Native iOS Xcode project
│   ├── NeonApp.xcodeproj
│   └── NeonApp/
│       ├── ViewController.swift # UIKit JSON tree renderer
│       └── AppDelegate.swift
├── neon.yaml                   # Framework settings & Hot Reload config
└── pubspec.yaml                # Dart dependencies (neon_framework)

3. Launching the App

Running a Neon app requires two active components:

  1. The Dart Engine Backend (serves JSON UI tree over HTTP).
  2. The Native Shell (Android APK or iOS Simulator app).

Step 3A: Start the Dart Engine Backend

Run the following command from the root of your project:

neon run
# Or directly via Dart:
# dart run lib/main.dart

You will see the startup confirmation:

[Neon Engine] Server running on http://localhost:8080
[Neon Engine] Active reload tier: State-preserving (300ms debounce)
[Neon Engine] Waiting for native shell connection...

Step 3B: Launch the Native Shell

Running on Android:

  1. Open Android Studio.
  2. Select File > Open and choose the my_neon_app/android/ directory.
  3. Wait for Gradle to sync.
  4. Select an Android Emulator or connected USB device.
  5. Click the green Run (Play) button.

Note for Android Emulator:
The Android emulator automatically communicates with the host machine's localhost through the special IP alias: http://10.0.2.2:8080.

Running on iOS (macOS):

  1. Open Xcode.
  2. Open my_neon_app/NeonApp/NeonApp.xcodeproj.
  3. Select an iOS Simulator (e.g., iPhone 15 Pro) from the target selector.
  4. Press Cmd + R to build and run.

4. Experience Hot Reload

Neon features an ultra-responsive, 3-tier Hot Reload engine:

  1. Open lib/screens/home_screen.dart in your favorite editor (VS Code, Cursor, Android Studio).
  2. Modify a widget property — for example, change button label or background color: 
    FilledButton(
  key: 'btn-explore',
  onPressed: _handlePress,
  child: Text('Explore Neon Ecosystem ✨'),
)
  3. Save the file (Cmd + S or Ctrl + S).
  4. Look at the terminal: 
    [Hot Reload] Change detected in lib/screens/home_screen.dart
[Hot Reload] UI-only reload applied in 84ms! Native shell refreshed.
  5. Your running Android or iOS device updates instantly without losing your user state!

5. Hot Reload Tiers

Neon's Hot Reload engine intelligently selects the fastest reload strategy:

| Tier | Strategy | Triggered By | Speed | | :--- | :--- | :--- | :--- | | Tier 1: UI-Only | Re-evaluates build() tree and re-serializes delta JSON | Modifying widget layout, styles, colors, or texts | < 100ms | | Tier 2: State-Preserving | Re-evaluates tree while preserving NeonSignal & State objects | Modifying internal logic, adding helper methods | < 250ms | | Tier 3: Structural Fallback | Reinitializes app state cleanly | Changing class inheritance, adding new package imports | < 600ms |

Next Steps