guides
SDK 설치
Connect SDK 설치 및 프레임워크별 초기 설정
SDK 설치
사전 요구 사항
Connect SDK를 설치하기 전에 다음을 준비하세요.
- Bun 런타임 설치
- GitHub Packages 접근 권한 (조직 멤버)
- Doppler 시크릿 설정 (프로젝트별 환경변수)
.npmrc 설정
@modfolio 스코프 패키지는 GitHub Packages에서 배포됩니다.
프로젝트 루트에 .npmrc 파일을 생성하세요.
# .npmrc
@modfolio:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=${GITHUB_TOKEN}GITHUB_TOKEN은 read:packages 권한이 필요합니다.
Doppler에 등록하거나 로컬에서는 환경변수로 설정합니다.
패키지 설치
bun add @modfolio/connect-sdkSDK Exports Map
Connect SDK는 프레임워크별 진입점을 제공합니다.
| Import Path | 프레임워크 | 비고 |
|---|---|---|
@modfolio/connect-sdk/astro |
Astro | 정적 + SSR 지원 |
@modfolio/connect-sdk/sveltekit |
SvelteKit 5 | hooks.server.ts 통합 |
@modfolio/connect-sdk/solidstart |
SolidStart | middleware 통합 |
@modfolio/connect-sdk/qwik |
Qwik | routeLoader$ 통합 |
@modfolio/connect-sdk/nuxt |
Nuxt 3 | server middleware 통합 |
@modfolio/connect-sdk/hono |
Hono | Worker 미들웨어 통합 |
각 진입점은 해당 프레임워크의 미들웨어 시스템에 맞는 API를 제공합니다.
Astro 설정 (전체 예시)
1. Auth 인스턴스 생성
// src/lib/connect.ts
import { createAstroAuth } from "@modfolio/connect-sdk/astro";
export const auth = createAstroAuth({
clientId: "your-app-name",
});clientId는 앱의 고유 식별자입니다. Connect에 등록된 이름과 일치해야 합니다.
2. 미들웨어 등록
// src/middleware.ts
import { auth } from "./lib/connect";
export const onRequest = auth.middleware;미들웨어는 모든 요청에서 쿠키를 파싱하고 JWT를 검증합니다.
인증된 사용자 정보는 Astro.locals.user에 자동으로 설정됩니다.
3. 인증 라우트 핸들러
세 개의 엔드포인트를 생성합니다.
// src/pages/auth/login.ts
import { auth } from "../../lib/connect";
export const GET = auth.loginHandler;// src/pages/auth/callback.ts
import { auth } from "../../lib/connect";
export const GET = auth.callbackHandler;// src/pages/auth/logout.ts
import { auth } from "../../lib/connect";
export const GET = auth.logoutHandler;| 핸들러 | 경로 | 동작 |
|---|---|---|
loginHandler |
/auth/login |
PKCE 생성 후 Connect로 리다이렉트 |
callbackHandler |
/auth/callback |
Authorization Code를 토큰으로 교환, 세션 쿠키 설정 |
logoutHandler |
/auth/logout |
세션 쿠키 삭제, Connect 로그아웃 호출 |
SvelteKit 설정 (요약)
1. Auth 인스턴스 생성
// src/lib/server/auth.ts
import { createSvelteKitAuth } from "@modfolio/connect-sdk/sveltekit";
export const auth = createSvelteKitAuth({
clientId: "your-app-name",
});2. Server Hook 등록
// src/hooks.server.ts
import { auth } from "$lib/server/auth";
export const handle = auth.handle;SvelteKit에서는 handle 함수가 미들웨어 역할을 합니다.
event.locals.user에 인증된 사용자 정보가 설정됩니다.
3. 인증 라우트 핸들러
// src/routes/auth/login/+server.ts
import { auth } from "$lib/server/auth";
export const GET = auth.loginHandler;// src/routes/auth/callback/+server.ts
import { auth } from "$lib/server/auth";
export const GET = auth.callbackHandler;// src/routes/auth/logout/+server.ts
import { auth } from "$lib/server/auth";
export const GET = auth.logoutHandler;환경변수
SDK가 내부적으로 사용하는 환경변수입니다. Doppler에서 관리합니다.
| 변수명 | 필수 | 설명 |
|---|---|---|
CONNECT_URL |
아니오 | Connect 서버 URL (기본: https://connect.modfolio.io) |
CONNECT_CLIENT_SECRET |
아니오 | Confidential client인 경우에만 필요 |
대부분의 앱은 public client이므로 별도 시크릿 설정 없이 clientId만으로 연동됩니다.