Quickstart

Add GitHub OAuth authentication to your React app in five steps.

This guide walks you through installing the package, creating a GitHub OAuth App, and wiring up the hook so users can sign in with GitHub.

1. Install the package

   Add @react-oauth/github to your project:

   npm

   npm install @react-oauth/github
   

   The package has no runtime dependencies. It requires React 16.8 or later.

2. Create a GitHub OAuth App

   You need a GitHub OAuth App to get a Client ID.

   1. Go to GitHub Developer Settings and click OAuth Apps.
   2. Click New OAuth App.
   3. Fill in the required fields:
      • Application name: the name users will see on the authorization screen.
      • Homepage URL: your app’s public URL (e.g., https://myapp.com).
      • Authorization callback URL: the URL GitHub redirects to after authorization (e.g., http://localhost:3000/callback).
   4. Click Register application.
   5. Copy the Client ID from the app settings page. Keep your Client Secret private — it must only be used on your backend.

   Never add your Client Secret to your frontend code or commit it to a public repository.

3. Set your redirect URI

   The redirectUri you pass to the hook must exactly match the Authorization callback URL registered in your GitHub OAuth App settings.

   For local development, register http://localhost:3000/callback (or whichever port your dev server uses). You can register multiple callback URLs — one per environment — by creating separate OAuth Apps or by updating the callback URL in GitHub settings before deploying.

   Create a separate GitHub OAuth App for each environment (development, staging, production) so each can have its own callback URL without conflicts.

4. Use the hook in your component

   Import useGitHubLogin and call it with your clientId, redirectUri, and callback functions:

   import { useGitHubLogin, OAuthError, OAuthErrorCode } from '@react-oauth/github';
   
   function GitHubLoginButton() {
     const { initiateGitHubLogin, isLoading } = useGitHubLogin({
       clientId: 'your-github-client-id',
       redirectUri: 'http://localhost:3000/callback',
       onSuccess: async response => {
         // Exchange the code on your backend
         const res = await fetch('/api/github/callback', {
           method: 'POST',
           headers: { 'Content-Type': 'application/json' },
           body: JSON.stringify({ code: response.code }),
         });
         const user = await res.json();
         console.log('Authenticated user:', user);
       },
       onError: error => {
         if (OAuthError.isOAuthError(error)) {
           if (error.code === OAuthErrorCode.POPUP_BLOCKED) {
             alert('Please allow popups for this site to sign in with GitHub.');
           } else {
             console.error('OAuth error:', error.message);
           }
         }
       },
     });
   
     return (
       <button onClick={initiateGitHubLogin} disabled={isLoading}>
         {isLoading ? 'Connecting...' : 'Sign in with GitHub'}
       </button>
     );
   }
   

   The hook returns two values:

   • initiateGitHubLogin — call this when the user clicks your button.
   • isLoading — true while the popup is open and the hook is waiting for a response.
5. Exchange the code on your backend

   The onSuccess callback receives an authorization code. Send it to your backend and exchange it for an access token using your Client Secret:

   // Node.js / Express example
   app.post('/api/github/callback', async (req, res) => {
     const { code } = req.body;
   
     // Exchange code for access token
     const tokenResponse = await fetch('https://github.com/login/oauth/access_token', {
       method: 'POST',
       headers: {
         'Content-Type': 'application/json',
         Accept: 'application/json',
       },
       body: JSON.stringify({
         client_id: process.env.GITHUB_CLIENT_ID,
         client_secret: process.env.GITHUB_CLIENT_SECRET,
         code,
       }),
     });
   
     const { access_token } = await tokenResponse.json();
   
     // Use the access token to fetch user data
     const userResponse = await fetch('https://api.github.com/user', {
       headers: { Authorization: `token ${access_token}` },
     });
   
     const user = await userResponse.json();
     res.json({ user });
   });
   

   Always exchange the authorization code server-side. The exchange requires your Client Secret, which must never be exposed in your frontend code.

Next steps

Creating a GitHub OAuth App

Detailed instructions for GitHub OAuth App configuration, including local development and environment setup.

Custom login button

Build loading states, icon buttons, and styled components on top of the hook.

Error handling

Handle every failure mode with named error codes and user-friendly messages.

Backend code exchange

Complete guide to exchanging the authorization code and fetching user data on your server.