이 내용이 도움이 되었나요?

WebView ​

create-ait-app을 사용하면 앱인토스 WebView 미니앱 프로젝트를 빠르게 시작할 수 있어요.

처음 시작한다면

앱인토스 개발이 처음이거나 AI와 함께 빠르게 미니앱을 만들어보고 싶다면,
바이브 코딩으로 미니앱 만들기 문서를 먼저 읽어보세요.

프로젝트 만들기 ​

앱을 만들 위치에서 다음 명령어를 실행하세요.

sh
npx create-ait-app <app-name>
sh
npm create ait-app <app-name>
sh
yarn create ait-app <app-name>
sh
pnpm create ait-app <app-name>

실행하면 대화형 프롬프트가 나와요. 아래 항목을 차례로 선택하세요.

항목설명
TDS (Toss Design System)토스 디자인 시스템 사용 여부를 선택해요. 비게임 미니앱은 TDS 사용이 필수예요.
AI SkillsCursor, Claude Code, Codex 등 AI 코딩 도구를 위한 스킬 파일을 추가할지 선택해요.
예제 코드인앱결제, 인앱광고 등 필요한 예제 코드를 추가할 수 있어요.

선택이 끝나면 프로젝트가 자동으로 생성돼요. 프로젝트 폴더로 이동한 뒤 의존성을 설치하세요.

sh
cd <app-name>
npm install
sh
cd <app-name>
yarn install
sh
cd <app-name>
pnpm install

프로젝트 실행하기 ​

sh
npm run dev
sh
yarn dev
sh
pnpm run dev

개발 서버가 실행되면 샌드박스 앱에서 미니앱을 확인할 수 있어요.

샌드박스 앱을 아직 설치하지 않았다면?

샌드박스 앱은 미니앱을 테스트하기 위한 전용 앱이에요.
iOS 설치 가이드 또는 Android 설치 가이드를 참고해 주세요.

샌드박스 앱에서 테스트하는 자세한 방법은 샌드박스앱 문서를 확인해 주세요.

설정 파일 수정하기 ​

프로젝트를 생성하면 granite.config.ts 파일이 자동으로 만들어져요.
이 파일에서 appName, displayName, icon을 앱인토스 콘솔에 등록한 앱 정보와 동일하게 수정해 주세요.

ts
import { defineConfig } from '@apps-in-toss/web-framework/config';

export default defineConfig({
  appName: 'my-granite-app', // 앱인토스 콘솔에서 등록한 앱 이름으로 바꿔주세요.
  brand: {
    displayName: '앱 이름', // 앱인토스 콘솔에 등록한 앱의 한글 이름으로 바꿔주세요.
    primaryColor: '#81C784', // 화면에 노출될 앱의 기본 색상으로 바꿔주세요.
    icon: '', // 화면에 노출될 앱의 아이콘 이미지 주소로 바꿔주세요.
  },
  web: {
    host: 'localhost',
    port: 5173,
    commands: {
      dev: 'vite dev',
      build: 'vite build',
    },
  },
  permissions: [],
  outdir: 'dist',
});

중요해요

  • appName은 각 앱을 식별하는 고유한 키로 사용돼요.
  • intoss://{appName} 형태의 딥링크 경로나 테스트·배포 시에도 사용돼요.
  • 샌드박스 앱에서 테스트할 때도 intoss://{appName}으로 접근해요.
    단, 출시하기 메뉴의 QR 코드로 테스트할 때는 intoss-private://{appName}이 사용돼요.

자세한 설정 방법은 공통 설정 문서를 확인해 주세요.

기존 웹 프로젝트에 SDK 추가하기 ​

기존 웹 프로젝트에 @apps-in-toss/web-framework를 직접 설치해서 시작할 수도 있어요.

1. SDK 설치하기 ​

sh
npm install @apps-in-toss/web-framework
sh
pnpm install @apps-in-toss/web-framework
sh
yarn add @apps-in-toss/web-framework

2. 환경 초기화하기 ​

sh
npx ait init
sh
pnpm ait init
sh
yarn ait init
  1. web-framework를 선택하세요.
  2. 앱 이름(appName)을 입력하세요. 앱인토스 콘솔에서 등록한 이름과 동일하게 입력해 주세요.
  3. 웹 번들러의 dev 명령어를 입력해 주세요.
  4. 웹 번들러의 build 명령어를 입력해 주세요.
  5. 웹 개발 서버에서 사용할 포트 번호를 입력하세요.

초기화가 완료되면 granite.config.ts 파일이 생성돼요.
설정 방법은 설정 파일 수정하기를 확인해 주세요.

3. 실행하기 ​

sh
npm run dev
sh
pnpm run dev
sh
yarn dev

AI 코딩 도구를 활용하고 싶다면?

Cursor, Claude Code, Codex 등 AI 도구와 함께 개발하는 방법은 LLMs 가이드를 참고해 주세요.

미니앱 실행하기 ​

개발 서버를 실행한 뒤, 샌드박스 앱에서 미니앱을 확인할 수 있어요.
디바이스별 실행 방법은 아래 문서를 참고해 주세요.

개발 서버를 실기기에서 접근 가능하게 설정하기 ​

실기기에서 테스트하려면 번들러를 실행할 때 --host 옵션을 활성화하고, web.host를 실 기기에서 접근할 수 있는 네트워크 주소로 설정해야 해요.

ts
import { defineConfig } from '@apps-in-toss/web-framework/config';

export default defineConfig({
  appName: 'ping-pong',
  web: {
    host: '192.168.0.100', // 실 기기에서 접근할 수 있는 IP 주소로 변경
    port: 5173,
    commands: {
      dev: 'vite --host', // --host 옵션 활성화
      build: 'vite build',
    },
  },
  permissions: [],
});

빌드하고 토스앱에서 최종 테스트하기 ​

샌드박스 앱에서 개발과 기본 검증이 끝나면 npm run build로 앱 번들을 생성한 뒤, 토스앱에 업로드해 최종 테스트를 진행해 주세요.
토스앱 테스트를 완료해야 출시 요청을 보낼 수 있어요. 자세한 방법은 토스앱 문서를 참고해 주세요.

출시하기 ​

출시하는 방법은 미니앱 출시 문서를 참고하세요.