Project Structure

A project created with flutter create holds your Dart code, package configuration and one native project per platform. This chapter explains what each file and folder does and how to manage dependencies and assets.

The big picture

hello_app/
├── lib/
│   └── main.dart          # App entry point
├── test/
│   └── widget_test.dart   # Default widget test
├── android/               # Android project (Gradle)
├── ios/                   # iOS project (Xcode)
├── web/                   # index.html, icons, manifest
├── windows/               # Windows desktop (CMake)
├── macos/                 # macOS desktop (Xcode)
├── linux/                 # Linux desktop (CMake)
├── pubspec.yaml           # Package configuration
├── pubspec.lock           # Resolved dependency versions
└── analysis_options.yaml  # Static analysis (lint) rules

build/ and .dart_tool/ are generated during builds and stay out of version control; the generated .gitignore already excludes them.

lib: your app code

All Dart code for the app lives under lib. It starts with just main.dart; as the app grows you split it by screens, widgets and data layers. Flutter does not enforce a layout, but this one is common:

lib/
├── main.dart
├── app.dart              # MaterialApp, theme, routing
├── screens/              # One widget per screen
│   ├── home_screen.dart
│   └── detail_screen.dart
├── widgets/              # Widgets shared across screens
├── models/               # Data classes
└── services/             # API clients, storage

Import other files with package paths. If the name in pubspec.yaml is hello_app:

import 'package:flutter/material.dart';
import 'package:hello_app/screens/home_screen.dart';
import 'package:hello_app/models/todo.dart';

Dart convention is snake_case for file names (home_screen.dart) and UpperCamelCase for classes (HomeScreen).

pubspec.yaml: package configuration

pubspec.yaml declares the app name, version, Dart SDK constraint, dependencies and assets.

name: hello_app
description: "A new Flutter project."
publish_to: 'none'
version: 1.0.0+1

environment:
  sdk: ^3.5.0

dependencies:
  flutter:
    sdk: flutter
  cupertino_icons: ^1.0.8
  http: ^1.2.0

dev_dependencies:
  flutter_test:
    sdk: flutter
  flutter_lints: ^5.0.0

flutter:
  uses-material-design: true
  assets:
    - assets/images/
    # Single files can be listed too
    - assets/data/config.json

The version numbers above are only examples; flutter create and flutter pub add fill in current versions. In version: 1.0.0+1, the part before + is the user-facing version name and the part after it is the build number the stores use.

Find packages on pub.dev and add them from the command line:

# Add a dependency (updates pubspec.yaml for you)
flutter pub add http

# Add a dev dependency
flutter pub add --dev mocktail

# Fetch packages after editing pubspec.yaml by hand
flutter pub get

# See which packages have newer versions
flutter pub outdated

pubspec.lock records the exact versions that were resolved. For apps, commit it so every developer and CI machine builds with the same versions.

Assets: images, fonts and data files

Files bundled with the app must be listed under flutter: assets: in pubspec.yaml. A folder entry ending in / includes every file directly inside it; subfolders must be listed separately.

import 'dart:convert';
import 'package:flutter/services.dart' show rootBundle;

// Show an image asset
Image.asset('assets/images/logo.png', width: 120);

// Read a text or JSON asset
Future<Map<String, dynamic>> loadConfig() async {
  final text = await rootBundle.loadString('assets/data/config.json');
  return jsonDecode(text) as Map<String, dynamic>;
}

Custom fonts go under flutter: fonts: with a family name and file paths, and are used via TextStyle(fontFamily: 'Name').

Platform folders

android, ios, web, windows, macos and linux are real native projects. You rarely touch them, except for things like:

• App name, icon and permissions: android/app/src/main/AndroidManifest.xml on Android, ios/Runner/Info.plist on iOS
• Android application ID, minimum SDK and signing: android/app/build.gradle.kts (build.gradle in older projects)
• iOS bundle identifier and signing: open ios/Runner.xcworkspace in Xcode
• Web page title and PWA metadata: web/index.html and web/manifest.json

To add a platform later, run flutter create --platforms=web,windows . inside the project.

analysis_options.yaml

This file pulls in the recommended rules from the flutter_lints package. flutter analyze reports lint violations and likely bugs, and your editor shows the same results as you type. Run dart format . to format the code.

Summary

• Dart code lives in lib, tests in test, and each platform has its own native project folder.
• pubspec.yaml holds dependencies, version, assets and fonts; add packages with flutter pub add.
• Assets are only bundled when listed in pubspec.yaml.
• Permissions, icons and signing are configured in the relevant platform folder.