Skip to content
pubscout

fresh_graphql

0.8.0, released 9 months ago by felangel.dev

A GraphQL link for package:graphql that manages authentication tokens transparently.

WASM-ready
$ flutter pub add fresh_graphql
Source repository

What it does

Provides a GraphQL link that automatically attaches authentication tokens, proactively or reactively refreshes expired tokens, retries failed requests, and manages authentication states via a stream.

AI-written summary of version 0.8.0, based on the package's README and metadata. Report an inaccuracy

Use it when

  • You are using package:graphql and need automated token refresh on unauthenticated errors.
  • You want to handle single-flight requests so concurrent token refreshes don't duplicate calls.

Skip it when

  • You are building a REST API client instead of GraphQL (use fresh or dio instead).
  • You do not use token-based authentication.

Strengths

  • Single-flight token refresh prevents concurrent duplicate refresh requests.
  • Provides an authenticationStatus stream for clean reactive navigation or login state management.
  • Supports custom token formats and pluggable storage layers.

Weaknesses

  • Requires custom implementation of token persistence (TokenStorage) for long-term storage.
  • Tied directly to package:graphql link architecture.

Setup

Kind
Pure Dart
Effort
Low
Code generation
No
Direct dependencies
4

Implement TokenStorage to save tokens persistently across app restarts and plug FreshLink into your GraphQL Link chain.

final freshLink = FreshLink.oAuth2(
  tokenStorage: InMemoryTokenStorage<OAuth2Token>(),
  refreshToken: (token, client) async {
    final response = await client.post(
      Uri.parse('https://api.example.com/auth/refresh'),
      body: jsonEncode({'refresh_token': token?.refreshToken}),
    );
    final body = jsonDecode(response.body) as Map<String, dynamic>;
    if (body['error'] == 'refresh_token_revoked') return null;
    return OAuth2Token(
      accessToken: body['access_token'],
      refreshToken: body['refresh_token'],
      expiresIn: body['expires_in'],
      issuedAt: DateTime.now(),
    );
  },
  shouldRefresh: (response) =>
      response.errors?.any((e) => e.message.contains('UNAUTHENTICATED')) ??
      false,
);

final link = Link.from([freshLink, HttpLink('https://api.example.com/graphql')]);

Alternatives

Packages that do the same job and could replace fresh_graphql.

  • oauth2

    If you need an OAuth2 client for REST APIs instead of GraphQL.

Works with

Packages commonly used together with fresh_graphql: ones it builds on, ones built on it, and its own family.