integrating-tauri-js-frontends

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Tauri v2 JavaScript Frontend Integration

Tauri v2 JavaScript前端集成

This skill covers integrating JavaScript frontend frameworks with Tauri v2 for desktop application development.

本内容涵盖如何将JavaScript前端框架与Tauri v2集成以开发桌面应用。

Core Architecture

核心架构

Tauri functions as a static web host, serving HTML, CSS, JavaScript, and WASM files through a native webview. The framework is frontend-agnostic but requires specific configurations for optimal integration.

Tauri 作为静态Web主机，通过原生Webview提供HTML、CSS、JavaScript和WASM文件。该框架与前端无关，但需要特定配置以实现最佳集成。

Supported Application Types

支持的应用类型

Static Site Generation (SSG)
Single-Page Applications (SPA)
Multi-Page Applications (MPA)

静态站点生成（SSG）
单页应用（SPA）
多页应用（MPA）

Not Supported

不支持的类型

Server-side rendering (SSR) in its native form. All frameworks must be configured for static output.

原生形式的服务器端渲染（SSR）。所有框架必须配置为静态输出。

General Requirements

通用要求

Key Principles

核心原则

Static Output Required: Tauri cannot run a Node.js server - all content must be pre-built static files
Client-Server Architecture: Implement proper client-server relationships between app and APIs (no hybrid SSR solutions)
Mobile Development: Requires a development server hosting the frontend on your internal IP

必须静态输出：Tauri无法运行Node.js服务器 - 所有内容必须是预构建的静态文件
客户端-服务器架构：在应用与API之间实现正确的客户端-服务器关系（不支持混合SSR解决方案）
移动开发：需要开发服务器在内部IP上托管前端

Common tauri.conf.json Structure

通用tauri.conf.json结构

json

{
  "build": {
    "beforeDevCommand": "<package-manager> dev",
    "beforeBuildCommand": "<package-manager> build",
    "devUrl": "http://localhost:<port>",
    "frontendDist": "../<output-dir>"
  }
}

Replace

<package-manager>

with

npm run

yarn

pnpm

, or

deno task

json

{
  "build": {
    "beforeDevCommand": "<package-manager> dev",
    "beforeBuildCommand": "<package-manager> build",
    "devUrl": "http://localhost:<port>",
    "frontendDist": "../<output-dir>"
  }
}

将

<package-manager>

替换为

npm run

、

yarn

、

pnpm

或

deno task

。

Framework Configurations

框架配置

Vite (React, Vue, Svelte, Solid)

Vite（React、Vue、Svelte、Solid）

Vite is the recommended choice for SPA frameworks due to its fast development experience and simple configuration.

Vite是SPA框架的推荐选择，因其开发体验快速且配置简单。

package.json

json

{
  "scripts": {
    "dev": "vite",
    "build": "tsc && vite build",
    "preview": "vite preview",
    "tauri": "tauri"
  }
}

json

{
  "scripts": {
    "dev": "vite",
    "build": "tsc && vite build",
    "preview": "vite preview",
    "tauri": "tauri"
  }
}

vite.config.ts

typescript

import { defineConfig } from 'vite';

export default defineConfig({
  clearScreen: false,
  server: {
    port: 5173,
    strictPort: true,
    host: process.env.TAURI_DEV_HOST || 'localhost',
    watch: {
      ignored: ['**/src-tauri/**'],
    },
  },
  envPrefix: ['VITE_', 'TAURI_ENV_*'],
  build: {
    target: process.env.TAURI_ENV_PLATFORM === 'windows' ? 'chrome105' : 'safari13',
    minify: process.env.TAURI_ENV_DEBUG ? false : 'esbuild',
    sourcemap: !!process.env.TAURI_ENV_DEBUG,
  },
});

typescript

import { defineConfig } from 'vite';

export default defineConfig({
  clearScreen: false,
  server: {
    port: 5173,
    strictPort: true,
    host: process.env.TAURI_DEV_HOST || 'localhost',
    watch: {
      ignored: ['**/src-tauri/**'],
    },
  },
  envPrefix: ['VITE_', 'TAURI_ENV_*'],
  build: {
    target: process.env.TAURI_ENV_PLATFORM === 'windows' ? 'chrome105' : 'safari13',
    minify: process.env.TAURI_ENV_DEBUG ? false : 'esbuild',
    sourcemap: !!process.env.TAURI_ENV_DEBUG,
  },
});

tauri.conf.json

json

{
  "build": {
    "beforeDevCommand": "npm run dev",
    "beforeBuildCommand": "npm run build",
    "devUrl": "http://localhost:5173",
    "frontendDist": "../dist"
  }
}

json

{
  "build": {
    "beforeDevCommand": "npm run dev",
    "beforeBuildCommand": "npm run build",
    "devUrl": "http://localhost:5173",
    "frontendDist": "../dist"
  }
}

