설정 파일

Tauri는 애플리케이션을 구축하기 위한 툴킷이므로 프로젝트 설정을 구성하기 위한 파일이 많을 수 있습니다. 흔히 볼 수 있는 일반적인 파일은 tauri.conf.json, package.json, Cargo.toml 등일 것입니다. 이 장에서는 어떤 파일을 수정해야 하는지 올바르게 판단할 수 있도록 각각에 대해 간단히 설명합니다.

《번역 주》 설정과 구성 둘 다 configuration의 번역어. 본고에서는 엄격한 구별 없이 사용하고 있으므로, 번역문에 위화감이 있는 경우 적절히 읽어주십시오.

Tauri 설정

“Tauri 설정”은 웹 앱 소스 정의, 애플리케이션 메타데이터 설명, 번들 설정, 플러그인 구성 설정 및 창, 트레이 아이콘, 메뉴 등의 설정으로 런타임 동작 변경에 사용됩니다.

이 파일은 “Tauri 런타임”과 “Tauri CLI”에서 사용됩니다. “빌드 설정”을 정의하거나(tauri build나 tauri dev가 시작되기 전에 실행되는 명령 등), 앱의 이름이나 버전을 설정하거나, Tauri 런타임 제어, [플러그인 설정] 등을 할 수 있습니다.

지원되는 형식

기본 Tauri 설정 형식은 “JSON”입니다. “JSON5” 또는 “TOML” 형식도 Cargo.toml의 tauri 및 tauri-build 종속성에 config-json5 또는 config-toml 기능 플래그를 각각 추가하여 활성화할 수 있습니다.

[build-dependencies]
tauri-build = { version = "2.0.0", features = [ "config-json5" ] }

[dependencies]
tauri = { version = "2.0.0", features = [  "config-json5" ] }

체계와 값은 모든 형식에서 동일하지만, 서식 설정은 각 파일의 형식과 일치해야 합니다:

{
  build: {
    devUrl: 'http://localhost:3000',
    // start the dev server
    beforeDevCommand: 'npm run dev',
  },
  bundle: {
    active: true,
    icon: ['icons/app.png'],
  },
  app: {
    windows: [
      {
        title: 'MyApp',
      },
    ],
  },
  plugins: {
    updater: {
      pubkey: 'updater pub key',
      endpoints: ['https://my.app.updater/{{target}}/{{current_version}}'],
    },
  },
}

[build]
dev-url = "http://localhost:3000"
# start the dev server
before-dev-command = "npm run dev"

[bundle]
active = true
icon = ["icons/app.png"]

[[app.windows]]
title = "MyApp"

[plugins.updater]
pubkey = "updater pub key"
endpoints = ["https://my.app.updater/{{target}}/{{current_version}}"]

JSON5와 TOML은 주석을 지원하며, TOML에서는 더 관용적인 “케밥 케이스”를 설정 이름에 사용할 수 있다는 점에 유의하십시오.

《번역 주》 케밥 케이스 원문 kebab-case. 복합어를 만들 때 소문자 단어 사이에 하이픈(-)을 넣어 만드는 명명 규칙. 글자를 꼬치에 꽂은 모양으로 보이기 때문에 “케밥 케이스”라고 불립니다.

플랫폼별 설정

기본 설정 파일 외에 Tauri는 다음 위치에서 플랫폼별 설정을 읽을 수 있습니다:

Linux용: tauri.linux.conf.json 또는 Tauri.linux.toml
Windows용: tauri.windows.conf.json 또는 Tauri.windows.toml
macOS용: tauri.macos.conf.json 또는 Tauri.macos.toml
Android용: tauri.android.conf.json 또는 Tauri.android.toml
iOS용: tauri.ios.conf.json 또는 Tauri.ios.toml

플랫폼별 설정 파일은 JSON Merge Patch (RFC 7396) 사양에 따라 기본 설정 객체와 통합(병합)됩니다.

예를 들어, 다음과 같은 기본 tauri.conf.json이 있다고 가정합니다:

{
  "productName": "MyApp",
  "bundle": {
    "resources": ["./resources"]
  },
  "plugins": {
    "deep-link": {}
  }
}

또한 지정된 플랫폼별 tauri.linux.conf.json:

