Scratch Auth for React

English / 日本語

Scratch Auth is a simple OAuth service for Scratch. It provides developers with an easy-to-understand API and users with a smooth login experience. By using scratch-auth-react, you can easily implement OAuth functionality into your site.

This guide explains the usage using Next.js's Approuter and TypeScript, but it should work similarly in Pagerouter or React, so adjust the code to make it work in your environment.

[!NOTE] Versions labeled as pre, beta, alpha, etc., may be unstable. We recommend using the release versions. If you encounter any issues, please report them here.

npm install scratch-auth-react

yarn add scratch-auth-react

Set the secret key used for signing Scratch Auth cookies. This value should be a random, long string.

SCRATCH_AUTH_COOKIE_SECRET_KEY=your_secret_key_here

[!NOTE] The setup file should be created in the root directory of your project. This file is used to set the OAuth redirect URL. Create it with the name scratch-auth.config.ts as shown below.

redirect_url Redirect URL When publishing a website, please change the URL from the development environment to the production environment.

title By default, it is Scratch Auth, but you can optionally decide your own title.

expiration Sets the session storage period. By default, it is 30 days. You can freely set the storage period as an option. If -1 is set, the storage period is permanently (200 years).

import { ScratchAuth_config } from "scratch-auth-react/src/dist/config"

// Perform necessary configurations within the setup file
const config: ScratchAuth_config = {
  redirect_url: `http://localhost:3000/api/auth`, // Required
  title: `Title`, // option
  expiration: 30, // option
}

export default config

No explanation of basic knowledge such as React, etc., will be provided.

By executing await ScratchAuthGET_session(), the user's name is returned if logged in, otherwise null is returned.

'use client'

import React, { useEffect, useState } from 'react';
import { ScratchAuthGET_session, ScratchAuth_Login, ScratchAuth_Logout } from 'scratch-auth-react';

export default function Home() {
  const [session, setSession] = useState<string | null>(null);

  useEffect(() => {
    const getSession = async () => {
      const sessionData = await ScratchAuthGET_session(); // Get session (username)
      setSession(sessionData); // Save session (username) to variable
    };
    getSession();
  }, []);

  return (
      <>
        <div className='flex flex-col gap-3 text-center'>
          {session?
            <>
              <h1>{session}</h1>
              <button onClick={() => ScratchAuth_Logout()}>
                Logout
              </button>
            </>:<>
              <button onClick={() => ScratchAuth_Login()}>
                Login
              </button> 
            </>
          }
        </div>
      </>
  );
}

In the example code, we use Next.js's useSearchParams to get parameters, but it's fine to use another method as long as you can get the value of privateCode.

[!NOTE] This process needs to be executed on the page with the redirect URL set up in the Setup.

/*
 * page.tsx
 * This file is the component of the authentication page.
 * It retrieves the privateCode from the redirect URL and performs the authentication process.
 */

'use client'

import React, { useEffect, useState } from 'react';
import { useSearchParams } from 'next/navigation'
import { ScratchAuthSET_session } from 'scratch-auth-react';

export default function AuthPage() {
  const searchParams = useSearchParams();
  const privateCode = searchParams.get('privateCode');

  useEffect(() => {
    async function auth() {
      await ScratchAuthSET_session(privateCode); //A uthenticate account
      if (typeof window !== 'undefined') {
        window.location.href = `/`; // Redirect to home
      }
    }
    auth()
  }, []); // Pass an empty dependency array to execute only on initial render

  return (
    <span>Processing...</span>
  );
}

https://github.com/Fun117/scratch-auth-react