global_assert

Package Overview

Package selection guidance compiled from public package information, community data, and project usage.

GlobalAssert is a lightweight Dart package that enables build-time assertions for constants, helping catch configuration errors early during the build process rather than at runtime. By validating critical values at compile time, it improves app reliability and reduces the risk of silent failures in production. Ideal for enforcing invariant conditions on static data, it integrates seamlessly into Flutter projects across all major platforms.

Use cases

Validating configuration constants
Preventing runtime errors from misconfigurations
Enforcing invariant checks during build
Improving test reliability
Detecting invalid state early
Ensuring safe initialization

Key features

Build-time assertion evaluation
Simple API for constant validation
No runtime overhead
Cross-platform support
Integrates with Flutter build system
Minimal dependency footprint

Suitable for

Developers prioritizing build-time safety
Teams using static analysis for quality control
Projects with strict configuration requirements
Flutter apps requiring robust initialization checks
CI/CD pipelines needing early failure detection

Considerations

Only works with compile-time constants
Limited to simple boolean conditions
Does not replace runtime validation
Requires understanding of build-time execution
May increase build time slightly
Not suitable for dynamic or user-provided data

Original README

Original README snapshot from the linked source repository. Visit the repository for the latest content.

A micro-library for asserting at build time.

It's a common practice to configure a Dart app using const (build-time) values. There are benefits to this approach, such as enabling tree shaking of unused code.

This library makes it easy to do build-time assertions about such constants so that misconfigured apps fail at build-time instead of failing at runtime.

Usage

Use this library to validate your app's const values at build time. Anything can be annotated with @Assert.

//
// This app will fail compilation with '--define=MY_VAL=foo'
//

@Assert(
  myBuildTimeVal == 'val1' || myBuildTimeVal == 'val2',
  'myBuildTimeVal must be one of "val1" or "val2"',
)
const myBuildTimeVal = String.fromEnvironment('MY_VAL');

void main() {
  print('myBuildTimeVal is "$myBuildTimeVal"');
}

FAQ

🤔 How does this even work?!

The Dart compiler invokes annotation constructors at compile-time. This micro-library takes advantage of that to "trick" the compiler into allowing build-time asserts that can be placed (almost) anywhere. Special thanks to Kyle Turney for the inspiration behind this approach.

Why not allow an assert without a message?

Unfortunately, Dart doesn't treat an assert with a null message the same as an assert without any message at all. This means that we would need two constructors for @Assert to enable both messageless asserts and asserts with messages. Instead, we made the design choice when creating this micro-library that @Assert should require a non-null message. This enforces more meaningful compilation failure messages.

Will this always be needed?

We expect that when Dart supports metaprogramming, this library will be deprecated.

Search packages, repositories and app categories

Install package