Agent-readable docs index: /llms.txt. Full docs in one file: /llms-full.txt. Download /docs.zip to grep all markdown files locally.

AssetKamKaro

assetkamkaro is a Flutter package for optimizing your app's assets — it compresses images, finds assets you no longer reference, and reports exactly how much size you saved. You can drive it programmatically from Dart or from its command-line interface, so it fits both local workflows and CI/CD pipelines.
pub.dev
AssetKamKaro has a successor: asset_wizard. Migrating is a rename — change the dependency to asset_wizard: ^0.2.0, run dart pub get, and use the new short command dart run ak. These docs cover the original assetkamkaro package as published on pub.dev.

What it does

Smart image compression
Compress JPEG, PNG, and WebP assets with quality control — pick a low, medium, or high compression level per run.
Unused asset detection
Analysis finds assets that are never referenced, with optional cleanup via --delete-unused, plus per-file size reduction reporting.
Fast and memory-efficient
Parallel processing, memory-efficient algorithms, asset caching, and progress tracking keep large asset folders manageable.
Developer tooling
A full CLI, config.yaml configuration files, automatic backups, dry-run mode, and comprehensive error handling.
AssetKamKaro operates on your project directory: point it at a Flutter project, and it walks the assets, compresses what it can, and returns an OptimizationResult with totalSizeReduction, totalAssetsProcessed, the unusedAssets list, and a per-file compressionResults map. Because it supports dry runs and backups, you can preview and safely revert every change.
The package is published under the MIT license and depends on args, crypto, flutter, image, path, and yaml.

Quick start

This takes you from a fresh install to your first optimized asset folder. Every write operation supports dry runs and backups, so nothing here is destructive unless you ask it to be.
  1. Add the dependency
    Add assetkamkaro to your pubspec.yaml:
    dependencies:
  assetkamkaro: ^0.1.1
    Then install it:
    flutter pub get
  2. Preview with a dry run
    Before touching any files, use the CLI dry run to analyze what would change:
    dart run assetkamkaro optimize --dry-run
  3. Run your first optimization
    Create an AssetKamKaro instance and call optimize() with your project path and a compression level:
    import 'package:assetkamkaro/assetkamkaro.dart';

void main() async {
  final optimizer = AssetKamKaro();
  final result = await optimizer.optimize(
    projectPath: 'path/to/your/flutter/project',
    compressionLevel: CompressionLevel.medium,
  );

  print('Optimization complete!');
  print('Total size reduction: ${result.totalSizeReduction}');
  print('Unused assets found: ${result.unusedAssets.length}');
}
    CompressionLevel is an enum with low, medium, and high options.
  4. Read the result
    The returned OptimizationResult carries everything you need to report on the run:
    • totalSizeReduction — bytes saved across the run
    • totalAssetsProcessed — how many assets were handled
    • unusedAssets — assets never referenced in your project
    • compressionResults — a per-file map with original size, compressed size, and reduction percentage
Prefer the terminal? The same optimization is one CLI command: dart run assetkamkaro optimize --compression high. See the full flag list in the Command line interface section below.
--delete-unused removes files it considers unreferenced. Keep backup: true (the default shown throughout these docs) and review the unusedAssets list from a dry run before enabling it.

Configuration file

Create a config.yaml in your project root to make runs repeatable instead of re-passing flags:
# AssetKamKaro Configuration
compression:
  level: high  # Options: low, medium, high
  jpeg:
    quality: 80  # 0-100
    subsampling: yuv420
  png:
    level: 9  # 0-9
    filter: 0

# Directories to exclude from optimization
exclude:
  - assets/icons
  - assets/backgrounds
  - assets/raw

# Backup settings
backup: true
delete_unused: false

# Performance settings
enable_cache: true
parallel_processing: true
The compression block sets a global level plus per-format knobs — JPEG quality (0–100) and subsampling, PNG compression level (0–9) and filter. exclude keeps directories like icons or raw originals untouched, while enable_cache and parallel_processing control performance.

Command line interface

The CLI covers the same operations and is the natural fit for scripts and CI:
# Basic optimization
dart run assetkamkaro optimize

