Tauri v2 Desktop Shell

Desktop applications need a native shell to wrap web-based user interfaces.

architectureenforced by 1 rule

Context

Desktop applications need a native shell to wrap web-based user interfaces. Traditionally, Electron has been the dominant choice, but it bundles an entire Chromium browser and Node.js runtime, resulting in large application sizes (200MB+) and high memory usage. Tauri v2 takes a fundamentally different approach by using Rust for the native shell and leveraging the operating system's built-in webview (WebView2 on Windows, WebKit on macOS, WebKitGTK on Linux). This results in dramatically smaller application sizes (~10MB), lower memory consumption, and better security through Rust's memory safety guarantees.

Tauri v2 provides a secure IPC bridge between the Rust backend and JavaScript frontend, supports Windows, macOS, and Linux from a single codebase, and offers a rich plugin ecosystem for native capabilities like file system access, notifications, and system tray management.

Decision

Tauri v2 is the desktop shell for all desktop applications. The Rust shell manages the application lifecycle, spawns the backend as a sidecar process, and loads the frontend via a webview pointed at localhost.

The desktop package lives at packages/desktop/ with a src-tauri/ directory containing the Rust code and tauri.conf.json configuration.
The Tauri configuration file (tauri.conf.json) defines window properties, security policies, bundle settings, and sidecar configurations.
The frontend is loaded via the system webview, connecting to a local development server or bundled assets.
Native functionality is accessed through Tauri's IPC system and plugin architecture, not through direct system calls from JavaScript.
@tauri-apps/cli must be present as a workspace dev dependency for build tooling.
@tauri-apps/api must be present as a dependency for frontend-to-Rust IPC communication.
No other desktop shell frameworks (Electron, NW.js, Neutralinojs) are permitted.

Do's and Don'ts

Do

Place all Tauri-related Rust code and configuration in packages/desktop/src-tauri/.
Use tauri.conf.json for all Tauri configuration (window settings, security, bundling).
Use Tauri's IPC system (invoke, emit, listen) for communication between Rust and JavaScript.
Use Tauri plugins for native OS capabilities (file system, notifications, clipboard, etc.).
Keep the Rust shell thin, delegating business logic to the TypeScript backend sidecar.
Test on all target platforms (Windows, macOS, Linux) before releases.

Don't

Use Electron, NW.js, Neutralinojs, or any other desktop shell framework.
Access native OS APIs directly from JavaScript; always go through Tauri's IPC bridge.
Bundle a Chromium browser or Node.js runtime with the application.
Put business logic in the Rust shell; it should only handle app lifecycle and native integrations.
Modify tauri.conf.json security settings (CSP, capabilities) without review.

Consequences

Positive

Dramatically smaller application size (~10MB vs 200MB+ for Electron).
Lower memory and CPU usage by leveraging the system's native webview.
Rust's memory safety guarantees reduce the risk of security vulnerabilities in the native shell.
Cross-platform support for Windows, macOS, and Linux from a single codebase.
Secure IPC architecture with fine-grained permission control.
Active community and growing plugin ecosystem.

Negative

Requires Rust knowledge for extending native shell functionality.
Webview rendering may differ slightly across operating systems due to using system webviews.
Smaller ecosystem compared to Electron's mature third-party library collection.
Debugging across the Rust/JavaScript boundary can be more complex than a pure JavaScript stack.

Enforcement rules

adrs/ARCH-010-tauri-desktop-shell.rules.ts

/// <reference path="../rules.d.ts" />

export default {
  rules: {
    "tauri-config-exists": {
      description: "Tauri configuration file must exist in packages/desktop/src-tauri/",
      async check(ctx) {
        const configFiles = [
          ...(await ctx.glob("packages/desktop/src-tauri/tauri.conf.json")),
          ...(await ctx.glob("packages/desktop/tauri.conf.json")),
        ];

        if (configFiles.length === 0) {
          ctx.report.warning({
            message:
              "No tauri.conf.json found in packages/desktop/src-tauri/ or packages/desktop/ — Tauri desktop shell may not be configured",
            file: "packages/desktop/src-tauri/tauri.conf.json",
            fix: "Create tauri.conf.json in packages/desktop/src-tauri/ with Tauri v2 configuration",
          });
        }
      },
    },
    "tauri-dependencies": {
      description: "@tauri-apps/cli and @tauri-apps/api must be present in workspace dependencies",
      async check(ctx) {
        const pkgFiles = [
          ...(await ctx.glob("package.json")),
          ...(await ctx.glob("packages/*/package.json")),
          ...(await ctx.glob("packages/*/*/package.json")),
        ];

        const results = await Promise.all(
          pkgFiles.map(async (pkgFile) => {
            let pkg: Record<string, unknown>;
            try {
              pkg = (await ctx.readJSON(pkgFile)) as Record<string, unknown>;
            } catch {
              return { hasCliDep: false, hasApiDep: false };
            }

            const allDeps = {
              ...((pkg.dependencies ?? {}) as Record<string, string>),
              ...((pkg.devDependencies ?? {}) as Record<string, string>),
            };

            return {
              hasCliDep: !!allDeps["@tauri-apps/cli"],
              hasApiDep: !!allDeps["@tauri-apps/api"],
            };
          }),
        );
        const hasCliDep = results.some((r) => r.hasCliDep);
        const hasApiDep = results.some((r) => r.hasApiDep);

        if (!hasCliDep) {
          ctx.report.warning({
            message:
              "@tauri-apps/cli not found in any workspace package — required for Tauri build tooling",
            file: "package.json",
            fix: "Add @tauri-apps/cli as a devDependency in the root or desktop package",
          });
        }

        if (!hasApiDep) {
          ctx.report.warning({
            message:
              "@tauri-apps/api not found in any workspace package — required for frontend-to-Rust IPC",
            file: "package.json",
            fix: "Add @tauri-apps/api as a dependency in the frontend or desktop package",
          });
        }
      },
    },
    "no-electron": {
      description: "No Electron or alternative desktop shell frameworks are permitted",
      async check(ctx) {
        const banned = ["electron", "electron-builder", "nw", "neutralino"];
        const pkgFiles = await ctx.glob("**/package.json");

        await Promise.all(
          pkgFiles.map(async (pkgFile) => {
            let pkg: Record<string, unknown>;
            try {
              pkg = (await ctx.readJSON(pkgFile)) as Record<string, unknown>;
            } catch {
              return;
            }

            const allDeps = {
              ...((pkg.dependencies ?? {}) as Record<string, string>),
              ...((pkg.devDependencies ?? {}) as Record<string, string>),
            };

            for (const framework of banned) {
              if (allDeps[framework]) {
                ctx.report.violation({
                  message: `${pkgFile}: contains banned desktop shell dependency "${framework}"`,
                  file: pkgFile,
                  fix: `Remove "${framework}" — Tauri v2 is the only permitted desktop shell`,
                });
              }
            }
          }),
        );
      },
    },
  },
} satisfies RuleSet;