{
  "productName": "my-app",
  "bundle": {
    "resources": ["./linux-assets"]
  },
  "plugins": {
    "cli": {
      "description": "My app",
      "subcommands": {
        "update": {}
      }
    },
    "deep-link": {}
  }
}

Linux용 최종 구성은 다음 객체와 같습니다:

《번역 주》 최종 구성 원문은 resolved configuration. 직역 “해결된 설정/구성”. “최종적으로 결정된” 의미로 해석하여 번역했습니다. 다음 항목 “설정 확장”에서의 표현도 마찬가지입니다.

{
  "productName": "my-app",
  "bundle": {
    "resources": ["./linux-assets"]
  },
  "plugins": {
    "cli": {
      "description": "My app",
      "subcommands": {
        "update": {}
      }
    },
    "deep-link": {}
  }
}

또한 CLI(명령줄 인터페이스)를 통해 병합할 설정을 수행할 수도 있습니다. 자세한 내용은 다음 항목을 참조하십시오.

Tauri CLI를 사용하면 dev, android dev, ios dev, build, android build, ios build 또는 bundle 명령 중 하나를 실행할 때 Tauri 설정을 확장할 수 있습니다. 확장 설정은 JSON 문자열을 그대로 또는 JSON 파일 경로로 --config 인수로 제공할 수 있습니다. Tauri는 JSON Merge Patch (RFC 7396) 사양을 사용하여 제공된 설정 값을 원래의 최종 구성 객체와 병합합니다.

이 메커니즘을 사용하면 애플리케이션의 여러 버전을 정의하거나 애플리케이션 번들을 구성할 때 유연성을 높일 수 있습니다.

예를 들어, 정식 버전과 완전히 분리된 베타 버전 애플리케이션을 배포하려면 이 기능을 사용하여 다른 애플리케이션 이름과 식별자를 설정할 수 있습니다:

{
  "productName": "My App Beta",
  "identifier": "com.myorg.myappbeta"
}

이 분리된 베타 버전 앱을 배포하려면 빌드 시 다음 설정 파일을 만듭니다:

npm run tauri build -- --config src-tauri/tauri.beta.conf.json

yarn tauri build --config src-tauri/tauri.beta.conf.json

pnpm tauri build --config src-tauri/tauri.beta.conf.json

deno task tauri build --config src-tauri/tauri.beta.conf.json

bun tauri build --config src-tauri/tauri.beta.conf.json

cargo tauri build --config src-tauri/tauri.beta.conf.json

`Cargo.toml`

Cargo의 매니페스트 파일은 앱이 의존하는 Rust 크레이트, 앱에 대한 메타데이터 및 기타 Rust 관련 기능을 선언하는 데 사용됩니다. Rust를 사용하여 앱의 백엔드 개발을 할 생각이 없다면 이 파일을 많이 변경하지 않을 수 있지만, 이러한 파일이 있고 그것이 무엇을 하는지 아는 것이 중요합니다.

다음은 Tauri 프로젝트의 최소한의 Cargo.toml 파일 예입니다:

[package]
name = "app"
version = "0.1.0"
description = "A Tauri App"
authors = ["you"]
license = ""
repository = ""
default-run = "app"
edition = "2021"
rust-version = "1.57"

[build-dependencies]
tauri-build = { version = "2.0.0" }

[dependencies]
serde_json = "1.0"
serde = { version = "1.0", features = ["derive"] }
tauri = { version = "2.0.0", features = [ ] }

주의해야 할 가장 중요한 부분은 tauri-build와 tauri의 종속성입니다. 일반적으로 이 둘은 모두 Tauri CLI와 마찬가지로 최신 “최신 버그 수정판(마이너 버전)“이어야 하지만, 이는 엄격하게 필수는 아닙니다. 앱 실행 중에 문제가 발생하면 모든 Tauri 버전(tauri 및 tauri-cli)이 각각의 “최신 버그 수정판”(마이너 릴리스의 최신 버전)인지 확인해야 합니다.

