Lesson 0001 • Bootstrap & ProviderScope

Flutter Bootstrap, ProviderScope & Dark Workbench Shell

Translate package.json, createRoot(), React Context Providers, and React Testing Library into pubspec.yaml, runApp(), ProviderScope, StatelessWidget, and WidgetTester.

Why Start at the Entrypoint?

When you open a React + TypeScript codebase for the first time, your eyes immediately look for three files: package.json (what libraries are installed?), tsconfig.json (how strict is the compiler?), and src/main.tsx (what wraps <App /> inside createRoot(...).render(...)?).

In our Electronics Parts Tracker repository, those exact same roles are played by pubspec.yaml, analysis_options.yaml, and lib/main.dart. In this first lesson, you will build and verify the runnable application foundation in ./tutorial/apps/0001-flutter-bootstrap-and-provider-scope/:

  1. Configure pubspec.yaml and analysis_options.yaml with flutter_riverpod and flutter_lints.
  2. Write lib/main.dart with WidgetsFlutterBinding.ensureInitialized(), ProviderScope, PartsTrackerApp, the cyan-accented Material 3 dark theme (#00E5FF on #0E1318), and an initial WorkbenchScreen shell.
  3. Verify the rendered UI headlessly in under two seconds using flutter analyze and flutter test (WidgetTester).

1. Project Manifest & Static Analysis (pubspec.yaml & analysis_options.yaml)

In a React + TypeScript project, package.json lists runtime dependencies and devDependencies, while tsconfig.json and eslint.config.js configure typechecking and lint rules. In Flutter, Dart's package manager (pub), compiler, static analyzer, and test runner are all built into a single flutter CLI tool.Unlike Node.js where typescript, eslint, and vitest are separate third-party packages, Dart ships its sound type checker, linter, formatter (dart format), and test runner directly inside the SDK.

Block 1: Declaring Dependencies in pubspec.yaml

Here is the minimal pubspec.yaml for our Lesson 0001 companion app:

tutorial/apps/0001-flutter-bootstrap-and-provider-scope/pubspec.yaml
name: parts_tracker_skilled
description: "Electronics Parts Tracker companion app (Lesson 0001)."
publish_to: 'none'
version: 1.0.0+1

environment:
  sdk: ^3.13.7

dependencies:
  flutter:
    sdk: flutter
  cupertino_icons: ^1.0.8
  flutter_riverpod: ^3.4.3

dev_dependencies:
  flutter_test:
    sdk: flutter
  flutter_lints: ^6.0.0

flutter:
  uses-material-design: true

Block 2: Configuring the Analyzer in analysis_options.yaml

tutorial/apps/0001-flutter-bootstrap-and-provider-scope/analysis_options.yaml
include: package:flutter_lints/flutter.yaml

analyzer:
  exclude:
    - build/**
    - ios/**

linter:
  rules:

2. Building lib/main.dart Block by Block

In React, you mount your application by passing a JSX tree into createRoot(document.getElementById('root')!).render(...), wrapping your root component in context providers (like <QueryClientProvider> or <ReduxProvider>), and rendering a <ThemeProvider> inside your App component.

Let's see how our Electronics Parts Tracker expresses that exact architecture in Dart and Flutter.

flowchart TD
  subgraph ReactApp["React + TypeScript (main.tsx)"]
    RMain["createRoot(rootEl).render(...)"] --> RScope["&lt;QueryClientProvider&gt; / &lt;Provider&gt;"]
    RScope --> RApp["&lt;PartsTrackerApp /&gt;"]
    RApp --> RTheme["&lt;ThemeProvider theme={darkTheme}&gt;"]
    RTheme --> RScreen["&lt;WorkbenchScreen /&gt;"]
  end
  subgraph FlutterApp["Flutter + Riverpod (lib/main.dart)"]
    FMain["void main() → runApp(...)"] --> FScope["const ProviderScope(...)"]
    FScope --> FApp["const PartsTrackerApp()"]
    FApp --> FTheme["MaterialApp(themeMode: ThemeMode.dark)"]
    FTheme --> FScreen["const WorkbenchScreen()"]
  end
Figure 1.1: Side-by-side startup flow in React + TypeScript vs. Flutter + Riverpod.

Block 1: Imports and the main() Entrypoint

Imports and main() entrypoint in lib/main.dart
import 'package:flutter/material.dart';
import 'package:flutter_riverpod/flutter_riverpod.dart';

void main() {
  WidgetsFlutterBinding.ensureInitialized();
  runApp(
    const ProviderScope(
      child: PartsTrackerApp(),
    ),
  );
}

Block 2: PartsTrackerApp (StatelessWidget & Dark Theme)

In React, a component with no local state is a function function PartsTrackerApp(props: Props): JSX.Element. In Flutter, it is a class that extends StatelessWidget:

PartsTrackerApp StatelessWidget and Material 3 dark theme configuration
class PartsTrackerApp extends StatelessWidget {
  const PartsTrackerApp({super.key});

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'Electronics Parts Tracker',
      debugShowCheckedModeBanner: false,
      themeMode: ThemeMode.dark,
      darkTheme: ThemeData(
        useMaterial3: true,
        colorScheme: ColorScheme.fromSeed(
          seedColor: const Color(0xFF00E5FF),
          brightness: Brightness.dark,
        ),
        scaffoldBackgroundColor: const Color(0xFF0E1318),
      ),
      home: const WorkbenchScreen(),
    );
  }
}

Let's unpack every Dart idiom in those 20 lines through a React + TypeScript lens:

Block 3: The Initial WorkbenchScreen Shell

Before we wire up our Freezed catalog models and Riverpod providers in the upcoming lessons, PartsTrackerApp needs a WorkbenchScreen widget to mount as its home: route:

Initial WorkbenchScreen shell in lib/main.dart
class WorkbenchScreen extends StatelessWidget {
  const WorkbenchScreen({super.key});

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: const Text('Electronics Parts Tracker'),
      ),
      body: const Center(
        child: Text('Workbench Ready — 0 parts cataloged'),
      ),
    );
  }
}

Complete lib/main.dart Listing

Here is the complete, runnable lib/main.dart for Lesson 0001 with all three blocks combined:

tutorial/apps/0001-flutter-bootstrap-and-provider-scope/lib/main.dart
import 'package:flutter/material.dart';
import 'package:flutter_riverpod/flutter_riverpod.dart';

void main() {
  WidgetsFlutterBinding.ensureInitialized();
  runApp(
    const ProviderScope(
      child: PartsTrackerApp(),
    ),
  );
}

class PartsTrackerApp extends StatelessWidget {
  const PartsTrackerApp({super.key});

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'Electronics Parts Tracker',
      debugShowCheckedModeBanner: false,
      themeMode: ThemeMode.dark,
      darkTheme: ThemeData(
        useMaterial3: true,
        colorScheme: ColorScheme.fromSeed(
          seedColor: const Color(0xFF00E5FF),
          brightness: Brightness.dark,
        ),
        scaffoldBackgroundColor: const Color(0xFF0E1318),
      ),
      home: const WorkbenchScreen(),
    );
  }
}

class WorkbenchScreen extends StatelessWidget {
  const WorkbenchScreen({super.key});

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: const Text('Electronics Parts Tracker'),
      ),
      body: const Center(
        child: Text('Workbench Ready — 0 parts cataloged'),
      ),
    );
  }
}

Interactive Simulator: React Tree vs. Flutter Widget & Element Tree

Click Any Node to Inspect

Select each layer of lib/main.dart below to compare its React + TypeScript counterpart, its BuildContext (Element) role, and when Flutter rebuilds it:


3. Writing Your First Headless Widget Test (test/widget_test.dart)

In React, you test components using Vitest/Jest + React Testing Library (render(<App />), screen.getByText(...), expect(...).toBeInTheDocument()). In Flutter, package:flutter_test provides testWidgets, which mounts your real widget tree inside a headless, deterministic frame clock driven by a WidgetTester.

Block 1: Imports and testWidgets Harness

Mounting PartsTrackerApp inside ProviderScope with WidgetTester
import 'package:flutter/material.dart';
import 'package:flutter_riverpod/flutter_riverpod.dart';
import 'package:flutter_test/flutter_test.dart';
import 'package:parts_tracker_skilled/main.dart';

void main() {
  testWidgets(
    'PartsTrackerApp boots inside ProviderScope with dark theme and WorkbenchScreen shell',
    (WidgetTester tester) async {
      await tester.pumpWidget(
        const ProviderScope(
          child: PartsTrackerApp(),
        ),
      );

Block 2: Querying the Tree with find and findsOneWidget

Asserting rendered text and Material 3 dark theme colors
      expect(find.text('Electronics Parts Tracker'), findsOneWidget);
      expect(find.text('Workbench Ready — 0 parts cataloged'), findsOneWidget);

      final materialApp = tester.widget<MaterialApp>(find.byType(MaterialApp));
      expect(materialApp.themeMode, ThemeMode.dark);
      expect(
        materialApp.darkTheme?.scaffoldBackgroundColor,
        const Color(0xFF0E1318),
      );
    },
  );
}

Complete test/widget_test.dart Listing

tutorial/apps/0001-flutter-bootstrap-and-provider-scope/test/widget_test.dart
import 'package:flutter/material.dart';
import 'package:flutter_riverpod/flutter_riverpod.dart';
import 'package:flutter_test/flutter_test.dart';
import 'package:parts_tracker_skilled/main.dart';

void main() {
  testWidgets(
    'PartsTrackerApp boots inside ProviderScope with dark theme and WorkbenchScreen shell',
    (WidgetTester tester) async {
      await tester.pumpWidget(
        const ProviderScope(
          child: PartsTrackerApp(),
        ),
      );

      expect(find.text('Electronics Parts Tracker'), findsOneWidget);
      expect(find.text('Workbench Ready — 0 parts cataloged'), findsOneWidget);

      final materialApp = tester.widget<MaterialApp>(find.byType(MaterialApp));
      expect(materialApp.themeMode, ThemeMode.dark);
      expect(
        materialApp.darkTheme?.scaffoldBackgroundColor,
        const Color(0xFF0E1318),
      );
    },
  );
}

4. Interactive Practice & Verification

Interactive Lab: Complete the Flutter & Riverpod Entrypoint

Skill Practice • Tight Feedback Loop

Fill in the missing Dart and Flutter identifiers below from memory to wire main(), ProviderScope, PartsTrackerApp, and the testWidgets assertion:

void main() {
  WidgetsFlutterBinding.ensureInitialized();
  runApp(
    const (
      child: PartsTrackerApp(),
    ),
  );
}

class PartsTrackerApp extends  {
  const PartsTrackerApp({});

  @override
  Widget build( context) {
    return const MaterialApp(
      home: WorkbenchScreen(),
    );
  }
}

// Inside testWidgets:
expect(find.text('Electronics Parts Tracker'), );

:::prompts hint: "Review Complete lib/main.dart Listing and Complete test/widget_test.dart Listing above: Riverpod's root container is ProviderScope, stateless components extend StatelessWidget with {super.key} and build(BuildContext context), and flutter_test checks single presence with findsOneWidget." success: "Spot on! You've nailed the five core building blocks of a Flutter + Riverpod entrypoint and widget test."

:::

Retrieval Practice: React & TypeScript vs. Flutter & Dart Bootstrap

3 Questions • Equal-Length Options
1. In Flutter, how does a StatelessWidget constructor like const PartsTrackerApp({super.key}) compare to React component rendering?
2. Why do we wrap PartsTrackerApp inside const ProviderScope(child: PartsTrackerApp()) in both main() and testWidgets?
3. What role does the BuildContext parameter in Widget build(BuildContext context) play compared to React?

Verification Lab: Analyze & Test Lesson 0001 Companion App

CLI Gate • Zero Warnings & 100% Green

Run the Dart static analyzer and headless widget test suite inside tutorial/apps/0001-flutter-bootstrap-and-provider-scope:

Terminal verification commands for Lesson 0001
cd tutorial/apps/0001-flutter-bootstrap-and-provider-scope
flutter analyze
flutter test

Expected terminal output:

Verified output of flutter analyze && flutter test
Analyzing 0001-flutter-bootstrap-and-provider-scope...
No issues found!
00:01 +1: All tests passed!

Check off each verification gate once you have reviewed or run the companion app: