Vite

이 안내서는 Vite를 프론트엔드 빌드 도구로 사용해 첫 Tauri 앱을 만드는 과정을 설명합니다.

정보

Before we continue, make sure you have completed the prerequisites to have a working development environment.

Tauri는 모든 프론트엔드 프레임워크와 Rust 코어를 함께 사용해 데스크톱 앱을 빌드하기 위한 프레임워크입니다. 각 앱은 두 개의 부분으로 구성됩니다:

1. 창을 만들고 그 창에 네이티브 기능을 내어주는 Rust 바이너리
2. 창 안에서 사용자 인터페이스를 만들기 위해 선택한 프론트엔드

따라가다보면, 먼저 프론트엔드를 스캐폴딩하고, Rust 프로젝트를 설정한 다음, 마지막으로 어떻게 둘 사이 통신이 이루어지는지 볼 수 있습니다.

create-tauri-app

The easiest way to scaffold a new project is the create-tauri-app utility. It provides opinionated templates for vanilla HTML/CSS/JavaScript and many frontend frameworks like React, Svelte and Yew.

Bash

sh <(curl https://create.tauri.app/sh)

PowerShell

irm https://create.tauri.app/ps | iex

Cargo

cargo install create-tauri-app --locked
cargo create-tauri-app

npm

npm create tauri-app@latest

Yarn

yarn create tauri-app

pnpm

pnpm create tauri-app

Bun

bunx create-tauri-app

Please note that you do not need to follow the rest of this guide if you use create-tauri-app, but we still recommend reading it to understand the setup.

다음은 빌드하게 될 내용의 미리보기 입니다:

프론트엔드 만들기

Vite는 프론트엔드 번들러 겸 빌드 도구입니다. 다시 말해, 개발 중 핫 모듈 리로딩 (HMR)뿐만 아니라 프로덕션 빌드에서 자동으로 소스 코드를 최적화된 HTML, CSS, JavaScript 코드로 변환하는 등 다양한 편의 기능을 제공한다는 뜻입니다. 빠른 속도, 쉬운 설정, 그리고 큰 플러그인 생태계가 있기 때문에 Vite를 추천합니다.

Vite comes with a scaffolding utility similar to create-tauri-app that can quickly set up a new project from many pre-defined templates. React, Svelte, Vue 등 수많은 프론트엔드 프레임워크 중 하나를 골라 사용할 수 있습니다. 이 안내서에서는 프론트 엔트 프레임워크 without vanilla-ts 템플릿을 선택하여 간단한 프로젝트를 만들어볼 것입니다.

npm

npm create vite@latest

Yarn

yarn create vite

pnpm

pnpm create vite

1. Project name
   이것은 당신의 JavaScript 프로젝트의 이름이 될 것입니다. 유틸리티가 만드는 폴더의 이름이 되지만 그 외 다른 이름에는 영향이 없습니다. 원하는 이름이라면 무엇이든 적을 수 있습니다.

2. Select a framework
   추후에 프론트엔드 프레임워크를 사용할 계획이 있다면 여기에서 프레임워크를 선택할 수 있습니다. 이 안내서에서는, vanilla를 선택했다고 가정합니다.

3. Select a variant
   Vite는 모든 템플릿에서 TypeScript나 기본 JavaScript을 선택할 수 있도록 하고 제공하는 데 이 부분을 여기서 선택할 수 있습니다. 더 안전하고, 유지보수하기 쉬운 코드를 빠르고 효율적으로 작성하게 돕는 TypeScript를 강하게 권장합니다. 이 안내서에서는, vanilla-ts를 선택했다고 가정합니다.

vite 명령어로 프론트엔드를 시작할 때, Vite는 프로젝트 루트 디렉터리 안에서 vite.config.ts라는 이름의 설정 파일을 찾아봅니다. Tauri와 궁합이 잘 맞도록 이 파일을 건드려봅시다. 만약 위 스캐폴딩 과정에서 파일이 만들어지지 않았다면 (예를 들어, 그냥 바닐라 JavaScript를 고르셨다거나 해서) 프로젝트 루트 디렉터리에 vite.config.ts 파일을 만들어야 할 수 있습니다.

파일 내용을 아래와 같이 고쳐봅시다:

vite.config.ts

import { defineConfig } from 'vite'

export default defineConfig({
  // prevent vite from obscuring rust errors
  clearScreen: false,
  // Tauri expects a fixed port, fail if that port is not available
  server: {
    strictPort: true,
  },
  // to access the Tauri environment variables set by the CLI with information about the current target
  envPrefix: ['VITE_', 'TAURI_PLATFORM', 'TAURI_ARCH', 'TAURI_FAMILY', 'TAURI_PLATFORM_VERSION', 'TAURI_PLATFORM_TYPE', 'TAURI_DEBUG'],
  build: {
    // Tauri uses Chromium on Windows and WebKit on macOS and Linux
    target: process.env.TAURI_PLATFORM == 'windows' ? 'chrome105' : 'safari13',
    // don't minify for debug builds
    minify: !process.env.TAURI_DEBUG ? 'esbuild' : false,
    // 디버그 빌드에서 소스맵을 제공합니다.
    sourcemap: !!process.env.TAURI_DEBUG,
  },
})

정보

만약 바닐라 JavaScript를 사용하는 게 아니라면 파일에 있던 프레임워크 전용 플러그인 코드를 남겨둬야 함에 주의하세요.

Rust 프로젝트 생성하기

모든 Tauri 앱의 중심에는 tauri라는 Rust crate를 통해 창, 웹뷰, 운영 체제의 호출을 관리하는 Rust 바이너리가 있습니다. 프로젝트는 Rust의 공식 패키지 관리자이자 범용 빌드 도구인 Cargo로 관리합니다.

Tauri CLI가 내부적으로 Cargo를 사용해, 직접 만져야 할 일은 적습니다. Cargo에는 CLI로는 접근할 수 없지만 유용한 기능이 많습니다. 예를 들어, 테스트나 린트, 포매팅 등이 있습니다. Cargo 공식 문서를 참조하시면 더 많이 알아보실 수 있습니다.

Tauri CLI 설치

Tauri CLI 미설치시 아래 중 하나의 명령어로 설치가능합니다. 무엇을 써야 하는지 잘 모르시겠나요? 자주 물어보는 질문 항목을 살펴보세요.

npm

npm install --save-dev @tauri-apps/cli

For npm to detect Tauri correctly you need to add it to the "scripts" section in your package.json file:

package.json

"scripts": {
  "tauri": "tauri"
}

Yarn

yarn add -D @tauri-apps/cli

pnpm

pnpm add -D @tauri-apps/cli

Bun

bun add -D @tauri-apps/cli

Cargo

cargo install tauri-cli

Tauri와의 사용을 위해 미리 설정된 작은 Rust 프로젝트를 만드시려면, 터미널을 열어 다음 명령어를 입력하세요:

npm

npm run tauri init

Yarn

yarn tauri init

pnpm

pnpm tauri init

Cargo

cargo tauri init

일련의 질문을 통해 프로젝트 구성을 진행해나갈 것입니다:

1. What is your app name?
   최종 번들의 이름이자, 운영 체제가 부를 앱의 이름입니다. 원하는 이름이라면 무엇이든 적을 수 있습니다.


2. What should the window title be?
   기본 메인 창의 제목입니다. 원하는 제목을 적으시면 됩니다.


3. Where are your web assets (HTML/CSS/JS) located relative to the <current dir>/src-tauri/tauri.conf.json file that will be created?
   Tauri가 프로덕션으로 빌드할 때 프론트엔드 애셋을 불러올 경로입니다.
   Use ../dist for this value.


4. What is the URL of your dev server?
   개발 과정에서 Tauri가 불러올 URL이나 파일 경로입니다.
   Use http://localhost:5173 for this value.


5. What is your frontend dev command?
   프론트엔드 개발 서버 실행에 쓰이는 명령어입니다.
   Use npm run dev (make sure to adapt this to use the package manager of your choice).


6. What is your frontend build command?
   프론트엔드 빌드에 쓰이는 명령어입니다.
   Use npm run build (make sure to adapt this to use the package manager of your choice).

정보

만약 Rust에 익숙하시다면, tauri init이 cargo init과 매우 비슷하게 동작한다는 것을 눈치채셨을 것입니다. 만약 손수 설정하는 것을 선호하신다면 그냥 cargo init을 수행하고, 필요한 Tauri 의존성을 받으셔도 좋습니다.

tauri init 명령어는 src-tauri 폴더를 만듭니다. 그 폴더에 코어와 관련된 파일을 두는 것이 Tauri 앱의 규칙입니다. 이 폴더의 내용물을 빠르게 살펴봅시다:

• Cargo.toml
  Cargo의 매니페스트 파일입니다. 앱에서 어떤 Rust crate에 의존하는지 정의하고, 앱에 대한 부가 정보를 기록하고, 그 외 다양한 일을 할 수 있습니다. 완전한 참고 자료로써 Cargo 매니페스트 형식 문서를 살펴보실 수 있습니다.

• tauri.conf.json
  이름부터 허용된 API 목록까지, 이 파일을 통해 Tauri 앱의 다양한 부분을 맞춤 설정합니다. Tauri API 설정 문서에서 지원하는 옵션의 전체 목록과 각 옵션의 자세한 설명을 확인하실 수 있습니다.

• src/main.rs
  이 부분은 Rust 프로그램의 시작점이자, Tauri를 구동하는 위치입니다. 두 부분으로 나누어 볼 수 있습니다:

  src/main.rs

   #![cfg_attr(not(debug_assertions), windows_subsystem = "windows")]
  
  fn main() {
  tauri::Builder::default()
     .run(tauri::generate_context!())
     .expect("error while running tauri application");
  }

  The line beginning with the cfg! 매크로로 시작합니다: 일반적으로 번들 앱을 실행할 때, Windows에서 나오는 명령 프롬프트 창을 비활성화합니다. 만약 Windows를 사용 중이시라면, 해당 줄을 주석 처리한 후 어떤 일이 일어나는지 살펴보세요.

  main 함수는 진입점으로 프로그램을 실행할 때 가장 먼저 불리는 함수입니다.

• icons
  앱에 멋진 아이콘을 추가할 기회가 바로 여기에 있습니다! 빠른 시작을 위해, 기본 아이콘 묶음을 미리 포함시켜 두었습니다. 앱을 공개하기 전, 기본 아이콘을 교체하셔야 합니다. Tauri 아이콘 기능 안내서에서 다양한 아이콘 형식에 대해 알아보실 수 있습니다.

이제 프론트엔드를 스캐폴드했고, Rust 프로젝트도 초기화했으니, 생성된 tauri.conf.json 파일엔 이런 내용이 있을 것입니다:

src-tauri/tauri.conf.json

{
  "build": {
    // `tauri build`를 돌릴 때 이 명령어가 실행될 것입니다.
    "beforeBuildCommand": "npm run build",
    // `tauri dev`를 돌릴 때 이 명령어가 실행될 것입니다.
    "beforeDevCommand": "npm run dev",
    "devPath": "http://localhost:5173",
    "distDir": "../dist"
  },

이걸로 끝입니다! 이제 터미널에서 다음 명령어를 실행해 앱의 개발 빌드를 시작할 수 있습니다.

npm

npm run tauri dev

Yarn

yarn tauri dev

pnpm

pnpm tauri dev

bun

bunx tauri dev

Cargo

cargo tauri dev

명령 호출

Tauri는 네이티브 기능과 함께 프론트엔드를 향상시킬 수 있습니다. 명령이라고 불리는 이 기능은, 기본적으로 프론트엔드 JavaScript에서 호출할 수 있는 Rust 함수입니다. 이를 통해 성능이 뛰어난 Rust 코드로 오래 걸리는 작업이나 OS 기능 호출 등을 처리할 수 있습니다.

간단한 예제를 만들어봅시다:

src-tauri/src/main.rs

#[tauri::command]
fn greet(name: &str) -> String {
   format!("Hello, {}!", name)
}

명령은 일반적인 Rust 함수와 같지만, JavaScript 맥락과 통신하게 해주는 #[tauri::command 속성 매크로가 붙어 있습니다.

마지막으로, Tauri가 적절히 호출을 전달하도록 새로 만든 명령을 알려줘야 합니다. 아래와 같이, invoke_handler() 함수와 generate_handler![] 매크로를 조합해 줍니다.

src-tauri/src/main.rs

fn main() {
  tauri::Builder::default()
    .invoke_handler(tauri::generate_handler![greet])
    .run(tauri::generate_context!())
    .expect("error while running tauri application");
}

이제 프론트엔드에서 명령을 호출할 준비가 되었습니다!

새로 만든 명령을 호출하기 위해서 JavaScript 라이브러리 @tauri-apps/api를 사용할 것입니다. 이 라이브러리는 편리한 JavaScript 추상화를 통해 창, 파일시스템 등 핵심 기능으로 가는 진입로를 제공합니다. 좋아하는 JavaScript 패키지 관리자로 설치할 수 있습니다.

npm

npm install @tauri-apps/api

Yarn

yarn add @tauri-apps/api

pnpm

pnpm add @tauri-apps/api

Bun

bun add @tauri-apps/api

라이브러리가 설치된 후, 명령을 호출하도록 main.ts 파일을 수정할 수 있습니다.

src/main.ts

import { invoke } from '@tauri-apps/api'

// 명령을 호출해볼 수 있습니다!
// 앱 배경을 우클릭하고 개발자 도구를 엽니다.
// "Hello, World!"가 콘솔에 출력되는 걸 볼 수 있습니다!
invoke('greet', { name: 'World' })
  // `invoke`는 Promise를 반환합니다.
  .then((response) => console.log(response))

팁

만약 Rust와 JavaScript 사이의 통신에 대해 더 알아보고 싶으시다면 Tauri 프로세스 간 통신 안내서를 읽어보세요.