Next.js

Next.js requires static export mode since Tauri cannot run Node.js servers.

Next.js需要使用静态导出模式，因为Tauri无法运行Node.js服务器。

Critical Requirements

关键要求

Must use
```
output: 'export'
```
in next.config
Images must be unoptimized for static export
Asset prefix required for development server

必须在next.config中设置
```
output: 'export'
```
图片必须禁用优化以支持静态导出
开发服务器需要配置资源前缀

next.config.mjs

javascript

const isProd = process.env.NODE_ENV === 'production';
const internalHost = process.env.TAURI_DEV_HOST || 'localhost';

/** @type {import('next').NextConfig} */
const nextConfig = {
  output: 'export',
  images: {
    unoptimized: true,
  },
  assetPrefix: isProd ? undefined : `http://${internalHost}:3000`,
};

export default nextConfig;

javascript

const isProd = process.env.NODE_ENV === 'production';
const internalHost = process.env.TAURI_DEV_HOST || 'localhost';

/** @type {import('next').NextConfig} */
const nextConfig = {
  output: 'export',
  images: {
    unoptimized: true,
  },
  assetPrefix: isProd ? undefined : `http://${internalHost}:3000`,
};

export default nextConfig;

package.json

json

{
  "scripts": {
    "dev": "next dev",
    "build": "next build",
    "start": "next start",
    "tauri": "tauri"
  }
}

json

{
  "scripts": {
    "dev": "next dev",
    "build": "next build",
    "start": "next start",
    "tauri": "tauri"
  }
}

tauri.conf.json

json

{
  "build": {
    "beforeDevCommand": "npm run dev",
    "beforeBuildCommand": "npm run build",
    "devUrl": "http://localhost:3000",
    "frontendDist": "../out"
  }
}

json

{
  "build": {
    "beforeDevCommand": "npm run dev",
    "beforeBuildCommand": "npm run build",
    "devUrl": "http://localhost:3000",
    "frontendDist": "../out"
  }
}

SSG Considerations for Next.js

Next.js的SSG注意事项

The
```
out
```
directory contains static exports
Dynamic routes require
```
generateStaticParams()
```
API routes are not supported - use Tauri commands instead
```
next/image
```
optimization is disabled; use standard
```
<img>
```
or configure unoptimized

```
out
```
目录包含静态导出文件
动态路由需要使用
```
generateStaticParams()
```
不支持API路由 - 请使用Tauri命令替代
```
next/image
```
优化已禁用；请使用标准
```
<img>
```
标签或配置为未优化模式

Nuxt

Nuxt must run in SSG mode with

ssr: false

for Tauri compatibility.

Nuxt必须运行在SSG模式并设置

ssr: false

以兼容Tauri。

nuxt.config.ts

typescript

export default defineNuxtConfig({
  ssr: false,
  telemetry: false,
  devServer: {
    host: '0.0.0.0', // Required for iOS device compatibility
  },
  vite: {
    clearScreen: false,
    envPrefix: ['VITE_', 'TAURI_'],
    server: {
      strictPort: true,
      watch: {
        ignored: ['**/src-tauri/**'],
      },
    },
  },
});

typescript

export default defineNuxtConfig({
  ssr: false,
  telemetry: false,
  devServer: {
    host: '0.0.0.0', // 兼容iOS设备所需
  },
  vite: {
    clearScreen: false,
    envPrefix: ['VITE_', 'TAURI_'],
    server: {
      strictPort: true,
      watch: {
        ignored: ['**/src-tauri/**'],
      },
    },
  },
});

package.json

json

{
  "scripts": {
    "dev": "nuxt dev",
    "build": "nuxt build",
    "generate": "nuxt generate",
    "tauri": "tauri"
  }
}

json

{
  "scripts": {
    "dev": "nuxt dev",
    "build": "nuxt build",
    "generate": "nuxt generate",
    "tauri": "tauri"
  }
}

tauri.conf.json

json

{
  "build": {
    "beforeDevCommand": "npm run dev",
    "beforeBuildCommand": "npm run generate",
    "devUrl": "http://localhost:3000",
    "frontendDist": "../dist"
  }
}

json

{
  "build": {
    "beforeDevCommand": "npm run dev",
    "beforeBuildCommand": "npm run generate",
    "devUrl": "http://localhost:3000",
    "frontendDist": "../dist"
  }
}

SSG Considerations for Nuxt

Nuxt的SSG注意事项

Use
```
nuxt generate
```
for production builds (creates static files)
Server routes (
```
/server/api
```
) are not available - use Tauri commands
Nitro server functionality is disabled in SSG mode

