프로젝트 구조

Tauri 프로젝트는 평범한 웹 프로젝트 안에 Rust 프로젝트 하나가 src-tauri 폴더로 들어 있는 모양입니다. 이 장에서는 각 파일이 하는 일과 설정 파일 tauri.conf.json, 권한을 정하는 capabilities 폴더를 차례로 살펴봅니다.

전체 모양

Vite와 TypeScript 템플릿으로 만든 프로젝트는 대략 다음과 같습니다.

tauri-app/
├── package.json          # 프런트엔드 의존성과 스크립트
├── index.html
├── vite.config.ts
├── src/                  # 프런트엔드 코드
│   └── main.ts
└── src-tauri/            # Rust 코어
    ├── Cargo.toml
    ├── build.rs
    ├── tauri.conf.json   # Tauri 설정
    ├── capabilities/
    │   └── default.json  # 창별 권한
    ├── icons/
    └── src/
        ├── main.rs       # 데스크톱 진입점
        └── lib.rs        # 앱 본체(모바일과 공유)

프런트엔드 쪽은 일반 웹 프로젝트와 다르지 않습니다. 어떤 프레임워크든 정적 파일(HTML · CSS · JavaScript)로 빌드할 수 있으면 쓸 수 있습니다. 다만 Tauri는 Node.js 서버를 함께 실행하지 않으므로, Next.js나 SvelteKit 같은 프레임워크는 정적 내보내기(SSG/SPA) 모드로 설정해야 합니다.

src-tauri: Rust 코어

Cargo.toml은 Rust 쪽 의존성을 적는 파일입니다. 템플릿은 라이브러리 크레이트를 만들고, 데스크톱 실행 파일과 모바일 빌드가 이 라이브러리를 함께 씁니다.

[package]
name = "tauri-app"
version = "0.1.0"
edition = "2021"

[lib]
name = "tauri_app_lib"
crate-type = ["staticlib", "cdylib", "rlib"]

[build-dependencies]
tauri-build = { version = "2", features = [] }

[dependencies]
tauri = { version = "2", features = [] }
tauri-plugin-opener = "2"
serde = { version = "1", features = ["derive"] }
serde_json = "1"

build.rs는 tauri_build::build() 한 줄을 실행해 설정과 권한 파일을 읽고 컴파일에 필요한 코드를 생성합니다. main.rs는 데스크톱 진입점으로, 라이브러리의 run 함수만 부릅니다. 앱의 실제 내용은 lib.rs에 씁니다. 모바일 빌드는 main 함수 대신 #[cfg_attr(mobile, tauri::mobile_entry_point)]가 붙은 run 함수를 진입점으로 쓰기 때문에 이렇게 나뉘어 있습니다.

// src-tauri/src/main.rs
// 릴리스 빌드에서 Windows 콘솔 창이 뜨지 않게 합니다
#![cfg_attr(not(debug_assertions), windows_subsystem = "windows")]

fn main() {
    tauri_app_lib::run()
}

tauri.conf.json

앱 이름, 버전, 창, 보안, 번들 설정이 모두 이 파일에 들어갑니다. 템플릿의 기본 모양은 다음과 같습니다.

{
  "$schema": "https://schema.tauri.app/config/2",
  "productName": "tauri-app",
  "version": "0.1.0",
  "identifier": "com.example.tauri-app",
  "build": {
    "beforeDevCommand": "npm run dev",
    "devUrl": "http://localhost:1420",
    "beforeBuildCommand": "npm run build",
    "frontendDist": "../dist"
  },
  "app": {
    "windows": [{ "title": "tauri-app", "width": 800, "height": 600 }],
    "security": { "csp": null }
  },
  "bundle": {
    "active": true,
    "targets": "all",
    "icon": ["icons/32x32.png", "icons/128x128.png", "icons/icon.icns", "icons/icon.ico"]
  }
}

플랫폼마다 설정을 달리하려면 tauri.windows.conf.json, tauri.macos.conf.json, tauri.linux.conf.json, tauri.android.conf.json, tauri.ios.conf.json을 같은 폴더에 둡니다. 해당 플랫폼으로 빌드할 때 기본 설정 위에 덮어씌워집니다. --config 옵션으로 다른 설정 파일을 합칠 수도 있습니다.

capabilities: 창별 권한

Tauri 2에서는 WebView 안의 코드가 어떤 기능을 쓸 수 있는지 capability 파일로 정합니다. src-tauri/capabilities 폴더의 파일은 기본적으로 모두 적용됩니다.

{
  "$schema": "../gen/schemas/desktop-schema.json",
  "identifier": "default",
  "description": "main 창에 주는 기본 권한",
  "windows": ["main"],
  "permissions": ["core:default", "opener:default"]
}

windows에는 이 권한을 받을 창의 라벨을, permissions에는 허용할 권한 식별자를 적습니다. gen/schemas 폴더는 빌드할 때 자동으로 생성되며, 여기에 담긴 스키마 덕분에 편집기에서 쓸 수 있는 권한 이름이 자동 완성됩니다. 자세한 보안 모델은 3장에서 다룹니다.

그 밖의 관례

• icons/의 아이콘은 직접 그리지 말고 npm run tauri icon으로 한 번에 만듭니다.
• 템플릿의 Vite 설정은 개발 서버 포트를 고정하고(strictPort), src-tauri 폴더 변경은 감시하지 않도록 되어 있습니다.
• src-tauri/target은 Rust 빌드 결과이므로 저장소에 넣지 않습니다. Cargo.lock은 커밋합니다.
• Rust 코드가 커지면 lib.rs에는 앱 조립만 남기고 명령은 commands.rs 같은 모듈로 나눕니다.

정리

• 프런트엔드는 일반 웹 프로젝트이고, Rust 코어는 src-tauri에 있습니다.
• 앱 본체는 lib.rs의 run 함수에 쓰고 main.rs는 그것을 부르기만 합니다.
• tauri.conf.json이 빌드 · 창 · 보안 · 번들 설정을 맡고, 플랫폼별 파일로 덮어쓸 수 있습니다.
• capabilities 폴더의 파일이 창마다 허용할 권한을 정합니다.