@apollo/client-integration-nextjs중복 코드 문제: 서버용, 어드민용, 클라이언트용 총 3개의 Apollo Client 인스턴스가 필요했는데, 각각에 대해 Apollo Links를 별도로 작성하면 코드 중복이 심각함
서버/클라이언트 경계 처리: RSC(React Server Components) 환경에서 서버와 클라이언트의 인증 방식이 달라 각각 다른 처리가 필요
토큰 갱신 로직: 클라이언트에서만 토큰 갱신이 가능하므로 환경별로 다른 에러 처리 필요
export interface CreateLinksOptions {
isServer: boolean;
getToken?: () => Promise<string | null | undefined> | string | null | undefined;
hasuraAdminSecret?: string;
hasuraGraphQLEndpoint?: string;
refreshTokenManager?: {
refreshAccessToken: () => Promise<boolean>;
};
}
의존성을 외부에서 주입받아 다양한 환경에 대응할 수 있도록 설계
1) 환경별 분기 처리
const prefix = isServer ? "🖥️ [Server]" : "💻 [Client]";
2) 조건부 링크 구성
const links = [
loggerLink,
errorLink,
...(retryLink ? [retryLink] : []), // 클라이언트만
...(ssrMultipartLink ? [ssrMultipartLink] : []), // 서버만
authLink.concat(httpLink),
];
3) 토큰 갱신 처리 (클라이언트 전용)
if (!isServer && extensions?.code === "invalid-jwt") {
return new Observable((observer) => {
refreshTokenManager.refreshAccessToken()
.then((success) => {
if (success) {
forward(operation).subscribe(observer); // 재시도
}
});
});
}
export const { getClient, query, PreloadQuery } = registerApolloClient(() => {
return new ApolloClient({
cache: new InMemoryCache(),
link: createApolloLinks({
isServer: true,
getToken: async () => {
const token = (await cookies()).get('access-token')?.value;
return token;
},
hasuraGraphQLEndpoint: env.HASURA_GRAPHQL_ENDPOINT,
}),
incrementalHandler: new Defer20220824Handler(),
});
});
const apolloClient = new ApolloClient({
cache: new InMemoryCache(),
link: createApolloLinks({
isServer: false,
hasuraGraphQLEndpoint: env.NEXT_PUBLIC_HASURA_GRAPHQL_ENDPOINT,
refreshTokenManager: {
refreshAccessToken: async () => {
// 토큰 갱신 로직
return await refreshToken();
}
},
}),
});
const adminClient = new ApolloClient({
cache: new InMemoryCache(),
link: createApolloLinks({
isServer: true,
hasuraAdminSecret: env.HASURA_ADMIN_SECRET,
hasuraGraphQLEndpoint: env.HASURA_GRAPHQL_ENDPOINT,
}),
});
import { ApolloLink, HttpLink, Observable } from "@apollo/client";
import {
CombinedGraphQLErrors,
CombinedProtocolErrors,
} from "@apollo/client/errors";
import { SetContextLink } from "@apollo/client/link/context";
import { ErrorLink } from "@apollo/client/link/error";
import { RetryLink } from "@apollo/client/link/retry";
import { SSRMultipartLink } from "@apollo/client-integration-nextjs";
import { tap } from "rxjs/operators";
export interface CreateLinksOptions {
isServer: boolean;
getToken?: () =>
| Promise<string | null | undefined>
| string
| null
| undefined;
hasuraAdminSecret?: string;
hasuraGraphQLEndpoint?: string;
refreshTokenManager?: {
refreshAccessToken: () => Promise<boolean>;
};
}
// 아폴로 링크 팩토리 함수
export function createApolloLinks(options: CreateLinksOptions) {
const {
isServer,
getToken,
hasuraAdminSecret,
hasuraGraphQLEndpoint,
refreshTokenManager,
} = options;
const prefix = isServer ? "🖥️ [Server]" : "💻 [Client]";
const endpoint = hasuraGraphQLEndpoint;
// 1. Auth Link
// 서버: 쿠키에서 토큰을 읽어 Authorization 헤더 설정
const authLink = new SetContextLink(async (prevContext, _operation) => {
let token: string | null | undefined;
// 명시적으로 토큰을 헤더에 추가
if (getToken) {
console.log(`${prefix} 🔑 apollo-links에서 헤더에 토큰 추가 시도 시작`);
token = await getToken();
console.log(
`${prefix} 🔑 apollo-links에서 토큰 조회 성공:`,
token ? `${token.substring(0, 20)}...` : "null",
);
} else {
console.log(`${prefix} 🔑 getToken 함수가 제공되지 않았습니다`);
}
const headers = {
...prevContext.headers,
...(token && { authorization: `Bearer ${token}` }),
"x-request-from": isServer ? "server" : "client",
};
return {
headers,
};
});
// 2. Error Link - 인증 에러 발생 시 토큰 갱신 및 재시도
const errorLink = new ErrorLink(({ error, operation, forward }) => {
if (CombinedGraphQLErrors.is(error)) {
for (const err of error.errors) {
const { message, locations, path, extensions } = err;
console.log(
`${prefix} ❌ [GraphQL error]: Message: ${message}, Location: ${locations}, Path: ${path}`,
);
// ** 클라이언트 토큰 갱신 처리 **
if (!isServer && typeof window !== "undefined") {
// invalid-jwt 또는 UNAUTHENTICATED 에러 감지
if (
extensions?.code === "invalid-jwt" ||
extensions?.code === "UNAUTHENTICATED"
) {
console.log(
`${prefix} 🔄 apollo-links에서 토큰 갱신 시도 시작: ${operation.operationName}`,
);
// Observable을 반환하여 토큰 갱신 후 재시도
return new Observable((observer) => {
if (!refreshTokenManager) {
console.error(`${prefix} ❌ refreshTokenManager 없음`);
observer.error(error);
return;
}
refreshTokenManager
.refreshAccessToken()
.then((success: boolean) => {
if (success) {
// 토큰 갱신 성공 - 원래 요청 재시도
console.log(
`${prefix} ♻️ 토큰 갱신 성공, ${operation.operationName} 재시도 시작`,
);
const subscriber = {
next: observer.next.bind(observer),
error: observer.error.bind(observer),
complete: observer.complete.bind(observer),
};
forward(operation).subscribe(subscriber);
} else {
// 토큰 갱신 실패 - 에러 전달
observer.error(error);
}
})
.catch((refreshError: unknown) => {
console.error(`${prefix} ❌ 토큰 갱신 에러:`, refreshError);
observer.error(error);
});
});
}
if (extensions?.code === "FORBIDDEN") {
// 권한 부족 에러
console.warn(`${prefix} ⛔ Forbidden 인가 검토 필요: ${message}`);
// TODO: forbidden 일때 처리 방법 논의 필요 ***
// toast.error('권한이 없습니다?')
}
} else {
// 서버에서는 토큰 갱신 불가 - 클라이언트에서 처리해야 함
// 1. 서버는 브라우저 쿠키에 직접 접근 불가
// 2. RSC는 이미 렌더링 중이라 쿠키 수정 불가
// 3. 에러를 자동으로 전파하여 클라이언트에서 재인증 처리
// (ErrorLink에서 아무것도 반환하지 않으면 에러가 자동 전파됨)
}
}
} else if (CombinedProtocolErrors.is(error)) {
for (const err of error.errors) {
const { message, extensions } = err;
console.log(
`${prefix} ❌ [Protocol] ${operation.operationName}: ${message}`,
{ extensions },
);
}
} else {
console.error(`${prefix} 🔌 [Network error]:`, error);
}
});
// 3. HTTP Link
const httpLink = new HttpLink({
uri: endpoint,
credentials: "include",
...(isServer && {
fetch: fetch,
fetchOptions: {
cache: "no-store",
},
}),
...(!!hasuraAdminSecret && {
headers: {
"x-hasura-admin-secret": hasuraAdminSecret,
},
}),
});
// 4. Retry Link (클라이언트만)
const retryLink = !isServer
? new RetryLink({
delay: {
initial: 300,
max: 5000,
jitter: true,
},
attempts: {
max: 3,
retryIf: (error) =>
!!error && error.message.includes("Network error"),
},
})
: null;
// 5. SSR Multipart Link
const ssrMultipartLink = isServer
? new SSRMultipartLink({
stripDefer: true,
})
: null;
// 6. Logger Link - 개발 환경에서만 GraphQL 작업 로깅
// Apollo Client 4.0에서 asyncMap이 제거되어 rxjs의 tap 연산자 사용
// tap은 사이드 이펙트(로깅)만 처리하고 응답은 그대로 전달
const loggerLink = new ApolloLink((operation, forward) => {
// 프로덕션 환경에서는 로깅 비활성화
if (process.env.NODE_ENV !== "development") {
return forward(operation);
}
// 요청 시작 로그 (작업 이름과 변수 출력)
console.log(`${prefix} 🚀 ${operation.operationName}`, {
variables: operation.variables,
});
const start = Date.now();
// 응답 완료 시 소요 시간 로그
// 1초 이상 걸리면 🐌, 그 이하면 ⚡ 이모지 표시
return forward(operation).pipe(
tap(() => {
const duration = Date.now() - start;
const emoji = duration > 1000 ? "🐌" : "⚡";
console.log(
`${prefix} ${emoji} ${operation.operationName} (${duration}ms)`,
);
}),
);
});
// 최종적으로 링크들 배열 생성
const links = [
loggerLink,
errorLink,
...(retryLink ? [retryLink] : []),
...(ssrMultipartLink ? [ssrMultipartLink] : []),
authLink.concat(httpLink),
];
return ApolloLink.from(links);
}
팩토리 패턴과 의존성 주입을 통해 복잡한 Apollo Client 설정을 깔끔하게 관리할 수 있었습니다. 특히 Next.js 15의 App Router와 RSC 환경에서 서버/클라이언트 경계를 명확히 구분하여 처리한 것이 핵심이었습니다.
서버에서의 토큰 갱신 불가: RSC는 이미 렌더링 중이므로 쿠키 수정 불가능. 에러를 클라이언트로 전파하여 처리해야 함
rxjs 의존성: Apollo Client 4.0에서 asyncMap이 제거되어 rxjs의 tap 연산자 사용 필요
캐싱 전략: 서버에서는 cache: "no-store" 설정으로 항상 최신 데이터 fetch