Install Neo

Neo is a private Flutter package. You add it to a normal Flutter app: create the project with Flutter, then wire Neo into pubspec.yaml, analysis options, and main.dart.

Prefer an agent to do this? Install Neo Skills and run /create-neo-project. The skill detects whether you are in an empty folder, a projects root, or an existing Flutter app, shows a plan, and waits for confirmation before it changes anything.

Prerequisites

Flutter installed and on your PATH (Flutter installation guide). Use fvm if the project already has .fvmrc or .fvm/.
Access to the Neo repository granted by TVK through the GitHub organization.
SSH keys for GitHub, because Neo is pulled over SSH.

If you don’t have access yet, ask your team lead or administrator to contact TVK with your GitHub account email address. Your organization needs an active Neo subscription with confirmed payment before developers can receive repository access.

SSH setup

Check for existing keys: ls -al ~/.ssh
Generate a key if needed: GitHub’s SSH guide
Add the key to your GitHub account

New Flutter project

Create the app with Flutter, then apply Add Neo in the project folder.

Terminal

flutter create --org com.example --project-name my_app --platforms ios,android,web,macos my_app
cd my_app

To create the project in the current empty directory, pass . as the last argument instead of a folder name.

Existing Flutter project

Skip flutter create. Apply Add Neo in the app that already has a pubspec.yaml. Do not replace existing screens with a starter. Keep your current router if it already provides a RouterConfig; NeoApp requires one.

Add Neo

1. Dependency and fonts

Add Neo from Git and register the bundled fonts. Use ref: production unless you have a reason to pin a tag.

pubspec.yaml

dependencies:
  flutter:
    sdk: flutter
  neo:
    git:
      url: git@github.com:tvkcompany/neo.git
      ref: production
  auto_route: ^11.0.0
  flutter_hooks: ^0.21.2
  gap: ^3.0.1
  hooks_riverpod: ^3.4.2
  phosphoricons_flutter: ^1.0.0
  riverpod_annotation: ^4.0.6

dev_dependencies:
  flutter_test:
    sdk: flutter
  auto_route_generator: ^10.0.0
  build_runner: ^2.16.0
  riverpod_generator: ^4.0.8

flutter:
  fonts:
    - family: Inter
      fonts:
        - asset: packages/neo/assets/fonts/inter_variable.ttf
        - asset: packages/neo/assets/fonts/inter_variable_italic.ttf
          style: italic
    - family: Geist Mono
      fonts:
        - asset: packages/neo/assets/fonts/geist_mono_variable.ttf
        - asset: packages/neo/assets/fonts/geist_mono_italic_variable.ttf
          style: italic

Then install packages:

Terminal

flutter pub get

You can add the non-Git packages with flutter pub add instead of editing pubspec.yaml by hand. Neo itself must stay a Git dependency.

2. Analyzer

Append these settings to analysis_options.yaml so Riverpod annotations and formatting match Neo’s conventions:

analysis_options.yaml

analyzer:
  errors:
    invalid_annotation_target: ignore

formatter:
  trailing_commas: preserve

3. App shell

Replace Flutter’s default MaterialApp / CupertinoApp with NeoInitializer, ProviderScope, and NeoApp. New projects can use this router and welcome screen as-is. Existing projects should keep their screens and only wrap the root.

lib/main.dart

import 'package:flutter/widgets.dart';
import 'package:hooks_riverpod/hooks_riverpod.dart';
import 'package:neo/neo.dart';

import 'router/app_router.dart';

void main() {
  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 appRouter = ref.watch(routerProvider);

    return NeoApp(
      title: "My App",
      defaultThemeMode: .system,
      routerConfig: appRouter.config(),
    );
  }
}

lib/router/app_router.dart

import 'package:auto_route/auto_route.dart';
import 'package:riverpod_annotation/riverpod_annotation.dart';

import 'app_router.gr.dart';

part 'app_router.g.dart';

@Riverpod(keepAlive: true)
AppRouter router(Ref ref) {
  return AppRouter(ref);
}

@AutoRouterConfig(replaceInRouteName: 'Screen,Route')
class AppRouter extends RootStackRouter {
  final Ref ref;

  AppRouter(this.ref);

  @override
  List<AutoRoute> get routes => [
    CustomRoute(
      path: "/",
      page: WelcomeRoute.page,
      initial: true,
    ),
    RedirectRoute(
      path: "*",
      redirectTo: "/",
    ),
  ];
}

lib/screens/welcome_screen.dart

import 'package:auto_route/auto_route.dart';
import 'package:flutter/widgets.dart';
import 'package:gap/gap.dart';
import 'package:hooks_riverpod/hooks_riverpod.dart';
import 'package:neo/neo.dart';

@RoutePage()
class WelcomeScreen extends ConsumerWidget {
  const WelcomeScreen({super.key});

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

    return Container(
      color: theme.colors.bgPrimary,
      child: NeoSafeArea(
        child: Center(
          child: Column(
            mainAxisSize: .min,
            children: [
              Text(
                "Welcome to Neo",
                style: theme.textStyles.header1.copyWith(color: theme.colors.fgPrimary),
              ),
              Gap(theme.spacings.medium),
              NeoButton(
                variant: .filled,
                label: "Get started",
                onPressed: () {},
              ),
            ],
          ),
        ),
      ),
    );
  }
}

4. Generate code

Terminal

dart run build_runner build

Then run the app:

Terminal

flutter run

Next steps

Neo Skills

Let an agent create or migrate the project with /create-neo-project, then keep it current with /update-neo

Neo Docs MCP

Give your assistant live access to these docs while you work

Widgets

Start with Neo’s pre-built components

Sidebar layout

Add navigation once the app shell is running

Troubleshooting

Permission denied (publickey) when fetching Neo

Flutter cannot clone git@github.com:tvkcompany/neo.git. Confirm SSH works with ssh -T git@github.com, that your key is on the GitHub account that has Neo access, and then run flutter pub get again.

Missing font files

Use the variable font paths above (inter_variable.ttf, geist_mono_variable.ttf). Older static .otf filenames are no longer in the package.

build_runner fails

From the project root, run dart run build_runner build after flutter pub get. Generated files such as *.g.dart and *.gr.dart are required for the router provider.

Getting Started

AI

Widgets

Layouts

Theming

Utilities

Install Neo

Prerequisites

SSH setup

New Flutter project

Existing Flutter project

Add Neo

1. Dependency and fonts

2. Analyzer

3. App shell

4. Generate code

Next steps

Neo Skills

Neo Docs MCP

Widgets

Sidebar layout

Troubleshooting

​Prerequisites

​SSH setup

​New Flutter project

​Existing Flutter project

​Add Neo

​1. Dependency and fonts

​2. Analyzer

​3. App shell

​4. Generate code

​Next steps

Neo Skills

Neo Docs MCP

Widgets

Sidebar layout

​Troubleshooting

Prerequisites

SSH setup

New Flutter project

Existing Flutter project

Add Neo

1. Dependency and fonts

2. Analyzer

3. App shell

4. Generate code

Next steps

Troubleshooting