트리 셰이킹 및 번들 최적화
TanStack AI는 처음부터 최대한의 트리 셰이킹을 고려해 설계되었습니다. 활동 함수부터 어댑터까지 전체 시스템이 함수형 모듈식 아키텍처를 사용하므로 실제로 사용하는 코드만 번들에 포함됩니다.
설계 철학
모든 기능을 포함하는 모놀리식 API 대신 TanStack AI는 다음을 제공합니다.
- 개별 활동 함수 - 필요한 활동만 가져옵니다(
chat,summarize등). - 개별 어댑터 함수 - 필요한 어댑터만 가져옵니다(
openaiText,openaiSummarize등). - 함수형 API 설계 - 번들러가 쉽게 제거할 수 있는 순수 함수입니다.
- 별도 모듈 - 각 활동과 어댑터가 자체 모듈에 있습니다.
따라서 OpenAI와 함께 chat만 사용하면 요약, 이미지 생성 또는 다른 프로바이더의 코드가 번들에 포함되지 않습니다.
활동 함수
각 AI 활동은 @tanstack/ai에서 별도의 함수로 내보냅니다.
// Import only the activities you need
import { chat } from '@tanstack/ai' // Chat/text generation
import { summarize } from '@tanstack/ai' // Summarization
import { generateImage } from '@tanstack/ai' // Image generation
import { generateSpeech } from '@tanstack/ai' // Text-to-speech
import { generateTranscription } from '@tanstack/ai' // Audio transcription
import { generateVideo } from '@tanstack/ai' // Video generation
예시: 채팅만 사용
채팅 기능만 필요하다면 다음과 같이 합니다.
// Only chat code is bundled
import { chat } from '@tanstack/ai'
import { openaiText } from '@tanstack/ai-openai'
const stream = chat({
adapter: openaiText('gpt-5.5'),
messages: [{ role: 'user', content: 'Hello!' }],
})
번들에는 다음 항목이 포함되지 않습니다:
- 요약 로직
- 이미지 생성 로직
- 기타 activity 구현
어댑터 함수
각 프로바이더 패키지는 활동 유형별로 개별 어댑터 함수를 내보냅니다.
OpenAI
import {
openaiText, // Chat/text generation
openaiSummarize, // Summarization
openaiImage, // Image generation
openaiSpeech, // Text-to-speech
openaiTranscription, // Audio transcription
openaiVideo, // Video generation
} from '@tanstack/ai-openai'
Anthropic
import {
anthropicText, // Chat/text generation
anthropicSummarize, // Summarization
} from '@tanstack/ai-anthropic'
Gemini
import {
geminiText, // Chat/text generation
geminiSummarize, // Summarization
geminiImage, // Image generation
geminiSpeech, // Text-to-speech (experimental)
} from '@tanstack/ai-gemini'
Ollama
import {
ollamaText, // Chat/text generation
ollamaSummarize, // Summarization
} from '@tanstack/ai-ollama'
전체 예시
트리 셰이킹 가능한 설계는 실제로 다음과 같이 동작합니다.
// Only import what you need
import { chat } from '@tanstack/ai'
import { openaiText } from '@tanstack/ai-openai'
// Chat generation - returns AsyncIterable<StreamChunk>
const chatResult = chat({
adapter: openaiText('gpt-5.5'),
messages: [{ role: 'user', content: 'Hello!' }],
})
for await (const chunk of chatResult) {
console.log(chunk)
}
번들에 포함되는 항목:
- ✅
chat함수와 해당 종속성 - ✅
openaiText어댑터와 해당 종속성 - ✅ 채팅 전용 스트리밍 및 도구 처리 로직
번들에 포함되지 않는 항목:
- ❌
summarize함수 - ❌
generateImage함수 - ❌ 기타 어댑터 구현(Anthropic, Gemini 등)
- ❌ 기타 activity 구현
여러 활동 사용
여러 활동이 필요하다면 사용하는 것만 가져옵니다.
import { chat, summarize } from '@tanstack/ai'
import {
openaiText,
openaiSummarize
} from '@tanstack/ai-openai'
// Each activity is independent
const chatResult = chat({
adapter: openaiText('gpt-5.5'),
messages: [{ role: 'user', content: 'Hello!' }],
})
const summarizeResult = await summarize({
adapter: openaiSummarize('gpt-5.4-mini'),
text: 'Long text to summarize...',
})
각 활동은 자체 모듈에 있으므로 번들러가 사용하지 않는 활동을 제거할 수 있습니다.
타입 안전성
트리 셰이킹 가능한 설계는 타입 안전성을 희생하지 않습니다. 각 어댑터는 지원하는 모델에 완전한 타입 안전성을 제공합니다.
import { openaiText, type OpenAIChatModel } from '@tanstack/ai-openai'
const adapter = openaiText('gpt-5.5')
// TypeScript knows the exact models supported
const model: OpenAIChatModel = 'gpt-5.5' // ✓ Valid
const model2: OpenAIChatModel = 'invalid' // ✗ Type error
Create 옵션 함수
create___Options 함수에도 tree-shaking이 적용됩니다:
import {
createChatOptions,
createImageOptions
} from '@tanstack/ai'
import { openaiText } from '@tanstack/ai-openai'
// Only import what you need
const chatOptions = createChatOptions({
adapter: openaiText('gpt-5.5'),
})
번들 크기의 이점
함수형 모듈식 설계는 번들 크기를 크게 줄여 줍니다.
모든 것 가져오기 (비효율적)
// ❌ Importing more than needed
import * as ai from '@tanstack/ai'
import * as openai from '@tanstack/ai-openai'
// This bundles all exports from both packages
필요한 것만 가져오기 (권장)
// ✅ Only what you use gets bundled
import { chat } from '@tanstack/ai'
import { openaiText } from '@tanstack/ai-openai'
// You only get:
// - Chat activity implementation
// - OpenAI text adapter
// - Chat-specific dependencies
실제 영향
일반적인 채팅 애플리케이션의 경우, 단일 액티비티와 어댑터를 가져오면 모든 액티비티와 모든 제공자 어댑터를 번들링하는 것보다 훨씬 적은 코드를 가져옵니다. 각 액티비티와 어댑터가 자체 부작용 없는 모듈에 존재하므로, 번들러는 참조하지 않는 모든 것을 제거합니다 — 따라서 라이브러리가 지원하는 제공자와 액티비티가 많을수록 집중된 가져오기와 네임스페이스 가져오기 간의 차이가 더 커집니다.
작동 방식
트리 셰이킹은 다음을 통해 구현됩니다.
- ES 모듈 내보내기 - 각 함수는 기본 내보내기가 아닌 이름이 지정된 내보내기입니다
- 별도 모듈 - 각 활동과 어댑터가 자체 파일에 있습니다.
- 부작용 없음 - 함수는 순수하며 모듈 수준의 부작용이 없습니다
- 기능적 합성 - 함수들이 서로 결합되어 죽은 코드 제거를 가능하게 합니다
- 타입 전용 가져오기 - 타입 가져오기는 빌드 시 제거됩니다.
최신 번들러(Vite, Webpack, Rollup, esbuild)는 다음 이유로 사용하지 않는 코드를 쉽게 제거할 수 있습니다.
- 함수는 정적 분석이 가능함
- 사용하지 않는 코드의 동적 가져오기 없음
- 모듈 레벨의 사이드 이펙트 없음
- 명확한 의존성 그래프
권장 사항
- 필요한 것만 가져오세요 - 전체 네임스페이스를 가져오지 마세요
- 특정 어댑터 함수를 사용하세요 -
openaiText를openai대신 가져오세요 - 라우트에 따라 작업을 분리하세요 - 다른 API 라우트는 다른 작업을 사용할 수 있습니다
- 가능하면 게으르게 로드하세요 - 코드 분할 라우트를 위한 동적 가져오기를 사용하세요
- 모바일 채팅 번들을 클라이언트 전용으로 유지하세요 - React Native 및 Expo 채팅 화면은 제공자 SDK, 서버 응답 헬퍼, React DOM UI, 개발자 도구 UI 또는 기타 프레임워크 패키지가 아닌
useChat와 채팅 연결 어댑터를 가져와야 합니다. 빠른 시작: React Native를 참조하여 서버 전용 제공자 경계 및 모바일 전송 설정을 확인하세요.
// ✅ Good - Only imports chat
import { chat } from '@tanstack/ai'
import { openaiText } from '@tanstack/ai-openai'
// ❌ Bad - Imports everything
import * as ai from '@tanstack/ai'
import * as openai from '@tanstack/ai-openai'
어댑터 타입
각 어댑터 유형은 특정 인터페이스를 구현합니다:
ChatAdapter- 스트리밍 채팅 응답을 위한chatStream()메서드를 제공합니다SummarizeAdapter- 텍스트 요약화를 위한summarize()메서드를 제공합니다ImageAdapter- 이미지 생성을 위한generateImage()메서드를 제공합니다TTSAdapter- 텍스트-음성 변환을 위한generateSpeech()메서드를 제공합니다TranscriptionAdapter- 오디오 전사화를 위한generateTranscription()메서드를 제공합니다VideoAdapter- 비디오 생성을 위한generateVideo()메서드를 제공합니다
모든 어댑터에는 유형을 나타내는 kind 속성이 있습니다.
import { openaiText, openaiSummarize } from '@tanstack/ai-openai'
const chatAdapter = openaiText('gpt-5.5')
console.log(chatAdapter.kind) // 'text'
const summarizeAdapter = openaiSummarize('gpt-5.4-mini')
console.log(summarizeAdapter.kind) // 'summarize'
요약
TanStack AI 의 트리 셰이커블 설계는 다음과 같습니다:
- ✅ 더 작은 번들 - 실제로 사용하는 코드만 포함합니다.
- ✅ 더 빠른 로드 시간 - 다운로드하고 파싱할 JavaScript가 줄어듭니다.
- ✅ 더 나은 성능 - 코드가 적어 실행이 빨라집니다.
- ✅ 타입 안전성 - 런타임 오버헤드 없이 TypeScript를 완전히 지원합니다.
- ✅ 유연성 - 필요에 따라 활동과 어댑터를 조합합니다.
함수형 모듈식 아키텍처는 최신 번들러가 사용하지 않는 코드를 효과적으로 제거하도록 하여 애플리케이션의 번들 크기를 최적화합니다.