package_file_loader 0.4.6

Simple utility functions for loading a file from packages

package_file_loader

A Dart utility package for loading files from package dependencies at runtime using package: URIs. Resolves package paths via .dart_tool/package_config.json with a fallback to the legacy .packages file.

Features

• Load files from any package dependency using package: URIs
• Both async and sync APIs
• Returns files as File objects or as LoadedFileAsset (wraps AssetId from package:build)
• Convert absolute pub-cache paths back to package: imports
• Extract package names from absolute dependency paths (hosted and git)
• Supports .dart_tool/package_config.json (v1 and v2) and legacy .packages format

Getting Started

dart pub add package_file_loader

Make sure your project has resolved dependencies:

dart pub get
# or
flutter pub get

Usage

Load a file from a package

import 'package:package_file_loader/package_file_loader.dart';

// Async
final file = await loadPackageFile('package:some_package/path/to/file.dart');

// Sync
final file = loadPackageFileSync('package:some_package/path/to/file.dart');

Load a file as a build asset

Returns a LoadedFileAsset containing both an AssetId (from package:build) and the File:

final asset = await loadPackageFileAsAsset('package:some_package/path/to/file.dart');
print(asset.assetId); // some_package|path/to/file.dart
print(asset.file.path);

Control the root path

By default, the package's packageUri (typically lib/) is used as the root. Set packageUriAsRoot to false to resolve from the package root directory instead:

// Resolves from lib/ (default)
final file = await loadPackageFile('package:some_package/file.dart');

// Resolves from the package root
final file = await loadPackageFile(
  'package:some_package/file.dart',
  packageUriAsRoot: false,
);

Extract package name from an absolute path

final name = packageFromAbsolutePath(
  '/Users/you/.pub-cache/hosted/pub.dev/http-1.0.0/lib/http.dart',
);
print(name); // http

Works with both pub.dev hosted and git dependencies.

Convert an absolute path to a package import

final import = await packageImportFromAbsolutePath(
  '/Users/you/.pub-cache/hosted/pub.dev/http-1.0.0/lib/src/client.dart',
);
print(import); // package:http/src/client.dart

API Reference

Function	Description
loadPackageFile	Async — returns a File from a package: URI
loadPackageFileSync	Sync version of loadPackageFile
loadPackageFileAsAsset	Async — returns a LoadedFileAsset (AssetId + File)
loadPackageFileAsAssetSync	Sync version of loadPackageFileAsAsset
packageFromAbsolutePath	Extracts package name from an absolute pub-cache path
packageImportFromAbsolutePath	Converts an absolute path back to a package: import

Error Handling

• FormatException — thrown when the input string doesn't match the expected package:name/path format
• PackageNotFoundException — thrown when the package isn't found in the config, or a package name can't be extracted from an absolute path
• FileSystemException — thrown when neither .dart_tool/package_config.json nor .packages is found (run pub get first)