Cargo의 버전 번호는 시맨틱 버전 관리 방식(참고)을 사용합니다. src-tauri 폴더 내에서 cargo update를 실행하면 모든 종속성에 대해 Semver 호환 최신 버전이 가져옵니다. 예를 들어, tauri-build의 버전으로 2.0.0을 지정하면 Cargo는 최신 Semver 호환 버전인 2.0.0.0을 감지하고 다운로드합니다. Tauri는 중대한 변경이 도입될 때 “메이저 버전 번호”를 업데이트합니다. 즉, 최신 마이너 버전과 패치 버전 업데이트에서는 자신의 코드가 [최신 기능으로] 손상될 걱정 없이 항상 안전하게 업그레이드할 수 있습니다.

특정 크레이트 버전을 사용하려면 종속성 버전 번호 앞에 =를 추가하여 지정한 버전을 사용할 수 있습니다:

tauri-build = { version = "=2.0.0" }

또한 tauri 종속성의 features=[] 부분에 주의해야 합니다. tauri dev와 tauri build를 실행하면 “Tauri 설정”에 따라 프로젝트에서 어떤 기능을 활성화해야 하는지 자동으로 판단합니다. tauri 기능 플래그에 대한 자세한 내용은 이 문서(영어)를 참조하십시오.

애플리케이션을 빌드하면 Cargo.lock 파일이 생성됩니다. 이 파일은 주로 개발 중 머신 간에 동일한 종속성이 사용되도록 하는 데 사용됩니다(Node.js의 yarn.lock, pnpm-lock.yaml 또는 package-lock.json과 유사합니다). 일관된 빌드를 얻기 위해 이 파일을 소스 리포지토리에 커밋하는 것이 좋습니다.

Cargo 매니페스트 파일에 대한 자세한 내용은 공식 문서(영어)를 참조하십시오.

`package.json`

이것은 Node.js에서 사용되는 패키지 파일입니다. Tauri 앱의 프론트엔드가 Node.js 기반 기술(npm, yarn, pnpm 등)을 사용하여 개발된 경우 이 파일은 프론트엔드 종속성과 스크립트를 구성하는 데 사용됩니다.

Tauri 프로젝트의 최소한의 package.json 파일은 다음 예와 같습니다:

{
  "scripts": {
    "dev": "command to start your app development mode",
    "build": "command to build your app frontend",
    "tauri": "tauri"
  },
  "dependencies": {
    "@tauri-apps/api": "^2.0.0.0",
    "@tauri-apps/cli": "^2.0.0.0"
  }
}

Tauri 애플리케이션에서 사용되는 프론트엔드의 시작 및 빌드에 사용되는 명령을 저장하는 데는 "scripts" 섹션을 사용하는 것이 일반적입니다. 위의 package.json 파일에서는 “dev 명령”과 “build 명령”을 지정하고 있습니다. “dev 명령”은 프론트엔드 프레임워크를 시작하기 위해 yarn dev 또는 npm run dev를 사용하여 실행되며, “build 명령”은 프로덕션 환경에서 Tauri에 의해 추가되는 프론트엔드 웹 자산을 빌드하기 위해 yarn build 또는 npm run build를 사용하여 실행됩니다. 이러한 스크립트를 사용하는 가장 편리한 방법은 “Tauri 설정”의 beforeDevCommand 및 beforeBuildCommand 후크를 통해 Tauri CLI에서 해당 스크립트를 후크하는 것입니다:

《번역 주》 후크 원문 hooks. 프로그램의 특정 지점(후크)에 사용자가 고유한 처리를 추가(후크)할 수 있도록 하는 메커니즘(Wikipedia)

{
  "build": {
    "beforeDevCommand": "yarn dev",
    "beforeBuildCommand": "yarn build"
  }
}

종속성 객체는 yarn, pnpm install 또는 npm install 중 하나를 실행할 때(이 경우 Tauri CLI 및 API에서) Node.js가 어떤 종속성을 다운로드할지 지정합니다.

package.json 파일 외에 yarn.lock, pnpm-lock.yaml 또는 package-lock.json 파일이 표시될 수 있습니다. 이러한 파일은 나중에 종속성을 다운로드할 때 개발 중에 사용한 것과 정확히 동일한 버전을 확실히 얻는 데 도움이 됩니다(Rust의 Cargo.lock과 유사합니다).

“package.json 파일 형식”에 대한 자세한 내용은 공식 문서(영어)를 참조하십시오.

【※ 이 한국어판은, 「Mar 29, 2025 영문판」에 근거하고 있습니다】

Support on Open Collective Sponsor on GitHub