TypeScript

Auth.js는 타입 안전성을 중요하게 여기기 때문에 TypeScript로 작성되었으며 100% 타입 안전합니다. 여러분의 프로젝트에서 사용할 수 있는 자체 타입 정의를 제공합니다.

TypeScript를 사용하지 않더라도 VS Code와 같은 IDE는 이를 인식하여 더 나은 개발자 경험을 제공합니다. 코드를 작성하는 동안 특정 객체나 함수가 어떻게 생겼는지에 대한 제안을 받을 수 있으며, 때로는 문서, 예제, 그리고 유용한 리소스에 대한 링크도 제공됩니다.

철학

여러분이 Auth.js 리소스를 확장할 경우, 애플리케이션 전반에 걸쳐 타입을 지정하는 주요 기술로 제네릭 대신 모듈 확장을 선택했습니다.

왜 제네릭을 사용하지 않나요?

서브모듈 간에 공유되는 인터페이스는 제네릭으로 Auth.js 라이브러리 함수에 전달되지 않습니다.

이러한 타입이 사용될 때마다, 함수는 항상 해당 형식을 반환할 것으로 기대합니다. 제네릭을 사용하면 한 곳에서 타입을 재정의할 수 있지만, 다른 곳에서는 그렇지 않을 수 있어 타입이 구현과 일치하지 않을 수 있습니다.

모듈 확장을 사용하면 타입을 한 번 정의하고, 예상되는 곳에서 항상 동일한 타입임을 확신할 수 있습니다.

모듈 확장

Auth.js 라이브러리들은 서브모듈과 다른 Auth.js 라이브러리들 간에 공유되는 특정 인터페이스들을 제공합니다. 예를 들어, next-auth와 @auth/prisma-adapter는 @auth/core의 타입들을 사용합니다.

이러한 인터페이스의 좋은 예로 Session이나 User가 있습니다. 여러분은 TypeScript의 모듈 확장을 사용하여 이러한 타입들을 확장하고, Auth.js 전반에 걸쳐 여러분만의 속성들을 추가할 수 있습니다. 이렇게 하면 제네릭을 계속 전달할 필요가 없습니다.

예를 들어 Session을 확장해 보겠습니다.

auth.ts

import NextAuth, { type DefaultSession } from "next-auth"
 
declare module "next-auth" {
  /**
   * `auth`, `useSession`, `getSession`에 의해 반환되며, `SessionProvider` React Context의 prop으로 전달됨
   */
  interface Session {
    user: {
      /** 사용자의 우편 주소 */
      address: string
      /**
       * 기본적으로 TypeScript는 새로운 인터페이스 속성을 병합하고 기존 속성을 덮어씀.
       * 이 경우, 기본 세션 사용자 속성이 덮어쓰여지므로,
       * 새로 정의한 속성과 함께 기본 세션 사용자 속성을 다시 추가해야 함.
       */
    } & DefaultSession["user"]
  }
}
 
export const { auth, handlers } = NextAuth({
  callbacks: {
    session({ session, token, user }) {
      // `session.user.address`는 이제 유효한 속성이 되며,
      // `useSession().data.user`나 `auth().user` 같은 곳에서 타입 체크가 됨
      return {
        ...session,
        user: {
          ...session.user,
          address: user.address,
        },
      }
    },
  },
})

plugin@auth.ts

import { DefaultSession, QwikAuth$ } from "@auth/qwik"
 
declare module "@auth/qwik" {
  /**
   * `useSession` 훅과 sharedMap의 `session` 객체에 의해 반환됨
   */
  interface Session {
    user: {
      /** 사용자의 우편 주소 */
      address: string
      /**
       * 기본적으로 TypeScript는 새로운 인터페이스 속성을 병합하고 기존 속성을 덮어씀.
       * 이 경우, 기본 세션 사용자 속성이 덮어쓰여지므로,
       * 새로 정의한 속성과 함께 기본 세션 사용자 속성을 다시 추가해야 함.
       */
    } & DefaultSession["user"]
  }
}
 
export const { onRequest, useSession, useSignIn, useSignOut } = QwikAuth$(
  () => ({
    callbacks: {
      session({ session, token, user }) {
        // `session.user.address`는 이제 유효한 속성이 되며,
        // `useSession().user`나 `sharedMap.get('session').user` 같은 곳에서 타입 체크가 됨
        return {
          ...session,
          user: {
            ...session.user,
            address: user.address,
          },
        }
      },
    },
  })
)

auth.ts

import SvelteKitAuth, { type DefaultSession } from "@auth/sveltekit"
 
declare module "@auth/sveltekit" {
  interface Session {
    user: {
      userId: string
      /**
       * 기본적으로 TypeScript는 새로운 인터페이스 속성을 병합하고 기존 속성을 덮어씀.
       * 이 경우, 기본 세션 사용자 속성이 덮어쓰여지므로,
       * 새로 정의한 속성과 함께 기본 세션 사용자 속성을 다시 추가해야 함.
       */
    } & DefaultSession["user"]
  }
}
 
export const { handle } = SvelteKitAuth({
  callbacks: {
    session: async ({ session, token }) => {
      if (token) {
        session.user.userId = token.sub
      }
      // `session.user.userId`는 이제 유효한 속성이 되며,
      // `useSession().data.user`나 `auth().user` 같은 곳에서 타입 체크가 됨
      return session
    },
  },
})

모듈 확장은 특정 인터페이스에만 국한되지 않습니다. 우리가 정의한 어떤 interface든 확장할 수 있습니다. 다음은 여러분의 사용 사례에 따라 재정의할 수 있는 일반적인 인터페이스들입니다.

types.d.ts

declare module "next-auth" {
  /**
   * OAuth 제공자의 `profile` 콜백이나 데이터베이스를 사용할 때 `session` 콜백의 두 번째 매개변수로 반환되는 사용자 객체의 형태
   */
  interface User {}
  /**
   * OAuth 제공자의 `account` 콜백으로 반환되는 계정 객체의 형태.
   * 일반적으로 사용 중인 제공자에 대한 정보(예: OAuth 토큰 `access_token` 등)를 포함함.
   */
  interface Account {}
 
  /**
   * `useSession`, `auth`에 의해 반환되며, 활성 세션에 대한 정보를 포함함.
   */
  interface Session {}
}
 
// `JWT` 인터페이스는 `next-auth/jwt` 서브모듈에서 찾을 수 있음
import { JWT } from "next-auth/jwt"
 
declare module "next-auth/jwt" {
  /** JWT 세션을 사용할 때 `jwt` 콜백과 `auth`에 의해 반환됨 */
  interface JWT {
    /** OpenID ID 토큰 */
    idToken?: string
  }
}

모듈 선언은 프로젝트의 tsconfig.json에 “포함된” 어떤 파일에든 추가할 수 있습니다.

리소스

배포 42 School

TypeScript

철학

모듈 확장

리소스

About Auth.js

Download

Acknowledgements