Window Creation and Lifecycle

Patterns for splash screens, dev server polling, macOS-specific tweaks, and window destroy cleanup.

Why create windows in Rust?

Tauri v2 lets you define windows in tauri.conf.json, but creating them programmatically in Rust gives you control over:

• Splash screen timing
• Dev server readiness polling
• Conditional window creation
• Multiple window instances
• Platform-specific configuration

Splash screen pattern

Show a lightweight splash window while the app initializes, then replace it with the main window:

.setup(|app| {
    // 1. Create splash window (non-fatal if it fails)
    if let Err(e) = native::window::create_splash_window(app.handle()) {
        eprintln!("Failed to create splash window: {e}");
    }

    // 2. Do initialization work
    let project_root = resolve_project_root();
    let app_state = Arc::new(AppState::new(project_root));
    app.manage(app_state);

    // Start file watchers, etc.

    // 3. Close splash, create main window
    native::window::close_splash_window(app.handle());
    native::window::create_main_window(app.handle())?;

    Ok(())
})

Splash window creation

The splash window is frameless, transparent, and always on top:

pub fn create_splash_window(
    handle: &tauri::AppHandle,
) -> tauri::Result<()> {
    let url = WebviewUrl::App("../frontend/splash.html".into());

    let _window = WebviewWindowBuilder::new(handle, "splash", url)
        .title("myapp")
        .inner_size(400.0, 200.0)
        .decorations(false)
        .transparent(true)
        .always_on_top(true)
        .resizable(false)
        .build()?;

    Ok(())
}

Closing the splash

pub fn close_splash_window(handle: &tauri::AppHandle) {
    if let Some(window) = handle.get_webview_window("splash") {
        let _ = window.close();
    }
}

Main window with dev server polling

In development, the Vite dev server may not be ready when the window is created. The pattern is: show a loading page immediately, then navigate to the dev server once it responds.

const DEV_SERVER_URL: &str = "http://localhost:37461";

pub fn create_main_window(
    handle: &tauri::AppHandle,
) -> tauri::Result<()> {
    // Unique label for multiple windows
    let label = if handle.get_webview_window("main").is_some() {
        format!("main-{}", std::time::SystemTime::now()
            .duration_since(std::time::UNIX_EPOCH)
            .unwrap_or_default()
            .as_millis())
    } else {
        "main".to_string()
    };

    let url = if cfg!(debug_assertions) {
        // Inline loading page as data: URL
        WebviewUrl::External(
            loading_page_data_url().parse().unwrap(),
        )
    } else {
        WebviewUrl::default() // Bundled frontend
    };

    let window = WebviewWindowBuilder::new(handle, &label, url)
        .title("myapp")
        .inner_size(1400.0, 800.0)
        .visible(false) // Start hidden
        .on_navigation(move |url: &tauri::Url| {
            let url_str = url.as_str();
            // Allow local and tauri URLs
            if url_str.starts_with("http://localhost")
                || url_str.starts_with("tauri://")
                || url_str.starts_with("data:")
            {
                return true;
            }
            // Open external URLs in default browser
            if url_str.starts_with("http://")
                || url_str.starts_with("https://")
            {
                let owned = url_str.to_string();
                tauri::async_runtime::spawn_blocking(move || {
                    let _ = open::that(owned);
                });
                return false;
            }
            false // Block unknown schemes
        })
        .build()?;

    // In dev: poll Vite, navigate when ready
    if cfg!(debug_assertions) {
        let win = window.clone();
        std::thread::spawn(move || {
            if wait_for_dev_server(DEV_SERVER_URL, 120) {
                let url: tauri::Url =
                    DEV_SERVER_URL.parse().unwrap();
                let _ = win.navigate(url);
            }
        });
    }

    // Belt-and-suspenders: show on focus event OR after delay
    let win_clone = window.clone();
    window.on_window_event(move |event| {
        if let tauri::WindowEvent::Focused(true) = event {
            if !win_clone.is_visible().unwrap_or(false) {
                let _ = win_clone.show();
            }
        }
    });

    let win = window.clone();
    std::thread::spawn(move || {
        std::thread::sleep(std::time::Duration::from_millis(200));
        let _ = win.show();
    });

    Ok(())
}

Dev server readiness check

Use TCP connection attempts instead of HTTP requests for faster polling:

fn wait_for_dev_server(url: &str, timeout_secs: u64) -> bool {
    let addr = url
        .strip_prefix("http://")
        .or_else(|| url.strip_prefix("https://"))
        .and_then(|h| h.split('/').next())
        .expect("invalid URL");

    let start = std::time::Instant::now();
    let timeout = std::time::Duration::from_secs(timeout_secs);

    while start.elapsed() < timeout {
        if std::net::TcpStream::connect(addr).is_ok() {
            return true;
        }
        std::thread::sleep(std::time::Duration::from_millis(500));
    }
    false
}

Anti-flash: show on page load

