Instalador de Windows

Las aplicaciones Tauri para Windows se distribuyen como Microsoft Installers (archivos .msi) usando WiX Toolset v3 o como ejecutables de instalación (archivos -setup.exe) usando NSIS.

Ten en cuenta que los instaladores .msi solo se pueden crear en Windows ya que WiX solo se ejecuta en sistemas Windows. La compilación cruzada para instaladores NSIS se muestra a continuación.

Esta guía proporciona información sobre las opciones de personalización disponibles para el instalador.

Compilación (Building)

Para compilar y empaquetar tu aplicación en un instalador de Windows, puedes usar la CLI de Tauri y ejecutar el comando tauri build en una computadora con Windows:

npm run tauri build

yarn tauri build

pnpm tauri build

deno task tauri build

bun tauri build

cargo tauri build

Compilar aplicaciones de Windows en Linux y macOS

La compilación cruzada de aplicaciones de Windows en equipos host Linux y macOS es posible con advertencias al usar NSIS. No es tan sencillo como compilar directamente en Windows y no se ha probado tanto. Por lo tanto, solo debe usarse como último recurso si las máquinas virtuales locales o soluciones de CI como GitHub Actions no funcionan para ti.

Dado que Tauri solo admite oficialmente el objetivo MSVC Windows, la configuración es un poco más compleja.

Algunas distribuciones de Linux tienen NSIS disponible en sus repositorios, por ejemplo en Ubuntu puedes instalar NSIS ejecutando este comando:

sudo apt install nsis

Pero en muchas otras distribuciones tienes que compilar NSIS tú mismo o descargar Stubs y Plugins manualmente que no se incluyeron en el paquete binario de la distribución. Fedora, por ejemplo, solo proporciona el binario pero no los Stubs ni los Plugins:

