Guide
Quick Start
5분 안에 01.software API 시작하기
빠른 시작
01.software SDK를 사용하여 5분 안에 첫 번째 API 호출을 해보세요.
사전 요구사항
- Node.js 18.20+ 또는 20.9+
- React 19+ (React 훅 사용 시)
- 01.software 계정 및 Client Key
설치
SDK 설치
npm install @01.software/sdk
# 또는
pnpm add @01.software/sdk
# 또는
yarn add @01.software/sdk환경 변수 설정
.env.local 파일을 생성하고 API 키를 설정합니다:
# 브라우저에서 사용 (공개 가능)
NEXT_PUBLIC_SOFTWARE_CLIENT_KEY=your-client-key
# 서버에서만 사용 (비공개)
SOFTWARE_SECRET_KEY=your-secret-keySecret Key는 절대 클라이언트에 노출하지 마세요.
클라이언트 생성
브라우저 클라이언트
// lib/client.ts
import { createBrowserClient } from '@01.software/sdk'
export const client = createBrowserClient({
clientKey: process.env.NEXT_PUBLIC_SOFTWARE_CLIENT_KEY!
})서버 클라이언트
// lib/server-client.ts
import { createServerClient } from '@01.software/sdk'
export const serverClient = createServerClient({
clientKey: process.env.NEXT_PUBLIC_SOFTWARE_CLIENT_KEY!,
secretKey: process.env.SOFTWARE_SECRET_KEY!
})기본 사용법
데이터 조회
// 상품 목록 조회
const response = await client.from('products').find({
limit: 10,
page: 1
})
if (response.success) {
console.log(response.data) // Product[]
console.log(response.pagination) // { totalDocs: 100, hasNextPage: true, ... }
}단일 항목 조회
const response = await client.from('products').findById('product-id')
if (response.success) {
console.log(response.data) // Product
}필터링
const response = await client.from('products').find({
where: {
status: { equals: 'active' },
price: { greater_than: 10000 }
},
sort: '-createdAt',
limit: 20
})에러 처리
import { isSuccessResponse, isErrorResponse } from '@01.software/sdk'
const response = await client.from('products').find()
if (isSuccessResponse(response)) {
// response.data 사용
console.log(response.data)
} else if (isErrorResponse(response)) {
// 에러 처리
console.error(response.error.code)
console.error(response.error.message)
}React에서 사용하기
React Query 훅
'use client'
import { client } from '@/lib/client'
export function ProductList() {
const { data, isLoading, error } = client.query.useCollection('products', {
where: { status: { equals: 'active' } },
limit: 10
})
if (isLoading) return <div>로딩 중...</div>
if (error) return <div>에러 발생</div>
return (
<ul>
{data?.map(product => (
<li key={product.id}>{product.title}</li>
))}
</ul>
)
}단일 항목 조회
export function ProductDetail({ id }: { id: string }) {
const { data, isLoading } = client.query.useById('products', id)
if (isLoading) return <div>로딩 중...</div>
if (!data) return <div>상품을 찾을 수 없습니다</div>
return (
<div>
<h1>{data.title}</h1>
<p>{data.price.toLocaleString()}원</p>
</div>
)
}무한 스크롤
export function ProductInfiniteList() {
const {
data,
fetchNextPage,
hasNextPage,
isFetchingNextPage
} = client.query.useCollectionInfinite('products', {
limit: 20
})
return (
<div>
{data?.map(product => (
<div key={product.id}>{product.title}</div>
))}
{hasNextPage && (
<button
onClick={() => fetchNextPage()}
disabled={isFetchingNextPage}
>
{isFetchingNextPage ? '로딩 중...' : '더 보기'}
</button>
)}
</div>
)
}Next.js App Router에서 사용하기
Server Component
// app/products/page.tsx
import { serverClient } from '@/lib/server-client'
export default async function ProductsPage() {
const response = await serverClient.from('products').find({
limit: 20
})
if (!response.success) {
return <div>데이터를 불러올 수 없습니다</div>
}
return (
<ul>
{response.data.map(product => (
<li key={product.id}>{product.title}</li>
))}
</ul>
)
}Client Component + Server Prefetch
// app/products/page.tsx
import { HydrationBoundary, dehydrate } from '@tanstack/react-query'
import { client } from '@/lib/client'
import { ProductList } from './product-list'
export default async function ProductsPage() {
// 서버에서 데이터 미리 가져오기
await client.query.prefetchCollection('products', { limit: 20 })
return (
<HydrationBoundary state={dehydrate(client.queryClient)}>
<ProductList />
</HydrationBoundary>
)
}