生产构建请使用
```
nuxt generate
```
（生成静态文件）
服务器路由（
```
/server/api
```
）不可用 - 请使用Tauri命令替代
SSG模式下Nitro服务器功能已禁用

SvelteKit

SvelteKit requires the static adapter and SSR must be disabled.

SvelteKit需要使用静态适配器并禁用SSR。

Installation

安装

bash

npm install --save-dev @sveltejs/adapter-static

bash

npm install --save-dev @sveltejs/adapter-static

svelte.config.js

javascript

import adapter from '@sveltejs/adapter-static';
import { vitePreprocess } from '@sveltejs/vite-plugin-svelte';

/** @type {import('@sveltejs/kit').Config} */
const config = {
  preprocess: vitePreprocess(),
  kit: {
    adapter: adapter({
      fallback: 'index.html',
    }),
  },
};

export default config;

javascript

import adapter from '@sveltejs/adapter-static';
import { vitePreprocess } from '@sveltejs/vite-plugin-svelte';

/** @type {import('@sveltejs/kit').Config} */
const config = {
  preprocess: vitePreprocess(),
  kit: {
    adapter: adapter({
      fallback: 'index.html',
    }),
  },
};

export default config;

src/routes/+layout.ts

typescript

export const ssr = false;
export const prerender = true;

typescript

export const ssr = false;
export const prerender = true;

vite.config.ts

typescript

import { sveltekit } from '@sveltejs/kit/vite';
import { defineConfig } from 'vite';

export default defineConfig({
  plugins: [sveltekit()],
  clearScreen: false,
  server: {
    port: 5173,
    strictPort: true,
    host: process.env.TAURI_DEV_HOST || 'localhost',
    watch: {
      ignored: ['**/src-tauri/**'],
    },
  },
  envPrefix: ['VITE_', 'TAURI_ENV_*'],
});

typescript

import { sveltekit } from '@sveltejs/kit/vite';
import { defineConfig } from 'vite';

export default defineConfig({
  plugins: [sveltekit()],
  clearScreen: false,
  server: {
    port: 5173,
    strictPort: true,
    host: process.env.TAURI_DEV_HOST || 'localhost',
    watch: {
      ignored: ['**/src-tauri/**'],
    },
  },
  envPrefix: ['VITE_', 'TAURI_ENV_*'],
});

tauri.conf.json

json

{
  "build": {
    "beforeDevCommand": "npm run dev",
    "beforeBuildCommand": "npm run build",
    "devUrl": "http://localhost:5173",
    "frontendDist": "../build"
  }
}

json

{
  "build": {
    "beforeDevCommand": "npm run dev",
    "beforeBuildCommand": "npm run build",
    "devUrl": "http://localhost:5173",
    "frontendDist": "../build"
  }
}

SSG Considerations for SvelteKit

SvelteKit的SSG注意事项

SPA mode (without prerendering) is recommended for full Tauri API access in load functions
With prerendering, load functions execute at build time without Tauri API access
The
```
fallback: 'index.html'
```
enables SPA routing
Output directory is
```
build/
```
by default

推荐使用SPA模式（不预渲染）以在加载函数中完全访问Tauri API
预渲染模式下，加载函数在构建时执行，无法访问Tauri API
```
fallback: 'index.html'
```
启用SPA路由
默认输出目录为
```
build/
```

Qwik

Qwik requires the static adapter for Tauri compatibility.

Qwik需要使用静态适配器以兼容Tauri。

Setup

设置

bash

undefined

bash

undefined

Create project

创建项目

npm create qwik@latest cd <project>

Add static adapter

添加静态适配器

npm run qwik add static

Add Tauri CLI

添加Tauri CLI

npm install -D @tauri-apps/cli@latest

Initialize Tauri

初始化Tauri

npm run tauri init

undefined

npm run tauri init

undefined

package.json

json

{
  "scripts": {
    "dev": "vite",
    "build": "qwik build",
    "tauri": "tauri"
  }
}

json

{
  "scripts": {
    "dev": "vite",
    "build": "qwik build",
    "tauri": "tauri"
  }
}

tauri.conf.json

json

{
  "build": {
    "beforeDevCommand": "npm run dev",
    "beforeBuildCommand": "npm run build",
    "devUrl": "http://localhost:5173",
    "frontendDist": "../dist"
  }
}

json

{
  "build": {
    "beforeDevCommand": "npm run dev",
    "beforeBuildCommand": "npm run build",
    "devUrl": "http://localhost:5173",
    "frontendDist": "../dist"
  }
}

SSG Considerations for Qwik

Qwik的SSG注意事项

The static adapter is mandatory
Qwik City server functions are not available
Use Tauri commands for backend functionality

必须使用静态适配器
Qwik City服务器函数不可用
请使用Tauri命令实现后端功能

Quick Reference Table