sudo dnf in mingw64-nsis
wget https://github.com/tauri-apps/binary-releases/releases/download/nsis-3/nsis-3.zip
unzip nsis-3.zip
sudo cp nsis-3.08/Stubs/* /usr/share/nsis/Stubs/
sudo cp -r nsis-3.08/Plugins/** /usr/share/nsis/Plugins/

En macOS necesitarás [Homebrew] para instalar NSIS:

brew install nsis

Instalar LLVM y el enlazador LLD

Dado que el enlazador predeterminado de Microsoft solo funciona en Windows, también necesitaremos instalar un nuevo enlazador. Para compilar el archivo de recursos de Windows que se usa para configurar el icono de la aplicación, entre otras cosas, también necesitaremos el binario llvm-rc que forma parte del proyecto LLVM.

Linux
macOS

sudo apt install lld llvm

En Linux también necesitas instalar el paquete clang si agregaste dependencias que compilan dependencias de C/C++ como parte de sus scripts de compilación. Las aplicaciones Tauri predeterminadas no deberían requerir esto.

brew install llvm

En macOS también debes agregar /opt/homebrew/opt/llvm/bin a tu $PATH como se sugiere en la salida de instalación.

Instalar el objetivo de Rust para Windows

Asumiendo que estás compilar para sistemas Windows de 64 bits:

rustup target add x86_64-pc-windows-msvc

Instalar `cargo-xwin`

En lugar de configurar los SDK de Windows manualmente, usaremos [cargo-xwin] como el "runner" de Tauri:

cargo install --locked cargo-xwin

De forma predeterminada, cargo-xwin descargará los SDK de Windows en una carpeta local del proyecto. Si tienes múltiples proyectos y quieres compartir esos archivos, puedes configurar la variable de entorno XWIN_CACHE_DIR con una ruta a la ubicación preferida.

Compilar la Aplicación

Ahora debería ser tan simple como agregar el runner y el target al comando tauri build:

npm run tauri build -- --runner cargo-xwin --target x86_64-pc-windows-msvc

yarn tauri build --runner cargo-xwin --target x86_64-pc-windows-msvc

pnpm tauri build --runner cargo-xwin --target x86_64-pc-windows-msvc

deno task tauri build --runner cargo-xwin --target x86_64-pc-windows-msvc

bun tauri build --runner cargo-xwin --target x86_64-pc-windows-msvc

cargo tauri build --runner cargo-xwin --target x86_64-pc-windows-msvc

La salida de la compilación estará entonces en target/x86_64-pc-windows-msvc/release/bundle/nsis/.

Compilar para 32-bit o ARM

La CLI de Tauri compila tu ejecutable usando la arquitectura de tu máquina por defecto. Suponiendo que estás desarrollando en una máquina de 64 bits, la CLI producirá aplicaciones de 64 bits.

Si necesitas admitir máquinas de 32 bits, puedes compilar tu aplicación con un objetivo de Rust diferente usando la bandera --target:

npm run tauri build -- --target i686-pc-windows-msvc

yarn tauri build --target i686-pc-windows-msvc

pnpm tauri build --target i686-pc-windows-msvc

deno task tauri build --target i686-pc-windows-msvc

bun tauri build --target i686-pc-windows-msvc

cargo tauri build --target i686-pc-windows-msvc

Por defecto, Rust solo instala toolchains para el objetivo de tu máquina, por lo que primero debes instalar el toolchain de Windows de 32 bits: rustup target add i686-pc-windows-msvc.

Si necesitas compilar para ARM64, primero debes instalar herramientas de compilación adicionales. Para hacer esto, abre Visual Studio Installer, haz clic en “Modificar” y en la pestaña “Componentes individuales” instala las “Herramientas de compilación C++ ARM64”. Al momento de escribir esto, el nombre exacto en VS2022 es Herramientas de compilación de MSVC v143 - VS 2022 C++ ARM64 (más reciente). Ahora puedes agregar el objetivo de Rust con rustup target add aarch64-pc-windows-msvc y luego usar el método mencionado anteriormente para compilar tu aplicación:

npm run tauri build -- --target aarch64-pc-windows-msvc

yarn tauri build --target aarch64-pc-windows-msvc

pnpm tauri build --target aarch64-pc-windows-msvc

deno task tauri build --target aarch64-pc-windows-msvc

bun tauri build --target aarch64-pc-windows-msvc

cargo tauri build --target aarch64-pc-windows-msvc

Soporte para Windows 7

De forma predeterminada, Microsoft Installer (.msi) no funciona en Windows 7 porque necesita descargar el bootstrapper de WebView2 si no está instalado (lo cual podría fallar si TLS 1.2 no está habilitado en el sistema operativo). Tauri incluye una opción para integrar el bootstrapper de WebView2 (consulta la sección Integración del Bootstrapper de WebView2 a continuación). El instalador basado en NSIS (-setup.exe) también admite el modo downloadBootstrapper en Windows 7.

Además, para usar la Notification API en Windows 7, debes habilitar la característica de Cargo windows7-compat:

[dependencies]
tauri-plugin-notification = { version = "2.0.0", features = [ "windows7-compat" ] }

Cumplimiento de FIPS

Si tu sistema requiere que el paquete MSI cumpla con FIPS, puedes establecer la variable de entorno TAURI_BUNDLER_WIX_FIPS_COMPLIANT en true antes de ejecutar tauri build. En PowerShell puedes establecerla para la sesión de terminal actual de esta manera:

$env:TAURI_BUNDLER_WIX_FIPS_COMPLIANT="true"

Opciones de instalación de WebView2

De forma predeterminada, los instaladores descargan el bootstrapper de WebView2 y lo ejecutan si el runtime no está instalado. Alternativamente, puedes integrar el bootstrapper, integrar el instalador sin conexión o usar una versión fija del runtime de WebView2. Consulta la siguiente tabla para ver una comparación entre estos métodos:

Método de Instalación	¿Requiere Conexión a Internet?	Tamaño Adicional del Instalador	Notas
`downloadBootstrapper`	Sí	0MB	`Predeterminado` Produce un tamaño de instalador más pequeño, pero no se recomienda para el despliegue en Windows 7 a través de archivos `.msi`.
`embedBootstrapper`	Sí	~1.8MB	Mejor soporte en Windows 7 para instaladores `.msi`.
`offlineInstaller`	No	~127MB	Integra el instalador de WebView2. Recomendado para entornos sin conexión.
`fixedVersion`	No	~180MB	Integra una versión fija de WebView2.
`skip`	No	0MB	⚠️ No recomendado No instala WebView2 como parte del instalador de Windows.

Bootstrapper descargado

Esta es la configuración predeterminada para compilar el instalador de Windows. Descarga el bootstrapper y lo ejecuta. Requiere una conexión a internet pero resulta en un tamaño de instalador más pequeño. Esto no se recomienda si vas a distribuir a Windows 7 mediante instaladores .msi.

{
  "bundle": {
    "windows": {
      "webviewInstallMode": {
        "type": "downloadBootstrapper"
      }
    }
  }
}

Bootstrapper integrado

Para integrar el bootstrapper de WebView2, establece webviewInstallMode en embedBootstrapper. Esto aumenta el tamaño del instalador en alrededor de 1.8MB, pero aumenta la compatibilidad con sistemas Windows 7.

{
  "bundle": {
    "windows": {
      "webviewInstallMode": {
        "type": "embedBootstrapper"
      }
    }
  }
}

Instalador sin conexión (Offline Installer)

Para integrar el bootstrapper de WebView2, establece webviewInstallMode en offlineInstaller. Esto aumenta el tamaño del instalador en alrededor de 127MB, pero permite que tu aplicación se instale incluso si no hay una conexión a internet disponible.

{
  "bundle": {
    "windows": {
      "webviewInstallMode": {
        "type": "offlineInstaller"
      }
    }
  }
}

Versión fija

Usar el runtime proporcionado por el sistema es excelente para la seguridad ya que los parches de vulnerabilidades de webview son gestionados por Windows. Si quieres controlar la distribución de WebView2 en cada una de tus aplicaciones (ya sea para gestionar los parches de versiones tú mismo o distribuir aplicaciones en entornos donde no haya conexión a internet disponible), Tauri puede empaquetar los archivos del runtime por ti.

Descarga la versión fija del runtime de WebView2 desde el sitio web de Microsoft. En este ejemplo, el nombre del archivo descargado es Microsoft.WebView2.FixedVersionRuntime.128.0.2739.42.x64.cab
Extrae el archivo a la carpeta core:

Expand .\Microsoft.WebView2.FixedVersionRuntime.128.0.2739.42.x64.cab -F:* ./src-tauri

Configura la ruta del runtime de WebView2 en tauri.conf.json:

{
  "bundle": {
    "windows": {
      "webviewInstallMode": {
        "type": "fixedRuntime",
        "path": "./Microsoft.WebView2.FixedVersionRuntime.98.0.1108.50.x64/"
      }
    }
  }
}

Ejecuta tauri build para producir el instalador de Windows con el runtime de WebView2 fijo.

Omitir la instalación

Puedes eliminar la comprobación de descarga del runtime de WebView2 del instalador estableciendo webviewInstallMode en skip. Tu aplicación NO funcionará si el usuario no tiene el runtime instalado.

Tu aplicación NO funcionará si el usuario no tiene el runtime instalado y no intentará instalarlo.

{
  "bundle": {
    "windows": {
      "webviewInstallMode": {
        "type": "skip"
      }
    }
  }
}

Versión mínima de Webview2

Si tu aplicación requiere características solo disponibles en versiones más recientes de Webview2 (como esquemas de URI personalizados), puedes indicar al instalador de Windows que verifique la versión actual de Webview2 y ejecute el bootstrapper de Webview2 si no coincide con la versión objetivo.

{
  "bundle": {
    "windows": {
      "minimumWebview2Version": "110.0.1531.0"
    }
  }
}

Personalizar el instalador de WiX

Consulta la configuración de WiX para obtener la lista completa de opciones de personalización.

Plantilla del instalador

El paquete del instalador de Windows .msi se compila utilizando WiX Toolset v3. Actualmente, aparte de las configuraciones predefinidas, puedes cambiarlo utilizando código fuente de WiX personalizado (un archivo XML con la extensión de archivo .wxs) o mediante fragmentos de WiX.

Reemplazar el código del instalador con un archivo WiX personalizado

El XML del instalador de Windows definido por Tauri está configurado para funcionar en el caso de uso común de aplicaciones simples basadas en webview (puedes encontrarlo aquí). Utiliza handlebars para que la CLI de Tauri pueda personalizar tu instalador de acuerdo con la definición de tu tauri.conf.json. Si necesitas un instalador completamente diferente, se puede configurar una plantilla personalizada en tauri.bundle.windows.wix.template.

Extender el instalador con fragmentos WiX

Un fragmento de WiX es un contenedor donde puedes configurar casi todo lo que ofrece WiX. En este ejemplo, definiremos un fragmento que escribe dos entradas de registro:

<?xml version="1.0" encoding="utf-8"?>
<Wix xmlns="http://schemas.microsoft.com/wix/2006/wi">
  <Fragment>
    <!-- these registry entries should be installed
     to the target user's machine -->
    <DirectoryRef Id="TARGETDIR">
      <!-- groups together the registry entries to be installed -->
      <!-- Note the unique `Id` we provide here -->
      <Component Id="MyFragmentRegistryEntries" Guid="*">
        <!-- the registry key will be under
       HKEY_CURRENT_USER\Software\MyCompany\MyApplicationName -->
        <!-- Tauri uses the second portion of the
       bundle identifier as the `MyCompany` name
       (e.g. `tauri-apps` in `com.tauri-apps.test`)  -->
        <RegistryKey
          Root="HKCU"
          Key="Software\MyCompany\MyApplicationName"
          Action="createAndRemoveOnUninstall"
        >
          <!-- values to persist on the registry -->
          <RegistryValue
            Type="integer"
            Name="SomeIntegerValue"
            Value="1"
            KeyPath="yes"
          />
          <RegistryValue Type="string" Value="Default Value" />
        </RegistryKey>
      </Component>
    </DirectoryRef>
  </Fragment>
</Wix>

Guarda el archivo de fragmento con la extensión .wxs en la carpeta src-tauri/windows/fragments y haz referencia a él en tauri.conf.json:

{
  "bundle": {
    "windows": {
      "wix": {
        "fragmentPaths": ["./windows/fragments/registry.wxs"],
        "componentRefs": ["MyFragmentRegistryEntries"]
      }
    }
  }
}

Ten en cuenta que los ID de los elementos ComponentGroup, Component, FeatureGroup, Feature y Merge deben tener referencia en el objeto wix de tauri.conf.json en componentGroupRefs, componentRefs, featureGroupRefs, featureRefs y mergeRefs respectivamente para ser incluidos en el instalador.

Internacionalización

El instalador de WiX se compila utilizando el idioma en-US por defecto. La internacionalización (i18n) se puede configurar mediante la propiedad tauri.bundle.windows.wix.language, definiendo los idiomas con los que Tauri debe compilar un instalador. Puedes encontrar los nombres de idioma a utilizar en la columna Language-Culture del sitio web de Microsoft.

Compilar un instalador de WiX para un solo idioma

Para crear un único instalador dirigido a un idioma específico, establece el valor de language como una cadena de texto:

{
  "bundle": {
    "windows": {
      "wix": {
        "language": "fr-FR"
      }
    }
  }
}

Compilar un instalador de WiX para cada idioma en una lista

Para compilar un instalador dirigido a una lista de idiomas, usa un arreglo. Se creará un instalador específico para cada idioma, con la clave del idioma como sufijo:

{
  "bundle": {
    "windows": {
      "wix": {
        "language": ["en-US", "pt-BR", "fr-FR"]
      }
    }
  }
}

Configurar las cadenas del instalador de WiX para cada idioma

Se puede definir un objeto de configuración para cada idioma para configurar las cadenas de localización:

{
  "bundle": {
    "windows": {
      "wix": {
        "language": {
          "en-US": null,
          "pt-BR": {
            "localePath": "./wix/locales/pt-BR.wxl"
          }
        }
      }
    }
  }
}

La propiedad localePath define la ruta a un archivo de idioma, un XML que configura la cultura del idioma:

<WixLocalization
  Culture="en-US"
  xmlns="http://schemas.microsoft.com/wix/2006/localization"
>
  <String Id="LaunchApp"> Launch MyApplicationName </String>
  <String Id="DowngradeErrorMessage">
    A newer version of MyApplicationName is already installed.
  </String>
  <String Id="PathEnvVarFeature">
    Add the install location of the MyApplicationName executable to
    the PATH system environment variable. This allows the
    MyApplicationName executable to be called from any location.
  </String>
  <String Id="InstallAppFeature">
    Installs MyApplicationName.
  </String>
</WixLocalization>

Actualmente, Tauri hace referencia a las siguientes cadenas de localización: LaunchApp, DowngradeErrorMessage, PathEnvVarFeature e InstallAppFeature. Puedes definir tus propias cadenas y hacer referencia a ellas en tu plantilla o fragmentos personalizados con "!(loc.TheStringId)". Consulta la documentación de localización de WiX para obtener más información.

Personalizar el instalador de NSIS

Consulta la configuración de NSIS para obtener la lista completa de opciones de personalización.

Plantilla del instalador

El script .nsi del instalador de NSIS definido por Tauri está configurado para funcionar en el caso de uso común de aplicaciones simples basadas en webview (puedes encontrarlo aquí). Utiliza handlebars para que la CLI de Tauri pueda personalizar tu instalador de acuerdo con la definición de tu tauri.conf.json. Si necesitas un instalador completamente diferente, se puede configurar una plantilla personalizada en tauri.bundle.windows.nsis.template.

Extender el instalador

Si solo necesitas extender algunos pasos de instalación, es posible que puedas usar hooks del instalador en lugar de reemplazar toda la plantilla del instalador.

Los hooks admitidos son:

NSIS_HOOK_PREINSTALL: Se ejecuta antes de copiar archivos, establecer valores de claves de registro y crear accesos directos.
NSIS_HOOK_POSTINSTALL: Se ejecuta después de que el instalador ha terminado de copiar todos los archivos, establecer las claves de registro y creado los accesos directos.
NSIS_HOOK_PREUNINSTALL: Se ejecuta antes de eliminar cualquier archivo, clave de registro y acceso directo.
NSIS_HOOK_POSTUNINSTALL: Se ejecuta después de que se hayan eliminado archivos, claves de registro y accesos directos.

Por ejemplo, crea un archivo hooks.nsh en la carpeta src-tauri/windows y define los hooks que necesitas:

!macro NSIS_HOOK_PREINSTALL
  MessageBox MB_OK "PreInstall"
!macroend

!macro NSIS_HOOK_POSTINSTALL
  MessageBox MB_OK "PostInstall"
!macroend

!macro NSIS_HOOK_PREUNINSTALL
  MessageBox MB_OK "PreUnInstall"
!macroend

!macro NSIS_HOOK_POSTUNINSTALL
  MessageBox MB_OK "PostUninstall"
!macroend

Luego debes configurar Tauri para usar ese archivo de hooks:

{
  "bundle": {
    "windows": {
      "nsis": {
        "installerHooks": "./windows/hooks.nsh"
      }
    }
  }
}

Instalar dependencias con Hooks

Puedes usar hooks del instalador para instalar automáticamente las dependencias del sistema que requiere tu aplicación. Esto es particularmente útil para dependencias en tiempo de ejecución como Visual C++ Redistributables, DirectX, OpenSSL u otras librerías del sistema que pueden no estar presentes en todos los sistemas Windows.

Ejemplo de instalador MSI (Visual C++ Redistributable):

!macro NSIS_HOOK_POSTINSTALL
  ; Check if Visual C++ 2019 Redistributable is installed (via Windows Registry)
  ReadRegDWord $0 HKLM "SOFTWARE\Microsoft\VisualStudio\14.0\VC\Runtimes\x64" "Installed"

  ${If} $0 == 1
    DetailPrint "Visual C++ Redistributable already installed"
    Goto vcredist_done
  ${EndIf}

  ; Install from bundled MSI if not installed
  ${If} ${FileExists} "$INSTDIR\resources\vc_redist.x64.msi"
    DetailPrint "Installing Visual C++ Redistributable..."
    ; Copy to TEMP folder and then execute installer
    CopyFiles "$INSTDIR\resources\vc_redist.x64.msi" "$TEMP\vc_redist.x64.msi"
    ExecWait 'msiexec /i "$TEMP\vc_redist.x64.msi" /passive /norestart' $0

    ; Check wether installation process exited successfully (code 0) or not
    ${If} $0 == 0
      DetailPrint "Visual C++ Redistributable installed successfully"
    ${Else}
      MessageBox MB_ICONEXCLAMATION "Visual C++ installation failed. Some features may not work."
    ${EndIf}

    ; Clean up setup files from TEMP and your installed app
    Delete "$TEMP\vc_redist.x64.msi"
    Delete "$INSTDIR\resources\vc_redist.x64.msi"
  ${EndIf}

  vcredist_done:
!macroend

Key considerations:

Una buena práctica es verificar siempre si la dependencia ya está instalada utilizando claves de registro o existencia de archivos o a través del comando where de Windows.
Usa los flags /passive, /quiet, o /silent para evitar interrumpir el flujo de instalación. Revisa las opciones de msiexec para archivos .msi, o el manual del instalador para flags específicos de la aplicación
Incluye /norestart para evitar reinicios automáticos del sistema durante la instalación para configuraciones que reinician los dispositivos del usuario
Limpia los archivos temporales y los instaladores empaquetados para evitar sobrecargar la aplicación
Considera que las dependencias pueden ser compartidas con otras aplicaciones al desinstalar
Proporciona mensajes de error significativos si la instalación falla

Asegúrate de empaquetar los instaladores de dependencias en tu carpeta src-tauri/resources y agregarlos a tauri.conf.json para que se empaqueten y se pueda acceder a ellos durante la instalación desde $INSTDIR\resources\:

{
  "bundle": {
    "resources": [
      "resources/my-dependency.exe",
      "resources/another-one.msi
    ]
  }
}

Modos de instalación

De forma predeterminada, el instalador instalará tu aplicación solo para el usuario actual. La ventaja de esta opción es que el instalador no requiere privilegios de administrador para ejecutarse, pero la aplicación se instala en la carpeta %LOCALAPPDATA% en lugar de C:/Program Files.

Si prefieres que la instalación de tu aplicación esté disponible en todo el sistema (lo que requiere privilegios de Administrador), puedes establecer installMode en perMachine:

{
  "bundle": {
    "windows": {
      "nsis": {
        "installMode": "perMachine"
      }
    }
  }
}

Alternativamente, puedes permitir que el usuario elija si la aplicación debe instalarse solo para el usuario actual o en todo el sistema estableciendo el installMode en both. Ten en cuenta que el instalador requerirá privilegios de Administrador para ejecutarse.

Consulta NSISInstallerMode para obtener más información.

Internacionalización

El instalador NSIS es un instalador multilenguaje, lo que significa que siempre tienes un único instalador que contiene todas las traducciones seleccionadas.

Puedes especificar qué idiomas incluir usando la propiedad tauri.bundle.windows.nsis.languages. Una lista de idiomas admitidos por NSIS está disponible en el proyecto de GitHub de NSIS. Hay algunas traducciones específicas de Tauri requeridas, por lo que si ves textos no traducidos, no dudes en abrir una solicitud de función en el repositorio principal de Tauri. También puedes proporcionar archivos de traducción personalizados.

De forma predeterminada, se utiliza el idioma predeterminado del sistema operativo para determinar el idioma del instalador. También puedes configurar el instalador para que muestre un selector de idioma antes de que se procesen los contenidos del instalador:

{
  "bundle": {
    "windows": {
      "nsis": {
        "displayLanguageSelector": true
      }
    }
  }
}

Apoya en Open Collective Patrocina en GitHub

Instalador de Windows

Compilación (Building)

Compilar aplicaciones de Windows en Linux y macOS

Instalar NSIS

Instalar LLVM y el enlazador LLD

Instalar el objetivo de Rust para Windows

Instalar cargo-xwin

Compilar la Aplicación

Compilar para 32-bit o ARM

Soporte para Windows 7

Cumplimiento de FIPS

Opciones de instalación de WebView2

Bootstrapper descargado

Bootstrapper integrado

Instalador sin conexión (Offline Installer)

Versión fija

Omitir la instalación

Versión mínima de Webview2

Personalizar el instalador de WiX

Plantilla del instalador

Reemplazar el código del instalador con un archivo WiX personalizado

Extender el instalador con fragmentos WiX

Internacionalización

Compilar un instalador de WiX para un solo idioma

Compilar un instalador de WiX para cada idioma en una lista

Configurar las cadenas del instalador de WiX para cada idioma

Personalizar el instalador de NSIS

Plantilla del instalador

Extender el instalador

Instalar dependencias con Hooks

Modos de instalación

Internacionalización

Instalar `cargo-xwin`