> ## Documentation Index
> Fetch the complete documentation index at: https://neo.tvk.company/llms.txt
> Use this file to discover all available pages before exploring further.

# App

> The root application widget that provides theme management, routing, and essential Neo framework functionality. Wraps Flutter's CupertinoApp with Neo-specific features.

<Note>
  **CLI Setup**: If you create a new Neo project using the [Neo CLI](/cli/commands), NeoApp will be fully configured for you inside `main.dart` with proper initialization, theming, and routing setup.
</Note>

<Note>
  **Placement Note**: While currently categorized under utilities, NeoApp may be reorganized into a more appropriate category in future releases as we refine our documentation structure and terminology.
</Note>

## Example

<CodeGroup>
  ```dart Complete Setup lines focus={26-29} theme={null}
  import 'package:flutter/widgets.dart';
  import 'package:neo/neo.dart';
  import 'package:hooks_riverpod/hooks_riverpod.dart';

  import 'router/neo_router.dart';

  void main() async {
    WidgetsFlutterBinding.ensureInitialized();

    NeoInitializer.initialize().then((_) {
      runApp(
        ProviderScope(
          child: MyApp(),
        ),
      );
    });
  }

  class MyApp extends ConsumerWidget {
    const MyApp({super.key});

    @override
    Widget build(BuildContext context, WidgetRef ref) {
      final neoRouter = ref.watch(routerProvider);

      return NeoApp(
        title: "My Neo App",
        routerConfig: neoRouter.config(),
      );
    }
  }
  ```
</CodeGroup>

## Properties

### Required

<ParamField path="title" type="String" required>
  The title of the application. Used by the operating system to identify your app (e.g., in the task switcher) and as the browser tab title on web platforms.
</ParamField>

<ParamField path="routerConfig" type="RouterConfig<Object>" required>
  The router configuration for navigation. Typically an `AutoRouter` configuration from the `auto_route` package that defines your app's routes and navigation structure.
</ParamField>

### Theming

<ParamField path="defaultThemeMode" type="NeoThemeMode" default="NeoThemeMode.system">
  The initial theme mode to use when the app starts.
</ParamField>

<ParamField path="defaultLightTheme" type="NeoThemeBase" default="NeoThemeLight()">
  Custom light theme to use instead of the default Neo theme.
</ParamField>

<ParamField path="defaultDarkTheme" type="NeoThemeBase" default="NeoThemeDark()">
  Custom dark theme to use instead of the default Neo theme.
</ParamField>

## Enums

### NeoThemeMode

Controls how the app determines which theme to use.

* `system`: Automatically switches between light and dark themes based on the device's system setting. Responds to system-level theme changes in real-time.
* `light`: Always uses the light theme regardless of system settings.
* `dark`: Always uses the dark theme regardless of system settings.

## Best Practices

* **Riverpod Required**: NeoApp requires `ProviderScope` as an ancestor widget for state management. Wrap your app with `ProviderScope` in your `main()` function.

## Integration Notes

* **Initialization**: NeoApp works with `NeoInitializer.initialize()` to properly set up the Neo framework before the app starts.