Anti-patterns to Avoid

Most bugs happen when imperative and declarative models are mixed. Keep a strict state boundary.

Back to Introduction Open GitHub

Mixing push/pop with pages

Do not call Navigator.push/pop for stacks already controlled by List<PageEntry>.

Widget in state

Do not put Widget instances into page metadata. Keep only keys and route-like identifiers.

Unbounded keys

Do not reuse duplicate PageEntry.key values in the same stack.

Migration Checklist

Use this checklist during refactor reviews to keep architecture consistent.

Checklist

Good vs Bad

// Bad: mixing imperative and declarative for same stack
Navigator.of(context).push(...);
_pages = [..._pages, const PageEntry(key: 'detail', name: '/detail')];

// Good: update only declarative state
setState(() {
  _pages = [..._pages, const PageEntry(key: 'detail', name: '/detail')];
});

Review Tip

During code review, track who owns stack mutations and reject changes that mutate the same stack through multiple APIs.

Back Handling

Introduction