| name | create-mini-app |
| description | Scaffold a new Apps In Toss (앱인토스) mini-app. Use when the user asks to create / start / scaffold a new Apps In Toss mini-app, 앱인토스 미니앱, AIT app, or Granite app — either the WebView flavor (create-ait-app) or the React Native flavor (create granite-app). |
Create an Apps In Toss mini-app
Help the user scaffold a brand-new Apps In Toss (앱인토스) mini-app from scratch.
Two frameworks are supported — pick exactly one, then drive the official CLI.
| Flavor | When to use | Scaffolder |
|---|
| WebView | User has (or wants) a web stack — Vite, Next.js, plain HTML/CSS. Fastest to start. | create-ait-app |
| React Native (Granite) | User wants native-feel UI, file-based routing, or React Native DX. Required for some 앱인토스 features. | create granite-app + ait init |
Arguments (optional, order-independent):
$0 — app name (kebab-case, e.g. my-mini-app)$1 — webview or react-native
If either is missing, ask the user. Never guess.
Step 1 — Gather requirements
Before running anything, confirm all of the following with the user (reuse earlier conversation context if it already answers a bullet):
- Framework — WebView or React Native?
Heuristics for asking:
- User says "RN", "React Native", "granite", "native UI" → React Native.
- User says "웹뷰", "WebView", already has a Vite/Next project, or is unsure → WebView.
- Otherwise ask a single direct question with both options.
- App name — kebab-case only (
^[a-z][a-z0-9-]*$).
Warn: this value becomes the 딥링크 key intoss://{appName} and must match what is registered in the 앱인토스 콘솔 later.
- Target directory — verify the current working directory with
pwd. The scaffolder will create a new folder named <app-name> inside it. Abort if <app-name> already exists (use Glob or test -e).
Do not proceed to Step 2 until these three are settled.
Step 2 — Pick the package manager
Pick in this order, then tell the user which one you chose:
- Explicit request from the user.
- Lockfile in the current directory —
pnpm-lock.yaml → pnpm, yarn.lock → yarn, package-lock.json → npm.
packageManager field in a nearby package.json.- Default to
npm.
Never silently switch between npm / pnpm / yarn mid-flow.
Step 3 — Run the scaffolder
Both CLIs are interactive. The Bash tool may not forward stdin in every environment. If a prompt-driven command hangs, stop it, tell the user to run the command themselves in a real terminal, and resume from Step 4 once they report completion.
A. WebView (create-ait-app)
Run from the user's current directory:
npx create-ait-app <app-name>
npm create ait-app <app-name>
pnpm create ait-app <app-name>
yarn create ait-app <app-name>
Before executing, warn the user about the prompts they will see:
- TDS (Toss Design System) — required for all non-game mini-apps. Say yes unless they are building a game.
- AI Skills — adds Cursor / Claude Code / Codex skill files. Recommend yes when the user is developing with Claude Code.
- Example code — optional starter code for in-app purchase, in-app ads, etc. Pick whatever the user asked for.
After the CLI finishes, run dependency install inside the new directory:
cd <app-name>
<pm> install
B. React Native (create granite-app + ait init)
The Granite CLI is a two-stage setup. Run both stages.
Stage 1 — scaffold the Granite project
npm create granite-app
Prompts:
- App name — enter the kebab-case name from Step 1.
- Tooling —
prettier + eslint or biome. Default to whichever the user prefers; biome if unsure.
Then install dependencies:
cd <app-name>
<pm> install
Stage 2 — add the Apps In Toss framework
<pm> add @apps-in-toss/framework
npx ait init
During ait init:
- Pick framework:
react-native.
- Enter appName (same kebab-case value).
Stage 3 — install TDS React Native (required for non-game apps)
Pick the package version by the installed @apps-in-toss/framework version (check the new project's package.json with Read):
@apps-in-toss/framework | Package to install |
|---|
>= 1.0.0 | @toss/tds-react-native |
< 1.0.0 | @toss-design-system/react-native |
<pm> add @toss/tds-react-native
<pm> add @toss-design-system/react-native
Step 4 — Configure granite.config.ts
Both flavors produce a granite.config.ts at the project root. Read it first, then use Edit to fill in the user's values:
appName — must match the name registered in the 앱인토스 콘솔. Do not change this casually later.brand.displayName — Korean-friendly display name shown in the nav bar.brand.primaryColor — hex color (e.g. #3182F6).brand.icon — hosted icon URL. Empty string '' is acceptable during local testing.- WebView only: if the user wants to test on a real device, set
web.host to the dev machine's LAN IP and add --host to the Vite dev command. Suggest ipconfig getifaddr en0 on macOS to find the IP.
Do not invent values — ask the user if a field is unknown.
Step 5 — Hand off with next steps
Tell the user (do not run these automatically):
- Start the dev server:
<pm> run dev
- Install the 앱인토스 sandbox app on iOS / Android (see https://developers-apps-in-toss.toss.im/development/client).
- Open the mini-app via the scheme
intoss://<appName> inside the sandbox app.
- React Native on Android: if running on a real device/emulator, run
adb reverse tcp:8081 tcp:8081
adb reverse tcp:5173 tcp:5173
- For Claude Code + MCP integration, suggest:
claude mcp add --transport stdio apps-in-toss ax mcp start
(after installing ax via Homebrew/Scoop — see https://developers-apps-in-toss.toss.im/development/llms.html).
Guardrails
- Never pick the framework silently. Always get an explicit answer.
- Never overwrite an existing directory. Abort if
<app-name>/ already exists.
- Never skip the interactive prompts by piping in
yes or similar — the CLIs change behavior based on the answers.
- Never edit 앱인토스 콘솔-registered
appName without telling the user it will break deeplinks.
- Never invent commands beyond the ones listed here. If the user needs something outside this flow, stop and ask.
Reference
