Search packages, repositories and app categories

Package detailsv0.7.0

fresh

An token refresh library for dart. This package exposes the core components that are common to various refresh token implementations (REST, GraphQL, etc...).

AndroidiOSWebmacOSWindowsLinux
30-day downloads
87K
Likes
157
Pub points
160

Install package

flutter pub add fresh

Package Overview

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

Fresh is a Dart library designed to manage token refresh workflows across REST and GraphQL APIs. It provides reusable components for handling authentication tokens, ensuring secure and consistent token renewal without duplicating logic. The package abstracts common patterns like token expiration detection, automatic refresh requests, and error handling, making it easier to implement robust authentication flows in Flutter and other Dart applications. Built with modularity in mind, Fresh supports multiple platforms including mobile, web, and desktop.

Use cases

  • Handling expired JWT tokens
  • Automating token refresh in REST APIs
  • Managing authentication state in GraphQL clients
  • Securing API calls with valid tokens
  • Implementing resilient auth flows

Key features

  • Modular token refresh architecture
  • Support for REST and GraphQL
  • Cross-platform compatibility
  • Automatic retry on failed requests
  • Configurable refresh strategies

Suitable for

  • Flutter apps with API authentication
  • Applications using JWT or similar tokens
  • Developers building reusable auth systems
  • Projects requiring secure token management
  • Multi-platform applications

Considerations

  • Requires custom implementation for specific auth endpoints
  • May need integration with HTTP clients like dio or http
  • Not a full auth solution but a refresh utility
  • Depends on proper backend token refresh setup
  • Limited to token refresh—not login or logout

Original README

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

Fresh 🍋

build License: MIT GitHub stars


A collection of packages for automatic token refresh in Dart and Flutter. Fresh handles refreshing, caching, and attaching authentication tokens transparently so your API calls just work.

Why Fresh?

Token-based authentication seems simple until you handle the edge cases: tokens expire mid-session, multiple requests fail at the same time triggering duplicate refreshes, refresh tokens get revoked, and you need to route users to login when auth is lost. Fresh handles all of this so you don't have to.

  • No more manual 401 handling scattered across your codebase
  • No more race conditions when concurrent requests trigger simultaneous refreshes
  • No more stale tokens causing request failures - expired tokens are refreshed proactively before the request is even sent

Packages

Package Pub
fresh pub package
fresh_dio pub package
fresh_graphql pub package
fresh_http pub package

Features

  • Automatic token refresh on 401 / auth errors, with automatic request retry
  • Proactive refresh before requests when the token is expired
  • Single-flight refresh - concurrent requests share one refresh call instead of triggering multiple
  • authenticationStatus stream for reacting to login/logout events
  • Pluggable TokenStorage - bring your own persistence layer
  • Built-in OAuth2Token with expiresAt support

Usage

fresh_dio
final dio = Dio();

dio.interceptors.add(
  Fresh.oAuth2(
    tokenStorage: InMemoryTokenStorage<OAuth2Token>(),
    refreshToken: (token, client) async {
      final response = await client.post(
        'https://api.example.com/auth/refresh',
        data: {'refresh_token': token?.refreshToken},
      );
      return OAuth2Token(
        accessToken: response.data['access_token'],
        refreshToken: response.data['refresh_token'],
      );
    },
  ),
);

See the fresh_dio README for full documentation.

fresh_graphql
import 'dart:convert';

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>;
    return OAuth2Token(
      accessToken: body['access_token'],
      refreshToken: body['refresh_token'],
    );
  },
  shouldRefresh: (response) =>
      response.errors?.any((e) => e.message.contains('UNAUTHENTICATED')) ?? false,
);

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

See the fresh_graphql README for full documentation.

fresh_http
import 'dart:convert';

final client = Fresh.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>;
    return OAuth2Token(
      accessToken: body['access_token'],
      refreshToken: body['refresh_token'],
    );
  },
);

See the fresh_http README for full documentation.

Categories

Dependencies

Dependency list 1 items

Source repository

Projects using this package

No data available yet.

Rankings