快速参考表

Framework	Output Dir	Dev Port	Build Command	Key Config
Vite	`dist`	5173	`vite build`	Standard Vite config
Next.js	`out`	3000	`next build`	`output: 'export'`
Nuxt	`dist`	3000	`nuxt generate`	`ssr: false`
SvelteKit	`build`	5173	`vite build`	`adapter-static`
Qwik	`dist`	5173	`qwik build`	Static adapter

框架	输出目录	开发端口	构建命令	关键配置
Vite	`dist`	5173	`vite build`	标准Vite配置
Next.js	`out`	3000	`next build`	`output: 'export'`
Nuxt	`dist`	3000	`nuxt generate`	`ssr: false`
SvelteKit	`build`	5173	`vite build`	`adapter-static`
Qwik	`dist`	5173	`qwik build`	静态适配器

Common Issues and Solutions

常见问题与解决方案

Issue: Assets Not Loading in Development

问题：开发环境下资源无法加载

Cause: Asset prefix not configured for development server.

Solution: Configure asset prefix to point to dev server (see Next.js config example).

原因：未为开发服务器配置资源前缀。

解决方案：配置资源前缀指向开发服务器（参见Next.js配置示例）。

Issue: Tauri APIs Unavailable

问题：Tauri API不可用

Cause: Code executing during SSG build time instead of runtime.

Solution:

Disable prerendering for pages using Tauri APIs
Use dynamic imports with
```
ssr: false
```
Check for
```
window.__TAURI__
```
before API calls

原因：代码在SSG构建时执行而非运行时执行。

解决方案：

对使用Tauri API的页面禁用预渲染
使用
```
ssr: false
```
进行动态导入
在调用API前检查
```
window.__TAURI__
```
是否存在

Issue: Hot Reload Not Working

问题：热重载不工作

Cause: File watcher including

src-tauri

directory.

Solution: Add

**/src-tauri/**

to watch ignore list in Vite config.

原因：文件监视器包含

src-tauri

目录。

解决方案：在Vite配置中将

**/src-tauri/**

添加到监视器忽略列表。

Issue: Mobile Development Fails

问题：移动开发失败

Cause: Dev server not accessible on network.

Solution: Set host to

0.0.0.0

or use

TAURI_DEV_HOST

environment variable.

原因：开发服务器无法在网络上访问。

解决方案：将主机设置为

0.0.0.0

或使用

TAURI_DEV_HOST

环境变量。

Issue: Build Fails with SSR Errors

问题：构建因SSR错误失败

Cause: Framework attempting server-side rendering.

Solution: Ensure SSR is disabled:

Next.js:
```
output: 'export'
```
Nuxt:
```
ssr: false
```
SvelteKit:
```
export const ssr = false
```
in layout
Qwik: Use static adapter

原因：框架尝试进行服务器端渲染。

解决方案：确保已禁用SSR：

Next.js:
```
output: 'export'
```
Nuxt:
```
ssr: false
```
SvelteKit: 在布局中设置
```
export const ssr = false
```
Qwik: 使用静态适配器

Environment Variables

环境变量

Tauri-Provided Variables

Tauri提供的变量

Variable	Description
`TAURI_DEV_HOST`	Host IP for mobile development
`TAURI_ENV_PLATFORM`	Target platform (windows, macos, linux, ios, android)
`TAURI_ENV_DEBUG`	Set during debug builds

变量名	描述
`TAURI_DEV_HOST`	移动开发使用的主机IP
`TAURI_ENV_PLATFORM`	目标平台（windows、macos、linux、ios、android）
`TAURI_ENV_DEBUG`	调试构建时设置

Recommended envPrefix

Build Targets

构建目标

Configure build targets based on platform webview capabilities:

typescript

build: {
  target: process.env.TAURI_ENV_PLATFORM === 'windows'
    ? 'chrome105'  // WebView2 on Windows
    : 'safari13',  // WebKit on macOS/Linux
}

根据平台Webview能力配置构建目标：

typescript

build: {
  target: process.env.TAURI_ENV_PLATFORM === 'windows'
    ? 'chrome105'  // Windows上的WebView2
    : 'safari13',  // macOS/Linux上的WebKit
}

Mobile Development

移动开发

For iOS and Android development, the dev server must be accessible on the network:

typescript

server: {
  host: process.env.TAURI_DEV_HOST || '0.0.0.0',
  strictPort: true,
}

Run with the appropriate mobile command:

bash

npm run tauri ios dev
npm run tauri android dev

对于iOS和Android开发，开发服务器必须在网络上可访问：

typescript

server: {
  host: process.env.TAURI_DEV_HOST || '0.0.0.0',
  strictPort: true,
}

运行相应的移动命令：

bash

npm run tauri ios dev
npm run tauri android dev