For apps that load bundled frontend (no server polling needed), the simplest way to prevent white flash is to start hidden and show on first page load:

use tauri::webview::PageLoadEvent;

tauri::Builder::default()
  .on_page_load(|webview, payload| {
    if webview.label() == "main"
      && matches!(payload.event(), PageLoadEvent::Finished)
    {
      let _ = webview.window().show();
    }
  })

This replaces the manual 200ms delay approach and is more reliable because it waits for actual content to render.

{
  "permissions": [
    "core:window:allow-show",
    "core:window:allow-hide"
  ]
}

macOS: suppress press-and-hold accent menu

macOS shows an accent character popup when you press and hold a key. This interferes with apps that use key-repeat (text editors, terminal emulators). Suppress it in setup():

#[cfg(target_os = "macos")]
{
    use objc2_foundation::{NSUserDefaults, NSString};
    let defaults = NSUserDefaults::standardUserDefaults();
    unsafe {
        let key = NSString::from_str("ApplePressAndHoldEnabled");
        defaults.setBool_forKey(false, &key);
    }
}

External link handling

A Tauri webview behaves like an embedded browser — when a user clicks an <a href="https://example.com"> link, the webview navigates to that URL in-place, replacing your app’s UI. This is the natural default, but in most apps you want external links to open in the OS default browser instead.

There are two complementary approaches:

1. Rust-side on_navigation callback — intercepts all top-level navigations before they happen. Best as a catch-all safety net.
2. Frontend-side tauri-plugin-opener — lets you programmatically open URLs from JavaScript. Best for explicit “open in browser” actions.

Rust: on_navigation callback

The on_navigation callback controls which URLs the webview is allowed to load. Return true to allow the navigation, false to block it. For external URLs, open them in the default browser before returning false:

.on_navigation(move |url: &tauri::Url| {
    let url_str = url.as_str();

    // Allow local dev server and tauri asset URLs
    if url_str.starts_with("http://localhost")
        || url_str.starts_with("https://localhost")
        || url_str.starts_with("tauri://")
        || url_str.starts_with("asset://")
        || url_str.starts_with("data:")
    {
        return true;
    }

    // External HTTP(S) links -> default browser
    if url_str.starts_with("http://")
        || url_str.starts_with("https://")
    {
        let owned = url_str.to_string();
        tauri::async_runtime::spawn_blocking(move || {
            let _ = open::that(owned);
        });
        return false;
    }

    // Block unknown schemes (javascript:, file:, etc.)
    false
})

This uses the open crate (open::that()) to launch the OS default browser. Add it to your Cargo.toml:

[dependencies]
open = "5"

Frontend: tauri-plugin-opener

For cases where you want to open a URL from JavaScript — for example, a button click handler or a dynamically generated link — use the official tauri-plugin-opener:

# Install the Rust crate and the frontend JS package
cargo add tauri-plugin-opener
pnpm add @tauri-apps/plugin-opener

Register it in your Tauri builder:

tauri::Builder::default()
    .plugin(tauri_plugin_opener::init())
    // ...

Add the permission in your capability file:

{
  "permissions": ["opener:default"]
}

Then call it from the frontend:

import { openUrl } from "@tauri-apps/plugin-opener";

// Open a URL in the OS default browser
await openUrl("https://example.com");

Window destroy event handling

Use on_window_event to clean up resources when a window is destroyed:

.on_window_event(|window, event| {
    if let tauri::WindowEvent::Destroyed = event {
        if window.label() == "main" {
            if let Some(state) = window.try_state::<Arc<AppState>>() {
                // Kill all PTY sessions
                commands::terminal::kill_all_ptys(&state);
            }
        }
    }
})

Sidecar process cleanup

For apps that spawn sidecar processes, clean them up on window destroy using the run callback:

.build(tauri::generate_context!())
.expect("error while building tauri application")
.run(move |app_handle, event| match &event {
    tauri::RunEvent::WindowEvent {
        event: tauri::WindowEvent::Destroyed,
        ..
    } => {
        if let Ok(mut guard) = sidecar_arc.lock() {
            if let Some(mut sidecar) = guard.take() {
                kill_sidecar(&mut sidecar);
            }
        }
        app_handle.exit(0);
    }
    _ => {}
});

Window lifecycle summary

Key takeaways

1. Keep "windows": [] empty in tauri.conf.json when creating windows programmatically
2. Start windows hidden and show after content is ready to avoid white flash
3. Use data: URLs for loading pages — no need for bundled HTML files (but note the webview-data-url feature flag requirement)
4. Poll dev server with TCP connect — faster than HTTP requests
5. Always clean up child processes on window destroy
6. Use on_navigation to control link behavior — open external links in the default browser; use tauri-plugin-opener for programmatic URL opening from the frontend
7. Platform-specific code goes behind #[cfg(target_os = "macos")] guards

Related

• Find-in-Page — another webview behavior that needs custom implementation: Tauri does not expose the browser’s native Ctrl+F find dialog