Axios Auth Refresh — Axios 用 JWT リフレッシュインターセプタ

Library
Axios Auth Refresh — Axios 用 JWT リフレッシュインターセプタ

Axios Auth Refresh — Axios 用 JWT リフレッシュインターセプタ

軽量かつ依存ゼロの Axios インターセプタで、JWT のアクセストークン自動リフレッシュと同時発生する 401 エラーのレースコンディションを解決します。約1KB 未満の超軽量実装で、TypeScript 対応。リフレッシュ処理中に来たリクエストをキューに入れて刷新が完了次第再試行することで、余分なリフレッシュ呼び出しを防ぎ、セッションの安定性を高めます。設定はほぼ不要で既存の Axios インスタンスに簡単に組み込めます（MIT）。

https://github.com/Eden1711/axios-auth-refresh

概要

Axios Auth Refresh は、Axios 用の「JWT リフレッシュトークン」処理を安全かつ簡潔に実装するための小さなライブラリです。アクセストークンの期限切れでサーバが 401 を返した際に、自動でリフレッシュ処理を行い、その間に発生した他のリクエストが重複してリフレッシュを発動しないようにキューイングしてまとめて再試行します。依存ライブラリを持たず TypeScript で型定義済み、配布サイズは非常に小さく、既存の Axios インスタンスへワンラインで組み込める点が特徴です。主にシングルページアプリやフロントエンドの API 呼び出しで、トークンのリフレッシュ競合や無駄なリクエストを防ぎたい場面で有用です。

GitHub

リポジトリの統計情報

  • スター数: 3
  • フォーク数: 0
  • ウォッチャー数: 3
  • コミット数: 30
  • ファイル数: 12
  • メインの言語: TypeScript

主な特徴

  • 超軽量（< 1KB）で依存ゼロ：バンドルへの影響が極小。
  • JWT リフレッシュのレースコンディションを解決：1 回のリフレッシュ処理に集約。
  • Zero-config（ほぼ設定不要）：既存の Axios インスタンスに簡単に組み込める。
  • TypeScript 対応：型安全に利用可能で IDE 補完が効く。

技術的なポイント

Axios Auth Refresh のコアは「1つのリフレッシュ処理を共有し、他のリクエストを待機させる」設計です。具体的には、Axios のレスポンスインターセプタで 401（未認可）応答を検出すると、次の動作を行います。まず“現在リフレッシュ処理が進行中か”をチェックし、進行中であればその完了を待つための Promise を返してリクエストを保留します。進行中でなければリフレッシュ関数（ユーザーが提供するトークン更新ロジック）を一度だけ呼び出し、その Promise を共有オブジェクトに保存します。リフレッシュ処理が成功すれば保留中の全リクエストに対して新しいアクセストークンを付与して再試行し、失敗すれば保留中のリクエストをエラーとして返します。

この「単一の shared Promise とキュー」というパターンにより、同時に複数の API 呼び出しが 401 を返した場合でも、不要なトークンリフレッシュを複数回発生させず、結果としてサーバへの負担軽減とクライアント側の整合性を確保します。TypeScript によりリフレッシュ関数やオプションに型を与えられるため、導入時の安全性も高まります。依存関係を持たないためツリーシェイキングや軽量なバンドルが可能で、ライブラリ自体のサイズが小さい点も利点です。

設計上の注意点としては、リフレッシュ関数（リフレッシュトークンを用いたアクセストークン再取得処理）は利用側が実装する必要がある点、そしてリフレッシュが失敗した際のアプリ側のログアウトや再ログイン処理はライブラリ側では決められないため、適切にハンドリングする必要がある点です。さらに、SSR 環境や複数タブでのトークン同期を扱う場合は、ブラウザストレージやブロードキャストチャネル等での同期ロジックを併用することでより堅牢になります。加えて、Axios のリクエストカスタマイズ（ヘッダ追加やリトライ戦略）と組み合わせる際は、インターセプタの登録順序やリトライ回数の設計に注意が必要です。

このライブラリは「簡単に導入してすぐ効く」ことを重視しており、API はシンプルです。典型的な使い方は、アクセストークン付与のためのヘッダ更新ロジックと、トークン更新処理を渡すだけで済みます。結果として、フロントエンドアプリケーションの認証フローを冗長なリフレッシュ呼び出しから守り、ユーザー体験の向上と実装コストの削減に寄与します。

プロジェクトの構成

主要なファイルとディレクトリ：

  • .github: dir
  • .gitignore: file
  • CONTRIBUTING.md: file
  • LICENSE: file
  • README.md: file

…他 7 ファイル

（補足）通常の TypeScriptライブラリ同様、ソース（src）や型定義、package.json、tsconfig.json 等が含まれている想定で、配布用ビルドや型定義ファイルも提供されている可能性が高いです。

まとめ

少コードで安全なトークンリフレッシュを実現する軽量ライブラリです。

リポジトリ情報：

READMEの抜粋：

Axios Auth Refresh Queue 🛡️

🚀 Ultra-lightweight (< 1KB) zero-dependency authentication interceptor for Axios.

A bulletproof, zero-config Axios interceptor that handles JWT refresh tokens automatically. It solves the race condition problem when multiple requests fail with 401 Unauthorized simultaneously.

License TypeScript [![npm version](https://img.shields.io/npm/v/…