# High compression with specific settings
dart run assetkamkaro optimize \
  --compression high \
  --exclude assets/icons,assets/backgrounds \
  --backup true

# Dry run for analysis
dart run assetkamkaro optimize --dry-run

# Delete unused assets
dart run assetkamkaro optimize --delete-unused

# Custom configuration file
dart run assetkamkaro optimize --config custom_config.yaml
Use --dry-run first on any project you haven't optimized before — it reports what would change, including the unused-asset list, without writing anything.

Programmatic optimization with options

The Dart API exposes the same options as constructor and optimize() parameters, and the OptimizationResult gives you full per-file detail:
import 'package:assetkamkaro/assetkamkaro.dart';

void optimizeAssets() async {
  // Initialize the optimizer
  final optimizer = AssetKamKaro(
    enableCache: true,
  );

  try {
    // Run optimization
    final result = await optimizer.optimize(
      projectPath: Directory.current.path,
      compressionLevel: CompressionLevel.high,
      dryRun: false,
      createBackup: true,
      excludePatterns: ['assets/icons', 'assets/raw'],
    );

    // Process results
    print('Optimization Results:');
    print('- Total assets processed: ${result.totalAssetsProcessed}');
    print('- Total size reduction: ${(result.totalSizeReduction / 1024).toStringAsFixed(2)} KB');

    // Handle unused assets
    if (result.unusedAssets.isNotEmpty) {
      print('\nUnused Assets Found:');
      for (final asset in result.unusedAssets) {
        print('- $asset');
      }
    }

    // Detailed compression results
    print('\nCompression Details:');
    result.compressionResults.forEach((path, details) {
      print('$path:');
      print('  - Original: ${(details.originalSize / 1024).toStringAsFixed(2)} KB');
      print('  - Compressed: ${(details.compressedSize / 1024).toStringAsFixed(2)} KB');
      print('  - Reduction: ${details.reduction.toStringAsFixed(2)}%');
    });
  } catch (e) {
    print('Optimization failed: $e');
  }
}

Selective asset processing

You don't have to optimize everything the same way. includePatterns restricts a run to matching globs, and compressionSettings applies different settings per asset type:
void processSpecificAssets() async {
  final optimizer = AssetKamKaro();

  // Process only images in specific directories
  await optimizer.optimize(
    projectPath: Directory.current.path,
    includePatterns: ['assets/images/**/*.png', 'assets/images/**/*.jpg'],
    compressionLevel: CompressionLevel.medium,
  );

  // Process with different settings for different types
  await optimizer.optimize(
    projectPath: Directory.current.path,
    compressionSettings: {
      'png': CompressionSettings(level: 9),
      'jpg': CompressionSettings(quality: 85),
    },
  );
}
A practical split: maximum compression for icons, higher quality for backgrounds, and a balanced middle for content images:
await optimizer.optimize(
  projectPath: Directory.current.path,
  compressionSettings: {
    'icons': CompressionSettings(level: 9),          // Maximum compression for icons
    'backgrounds': CompressionSettings(quality: 85), // High quality for backgrounds
    'content': CompressionSettings(quality: 80),     // Balanced for content
  },
);
Organizing assets into assets/images/icons, assets/images/backgrounds, assets/images/content, and an untouched assets/raw/ for original, unoptimized files makes this per-type strategy trivial to express — raw simply goes in exclude.

Pre-release pipeline

For release builds, chain the analysis, backup, optimization, and reporting APIs into one repeatable pipeline:
void preReleaseOptimization() async {
  final optimizer = AssetKamKaro();

  // 1. Analyze current state
  final analysis = await optimizer.analyzeAssets(
    projectPath: Directory.current.path,
  );

  // 2. Create backup
  await optimizer.createBackup(
    projectPath: Directory.current.path,
    backupPath: 'backups/pre_release_${DateTime.now().toIso8601String()}',
  );

  // 3. Optimize assets
  final result = await optimizer.optimize(
    projectPath: Directory.current.path,
    compressionLevel: CompressionLevel.high,
    createBackup: true,
  );

  // 4. Generate report
  await optimizer.generateReport(
    result: result,
    outputPath: 'reports/optimization_report.html',
  );
}
Cleanup of unused assets can also run with its own backup:
if (analysis.unusedAssets.isNotEmpty) {
  await optimizer.deleteUnusedAssets(
    assets: analysis.unusedAssets,
    backup: true,
  );
}

