SDK 설치

Connect Base JavaScript/TypeScript SDK(connectbase-client)를 환경별로 설치하는 방법입니다.

패키지 설치

bash

# npm
npm install connectbase-client

# yarn
yarn add connectbase-client

# pnpm
pnpm add connectbase-client

환경별 초기화

Vite (React / Vue / Svelte)

bash

# .env
VITE_CONNECT_BASE_PUBLIC_KEY=cb_pk_your_public_key_here

typescript

// src/lib/connectbase.ts
import ConnectBase from 'connectbase-client'

export const cb = new ConnectBase({
  publicKey: import.meta.env.VITE_CONNECT_BASE_PUBLIC_KEY
})

⚠️ Vite에서는 VITE_ 접두사가 붙은 환경 변수만 클라이언트에 노출됩니다.

Next.js (App Router / Pages Router)

bash

# .env.local
NEXT_PUBLIC_CONNECT_BASE_PUBLIC_KEY=cb_pk_your_public_key_here
# 서버 컴포넌트/라우트 핸들러에서만 사용 (브라우저 노출 금지)
CONNECT_BASE_SECRET_KEY=cb_sk_your_secret_key_here

typescript

// app/lib/connectbase.ts (클라이언트 컴포넌트용)
'use client'
import ConnectBase from 'connectbase-client'

export const cb = new ConnectBase({
  publicKey: process.env.NEXT_PUBLIC_CONNECT_BASE_PUBLIC_KEY
})

typescript

// app/lib/connectbase-server.ts (서버 전용)
import ConnectBase from 'connectbase-client'

// 서버에서만 사용 — Secret Key는 절대 client component로 import하지 마세요.
export const cbServer = new ConnectBase({
  secretKey: process.env.CONNECT_BASE_SECRET_KEY
})

Node.js / Express (백엔드)

bash

# .env
CONNECT_BASE_SECRET_KEY=cb_sk_your_secret_key_here

typescript

// server.ts
import 'dotenv/config'
import express from 'express'
import ConnectBase from 'connectbase-client'

const cb = new ConnectBase({
  secretKey: process.env.CONNECT_BASE_SECRET_KEY
})

const app = express()
app.use(express.json())

app.get('/users', async (_req, res) => {
  const result = await cb.database.getData('tbl_users', { limit: 50 })
  res.json(result.data)
})

app.listen(3000, () => console.log('http://localhost:3000'))

서버 환경에서는 더 강한 권한을 가진 cb_sk_* Secret Key를 사용해도 안전합니다.

React Native / Expo

bash

# .env (expo)
EXPO_PUBLIC_CONNECT_BASE_PUBLIC_KEY=cb_pk_your_public_key_here

typescript

// lib/connectbase.ts
import ConnectBase from 'connectbase-client'

export const cb = new ConnectBase({
  publicKey: process.env.EXPO_PUBLIC_CONNECT_BASE_PUBLIC_KEY
})

고급 옵션

typescript

import ConnectBase from 'connectbase-client'

const cb = new ConnectBase({
  publicKey: 'cb_pk_...',

  // 선택 옵션 — 셀프호스트하지 않는다면 그대로 두세요
  baseUrl: 'https://api.connectbase.world',      // API 서버 URL
  socketUrl: 'https://socket.connectbase.world', // WebSocket 서버 URL
  webrtcUrl: 'https://webrtc.connectbase.world', // WebRTC
  videoUrl: 'https://video.connectbase.world',   // Video
  gameUrl: 'https://game.connectbase.world',     // Game

  // 앱 ID (WebRTC, Game 일부 기능에 필요)
  appId: 'app_xxx',

  // 토큰이 갱신될 때 호출 (앱 멤버 로그인 후 자동 갱신 시)
  onTokenRefresh: ({ accessToken, refreshToken }) => {
    localStorage.setItem('cb_access_token', accessToken)
    localStorage.setItem('cb_refresh_token', refreshToken)
  },

  // 401 등 인증 에러 발생 시 호출
  onAuthError: (error) => {
    console.error('인증 에러:', error)
  },

  // 리프레시 토큰까지 만료되어 재로그인이 필요할 때 호출
  onTokenExpired: () => {
    window.location.href = '/login'
  }
})

사용 가능한 모듈

SDK 초기화 후 다음 모듈을 사용할 수 있습니다:

모듈	설명
`cb.auth`	앱 멤버 인증 (회원가입, 로그인, 세션)
`cb.oauth`	소셜 로그인 (Google, GitHub, Naver, Discord)
`cb.database`	JSON 데이터베이스 CRUD
`cb.storage`	파일 업로드/다운로드
`cb.functions`	서버리스 함수 호출
`cb.realtime`	WebSocket 실시간 통신
`cb.webrtc`	영상/음성 통화
`cb.video`	동영상 업로드/스트리밍
`cb.game`	실시간 멀티플레이어 게임
`cb.push`	푸시 알림
`cb.payment`	결제 (토스페이먼츠)
`cb.subscription`	정기결제 / 멤버십
`cb.knowledge`	AI 데이터베이스 (문서 검색)
`cb.queue`	메시지 큐 (NATS JetStream)
`cb.ads`	Google AdSense
`cb.errorTracker`	클라이언트 에러 리포팅

TypeScript 지원

SDK는 TypeScript로 작성되어 자동완성과 타입 검증을 지원합니다.

typescript

import ConnectBase, { ApiError, AuthError } from 'connectbase-client'

const cb = new ConnectBase({ publicKey: 'cb_pk_...' })

try {
  const result = await cb.database.getData('tbl_xxx')
  console.log(result.data)
} catch (e) {
  if (e instanceof ApiError) {
    console.error('API 에러:', e.statusCode, e.message)
  } else if (e instanceof AuthError) {
    console.error('인증 에러:', e.message)
  }
}

다음 단계

인증 설정 — Public Key 발급 흐름과 cb_pk_ vs cb_sk_ 구분
첫 번째 앱 — 실습 튜토리얼
흔한 에러 & 해결책

빠른 시작 가이드

인증 설정