설치 | Solana

JavaScript SDK를 설치하고 개발 환경을 설정하여 Solana Pay를 시작하세요. 이 SDK는 프레임워크에 구애받지 않으며 모든 JavaScript 환경에서 작동합니다.

시스템 요구사항

Node.js: 버전 20 이상 (Ed25519 crypto.subtle 지원 필수)
패키지 매니저: pnpm, npm 또는 yarn
TypeScript: 버전 5 이상 (권장사항이나 필수는 아님)

Solana Pay SDK 설치

원하는 패키지 매니저를 선택하세요:

# Using pnpm (recommended)
pnpm add @solana/pay@beta @solana/kit

# Using npm
npm install @solana/pay@beta @solana/kit

# Using yarn
yarn add @solana/pay@beta @solana/kit

피어 의존성

다음은 @solana/pay의 피어 의존성이며 함께 설치되어야 합니다:

패키지	버전
`@solana/kit`	`^6.5.0`

선택적 의존성

전송 생성 및 검증 (SOL 및 SPL 토큰 전송)을 위해서는 다음도 설치하세요:

pnpm add @solana-program/system @solana-program/token @solana-program/token-2022 @solana-program/memo

클라이언트 팩토리 (createMerchantClient, createWalletClient)를 위해서는 킷 플러그인도 설치하세요:

pnpm add @solana/kit-plugin-rpc @solana/kit-plugin-payer @solana/kit-plugin-instruction-plan

TypeScript 구성

TypeScript를 사용하는 경우, tsconfig.json에 다음을 포함해야 합니다:

{
  "compilerOptions": {
    "module": "ESNext",
    "target": "ES2022",
    "lib": ["ES2022", "DOM", "DOM.Iterable"],
    "moduleResolution": "bundler",
    "resolveJsonModule": true,
    "esModuleInterop": true,
    "skipLibCheck": true
  }
}

환경 설정

개발 환경

개발을 위한 환경 변수를 설정하세요:

# .env.local
SOLANA_RPC_URL=https://api.devnet.solana.com
SOLANA_NETWORK=devnet

프로덕션 환경

프로덕션의 경우 메인넷 엔드포인트를 사용하세요:

# .env.production
SOLANA_RPC_URL=https://api.mainnet-beta.solana.com
SOLANA_NETWORK=mainnet-beta

설치 확인

모든 것이 정상적으로 작동하는지 확인하기 위해 간단한 테스트를 만들어보세요:

// test-installation.ts
import { address } from "@solana/kit";
import { encodeURL } from "@solana/pay";

// Test creating a payment URL
const recipient = address("FvJ8k8HhXp4a3zQyFMZd4FvEqcYdYE7gSZWxrEBRfBsB");

const url = encodeURL({
  recipient,
  amount: 0.01,
  label: "Test Store",
  message: "Test payment"
});

console.log("Solana Pay URL:", url.toString());
// Output: solana:FvJ8k8Hh...?amount=0.01&label=Test%20Store&message=Test%20payment

테스트를 실행하세요:

npx tsx test-installation.ts

콘솔에 유효한 Solana Pay URL이 표시되어야 합니다.

일반적인 문제 및 해결 방법

모듈 해석 오류

"Cannot resolve module '@solana/pay'"와 같은 오류가 발생하는 경우:

패키지 관리자 캐시를 지우세요:

# pnpm
pnpm store prune

# npm
npm cache clean --force

# yarn
yarn cache clean

node_modules를 삭제하고 재설치하세요:
```
rm -rf node_modules
pnpm install
```

TypeScript 오류

TypeScript 오류가 발생하는 경우:

최신 TypeScript 버전(5+)으로 업데이트하세요
tsconfig.json에서 moduleResolution가 "bundler" 또는 "nodenext"로 설정되어 있는지 확인하세요

다음 단계

Solana Pay가 설치되었으니, 통합 방법을 선택하세요:

전송 요청 - 기본 전송을 위한 간단한 결제 URL
트랜잭션 요청 - 상호작용 결제 플로우
QR 코드 통합 - 모바일 결제를 위한 QR 코드 생성

개발 도구

다음과 같은 유용한 개발 도구 설치를 고려해보세요:

# Solana CLI (for testing and key generation)
sh -c "$(curl -sSfL https://release.anza.xyz/stable/install)"

# Local validator for testing
solana-test-validator

리소스

GitHub 저장소 - 소스 코드 및 예제
Solana Cookbook - Solana 개발 레시피

목차