CI/CD integration

Run optimization automatically on push with GitHub Actions:
name: Asset Optimization

on:
  push:
    branches: [ main ]

jobs:
  optimize:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2

      - name: Setup Flutter
        uses: subosito/flutter-action@v1
        with:
          flutter-version: '3.x'

      - name: Install Dependencies
        run: flutter pub get

      - name: Optimize Assets
        run: dart run assetkamkaro optimize --compression high --backup true

      - name: Commit Changes
        run: |
          git config --local user.email "action@github.com"
          git config --local user.name "GitHub Action"
          git add .
          git commit -m "Optimize assets"
          git push

Troubleshooting

Optimization failed. Catch and distinguish the underlying error — file permissions vs. disk space:
try {
  await optimizer.optimize(...);
} catch (e) {
  // Check file permissions
  if (e is FileSystemException) {
    print('Permission error: ${e.message}');
  }
  // Check disk space
  if (e is IOException) {
    print('Disk space error: ${e.message}');
  }
}
No size reduction. Verify your compression settings and enable detailed verification:
final result = await optimizer.optimize(
  compressionLevel: CompressionLevel.high,
  verifyResults: true,  // Enable detailed verification
);
Performance issues. Reduce the batch size, disable parallel processing, and lean on the cache:
await optimizer.optimize(
  batchSize: 25,              // Reduce batch size
  parallelProcessing: false,  // Disable parallel processing
  cacheEnabled: true,         // Enable caching
);
Always create backups before optimization, use compression levels appropriate to each asset type, and monitor the OptimizationResult after every run — compression is lossy at higher levels, and --delete-unused removes files.

For AI agents

Copy this block into Cursor, Claude Code, or any coding agent to integrate the package correctly:
# assetkamkaro — agent integration instructions

Optimize this Flutter app's assets (compress images, find unused assets)
using assetkamkaro ^0.1.1 (pub.dev). Follow these rules exactly:

1. Note the successor first: asset_wizard ^0.2.0 replaces assetkamkaro —
   migrating is a dependency rename plus `dart pub get`, and the CLI
   becomes `dart run ak`. Use asset_wizard for new projects if available;
   the instructions below are for the original assetkamkaro package.
2. Add to pubspec.yaml: assetkamkaro: ^0.1.1, then run flutter pub get.
3. ALWAYS start with a dry run before writing anything:
   dart run assetkamkaro optimize --dry-run
   Review the reported changes and the unusedAssets list.
4. Run the real optimization via CLI:
   dart run assetkamkaro optimize --compression high \
     --exclude assets/icons,assets/backgrounds --backup true
   Other flags: --delete-unused (destructive — removes unreferenced
   files), --config custom_config.yaml.
5. Or drive it from Dart: create AssetKamKaro() and call
   optimize(projectPath: ..., compressionLevel: CompressionLevel.low |
   medium | high, dryRun:, createBackup:, excludePatterns:,
   includePatterns:, compressionSettings:).
6. Read the returned OptimizationResult: totalSizeReduction (bytes),
   totalAssetsProcessed, unusedAssets (list), compressionResults
   (per-file map of original size, compressed size, reduction %).
   Report these numbers to the user.
7. Supported formats: JPEG, PNG, WebP. For repeatable runs write a
   config.yaml at the project root (compression.level, jpeg.quality
   0-100, png.level 0-9, exclude:, backup:, delete_unused:,
   enable_cache:, parallel_processing:).
8. Keep backups on (backup: true / createBackup: true) and never pass
   --delete-unused without first reviewing the dry-run unusedAssets
   list. Higher compression levels are lossy.
9. Pipeline APIs also available on the optimizer: analyzeAssets(),
   createBackup(projectPath:, backupPath:), generateReport(result:,
   outputPath:), deleteUnusedAssets(assets:, backup: true).

Docs: https://docs.aliarain.com/assetkamkaro
Agents can also read this page as plain markdown — every page on this site is available to LLMs in raw form via the docs' llms.txt index.
Ali Arain Docs
Powered byHolocron