auto_gen_assets 1.0.2

A Flutter package for automatically generating strongly-typed asset references from your assets directory.

auto_gen_assets

A Flutter package for automatically generating strongly-typed asset references from your assets directory.

Features

• 🔄 Automatic Generation: Scans your assets directory and generates Dart code
• 📁 Folder Organization: Groups assets by folder structure
• 🎯 Type Safety: Provides strongly-typed asset references
• ⚙️ Configurable: Customize output location and file filtering
• 🚀 Easy to Use: Simple API with sensible defaults

Installation

Add this to your package's pubspec.yaml file:

dependencies:
  auto_gen_assets: ^1.0.2

Usage

Basic Usage

1. Create an assets directory structure in your Flutter project:

assets/
├── images/
│   ├── logo.png
│   ├── background.jpg
│   └── icons/
│       ├── home.png
│       └── settings.png
├── animations/
│   ├── loading.json
│   └── success.json
└── fonts/
    ├── roboto.ttf
    └── opensans.ttf

2. Run the generator:

# Generate once
dart run auto_gen_assets

# Or with watch mode (auto-regenerate on changes)
dart run auto_gen_assets --watch

3. Use the generated assets in your Flutter code:

import 'generated/assets.dart';

class MyWidget extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return Column(
      children: [
        Image.asset(Assets.images.logo),
        Image.asset(Assets.images.icons.home),
        Lottie.asset(Assets.animations.loading),
      ],
    );
  }
}

Using Watcher (Auto-regenerate on changes)

After installing the package, you can use the watcher functionality:

Quick Setup (Recommended)

1. Create a simple script in your project root:

For macOS/Linux - Create watch.sh:

#!/bin/bash
dart run auto_gen_assets --watch

For Windows - Create watch.bat:

dart run auto_gen_assets --watch

2. Make it executable (macOS/Linux only):

chmod +x watch.sh

3. Start watching:

# macOS/Linux
./watch.sh

# Windows
watch.bat

Alternative: Direct commands

# Watch for changes and auto-regenerate
dart run auto_gen_assets --watch

# Generate once
dart run auto_gen_assets

What the watcher does:

• ✅ Monitors your assets/ directory for changes
• 🔄 Auto-regenerates lib/generated/assets.dart when files are added/removed/modified
• ⏱️ Debounces rapid changes to avoid excessive regeneration
• 🛑 Graceful shutdown with Ctrl+C

Example workflow:

# Terminal 1: Start watcher
./watch.sh

# Terminal 2: Add new assets
cp new_image.png assets/images/
# Watcher automatically updates lib/generated/assets.dart

# Use in your code
import 'generated/assets.dart';
Image.asset(Assets.images.newImage);

Programmatic Usage

You can also use the generator programmatically:

import 'package:auto_gen_assets/auto_gen_assets.dart';

void main() {
  const generator = AssetGenerator(
    assetsDirectory: 'assets',
    outputFile: 'lib/generated/assets.dart',
    ignoreHiddenFiles: true,
    ignoreEnvFiles: true,
  );
  
  final success = generator.generate();
  if (success) {
    print('Assets generated successfully!');
  }
}

Configuration Options

The AssetGenerator class accepts the following configuration options:

Parameter	Type	Default	Description
assetsDirectory	String	'assets'	The directory containing assets to scan
outputFile	String	'lib/generated/assets.dart'	The output file path
ignoreHiddenFiles	bool	true	Whether to ignore hidden files (starting with '.')
ignoreEnvFiles	bool	true	Whether to ignore environment files (containing '.env')

Generated Code Structure

The generator creates a structured Dart file with the following organization:

/// This file is automatically generated. DO NOT EDIT.
/// Generated by auto_gen_assets package.

class Assets {
  Assets._();

  static const Images images = Images();
  static const Animations animations = Animations();
  static const Fonts fonts = Fonts();
}

class Images {
  const Images();
  final String logo = 'assets/images/logo.png';
  final String background = 'assets/images/background.jpg';
}

class Icons {
  const Icons();
  final String home = 'assets/images/icons/home.png';
  final String settings = 'assets/images/icons/settings.png';
}

class Animations {
  const Animations();
  final String loading = 'assets/animations/loading.json';
  final String success = 'assets/animations/success.json';
}

class Fonts {
  const Fonts();
  final String roboto = 'assets/fonts/roboto.ttf';
  final String opensans = 'assets/fonts/opensans.ttf';
}

Naming Conventions

• Folder names are converted to PascalCase for class names
• File names are converted to camelCase for property names
• Underscores and hyphens in names are properly handled

Examples:

• my_folder → MyFolder (class name)
• my_file_name.png → myFileName (property name)
• user-avatar.jpg → userAvatar (property name)

Integration with Build Process

Using Watcher (Recommended)

The package includes a built-in watcher that automatically regenerates assets when files change:

# Start watching for changes
make watch

# Or directly with dart
dart run bin/watch_assets.dart

The watcher will:

• ✅ Monitor the assets directory for any changes
• 🔄 Automatically regenerate assets.dart when files are added/modified/removed
• ⏱️ Debounce rapid changes to avoid excessive regeneration
• 🛑 Gracefully handle Ctrl+C to stop watching

Using build_runner

Add to your pubspec.yaml:

dev_dependencies:
  build_runner: ^2.4.7
  build: ^2.4.1

Create a build script:

// build.yaml
targets:
  $default:
    builders:
      auto_gen_assets|asset_builder:
        enabled: true
        options:
          assets_directory: assets
          output_file: lib/generated/assets.dart

Using Makefile

The project includes a Makefile with convenient commands:

# Generate assets once
make generate

# Watch for changes (auto-regenerate)
make watch

# Clean generated files
make clean

# Run tests
make test

# Show all available commands
make help

Examples

Complete Example Project

// lib/main.dart
import 'package:flutter/material.dart';
import 'generated/assets.dart';

void main() {
  runApp(MyApp());
}

class MyApp extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'Auto Gen Assets Demo',
      home: MyHomePage(),
    );
  }
}

class MyHomePage extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: Text('Auto Gen Assets Demo'),
      ),
      body: Center(
        child: Column(
          mainAxisAlignment: MainAxisAlignment.center,
          children: [
            Image.asset(
              Assets.images.logo,
              width: 200,
              height: 200,
            ),
            SizedBox(height: 20),
            Text(
              'Assets loaded successfully!',
              style: TextStyle(fontSize: 18),
            ),
          ],
        ),
      ),
    );
  }
}

Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Changelog

See CHANGELOG.md for a list of changes and version history.