Updater

GitHubnpmcrates.io

Referencia de API

Actualiza automáticamente tu app de Tauri con un servidor de actualización o un JSON estático.

Plataformas Soportadas

Este plugin requiere una versión de Rust de al menos 1.77.2

Plataforma	Nivel	Notas
windows
linux
macos
android
ios

Configuración

Instala el plugin updater de Tauri para comenzar.

Automático

Usa el gestor de paquetes de tu proyecto para agregar la dependencia:

npm

npm run tauri add updater

yarn

yarn run tauri add updater

pnpm

pnpm tauri add updater

deno

deno task tauri add updater

bun

bun tauri add updater

cargo

cargo tauri add updater

Manual

1. Ejecuta el siguiente comando en la carpeta src-tauri para agregar el plugin a las dependencias del proyecto en Cargo.toml:

   cargo add tauri-plugin-updater --target 'cfg(any(target_os = "macos", windows, target_os = "linux"))'

2. Modifica lib.rs para inicializar el plugin:

   lib.rs

   #[cfg_attr(mobile, tauri::mobile_entry_point)]
   pub fn run() {
       tauri::Builder::default()
           .setup(|app| {
               #[cfg(desktop)]
               app.handle().plugin(tauri_plugin_updater::Builder::new().build());
               Ok(())
           })
           .run(tauri::generate_context!())
           .expect("error while running tauri application");
   }

3. Puedes instalar los bindings de JavaScript utilizando tu gestor de paquetes de JavaScript preferido:

   npm

   npm install @tauri-apps/plugin-updater

   yarn

   yarn add @tauri-apps/plugin-updater

   pnpm

   pnpm add @tauri-apps/plugin-updater

   deno

   deno add npm:@tauri-apps/plugin-updater

   bun

   bun add @tauri-apps/plugin-updater

Firmar actualizaciones

El actualizador de Tauri necesita una firma para verificar que la actualización provenga de una fuente de confianza. Esto no se puede desactivar.

Para firmar tus actualizaciones necesitas dos claves:

1. La clave pública, que se establecerá en el tauri.conf.json para validar los artefactos antes de la instalación. Esta clave pública se puede cargar y compartir de forma segura siempre que tu clave privada esté protegida.
2. La clave privada, que se usa para firmar tus archivos de instalador. NUNCA debes compartir esta clave con nadie. Además, si pierdes esta clave NO podrás publicar nuevas actualizaciones para los usuarios que ya tienen la app instalada. ¡Es importante guardar esta clave en un lugar seguro!

Para generar las claves, la CLI de Tauri proporciona el comando signer generate. Puedes ejecutar esto para crear las claves en la carpeta personal:

npm

npm run tauri signer generate -- -w ~/.tauri/myapp.key

yarn

yarn tauri signer generate -w ~/.tauri/myapp.key

pnpm

pnpm tauri signer generate -w ~/.tauri/myapp.key

deno

deno task tauri signer generate -w ~/.tauri/myapp.key

bun

bunx tauri signer generate -w ~/.tauri/myapp.key

cargo

cargo tauri signer generate -w ~/.tauri/myapp.key

Compilación (Building)

Al compilar tus artefactos de actualización, necesitas tener la clave privada que generaste anteriormente en tus variables de entorno. ¡Los archivos .env no funcionan!

Mac/Linux

export TAURI_SIGNING_PRIVATE_KEY="Path or content of your private key"
# optionally also add a password
export TAURI_SIGNING_PRIVATE_KEY_PASSWORD=""

Ventanas

Ejecuta esto en PowerShell:

$env:TAURI_SIGNING_PRIVATE_KEY="Path or content of your private key"
<# optionally also add a password #>
$env:TAURI_SIGNING_PRIVATE_KEY_PASSWORD=""

Después de eso, puedes ejecutar el build de Tauri como de costumbre y Tauri generará los paquetes de actualización y sus firmas. Los archivos generados dependen del valor de configuración createUpdaterArtifacts configurado a continuación.

v2

{
  "bundle": {
    "createUpdaterArtifacts": true
  }
}

En Linux, Tauri creará la AppImage normal dentro de la carpeta target/release/bundle/appimage/:

• myapp.AppImage - El paquete estándar de la app. El actualizador lo reutilizará.
• myapp.AppImage.sig - La firma del paquete del actualizador.

En macOS, Tauri creará un archivo .tar.gz a partir del paquete de aplicación dentro de la carpeta target/release/bundle/macos/:

• myapp.app - El paquete estándar de la app.
• myapp.app.tar.gz - El paquete del actualizador.
• myapp.app.tar.gz.sig - La firma del paquete de actualización.

En Windows, Tauri creará los instaladores normales MSI y NSIS dentro de las carpetas target/release/bundle/msi/ y target/release/bundle/nsis:

• myapp-setup.exe - El paquete estándar de la app. El actualizador lo reutilizará.
• myapp-setup.exe.sig - La firma del paquete de actualización.
• myapp.msi - El paquete estándar de la app. El actualizador lo reutilizará.
• myapp.msi.sig - La firma del paquete de actualización.

compatible con v1

{
  "bundle": {
    "createUpdaterArtifacts": "v1Compatible"
  }
}

En Linux, Tauri creará un archivo .tar.gz a partir de la AppImage dentro de la carpeta target/release/bundle/appimage/:

• myapp.AppImage - El paquete estándar de la app.
• myapp.AppImage.tar.gz - El paquete del actualizador.
• myapp.AppImage.tar.gz.sig - La firma del paquete de actualización.

En macOS, Tauri creará un archivo .tar.gz a partir del paquete de aplicación dentro de la carpeta target/release/bundle/macos/:

• myapp.app - El paquete estándar de la app.
• myapp.app.tar.gz - El paquete del actualizador.
• myapp.app.tar.gz.sig - La firma del paquete de actualización.

En Windows, Tauri creará archivos .zip a partir de los instaladores MSI y NSIS dentro de las carpetas target/release/bundle/msi/ y target/release/bundle/nsis:

• myapp-setup.exe - El paquete estándar de la app.
• myapp-setup.nsis.zip - El paquete del actualizador.
• myapp-setup.nsis.zip.sig - La firma del paquete de actualización.
• myapp.msi - El paquete estándar de la app.
• myapp.msi.zip - El paquete del actualizador.
• myapp.msi.zip.sig - La firma del paquete de actualización.

Configuración de Tauri

Configura el tauri.conf.json en este formato para que el actualizador comience a funcionar.

Claves	Descripción
createUpdaterArtifacts	Establecer esto en true le indica al empaquetador de aplicaciones de Tauri que cree artefactos para el actualizador. Si estás migrando tu aplicación desde una versión anterior de Tauri, establécelo en "v1Compatible" en su lugar. Esta configuración se eliminará en v3, así que asegúrate de cambiarla a true una vez que todos tus usuarios hayan migrado a v2.
pubkey	Esta debe ser la clave pública generada desde la CLI de Tauri en el paso anterior. ¡No puede ser una ruta de archivo!
endpoints	Debe ser un array de URL de endpoints como cadenas de texto. TLS es obligatorio en modo producción. ¡Tauri solo continuará a la siguiente URL si se devuelve un código de estado distinto de 2XX!
dangerousInsecureTransportProtocol	Establecer esto en true permite que el actualizador acepte endpoints que no sean HTTPS. ¡Usa esta configuración con precaución!

Cada URL de actualizador puede contener las siguientes variables dinámicas, lo que te permite determinar en el lado del servidor si hay una actualización disponible.

• {{current_version}}: La versión de la app que solicita la actualización.
• {{target}}: El nombre del sistema operativo (uno de linux, windows o darwin).
• {{arch}}: La arquitectura de la máquina (una de x86_64, i686, aarch64 o armv7).

tauri.conf.json

{
  "bundle": {
    "createUpdaterArtifacts": true
  },
  "plugins": {
    "updater": {
      "pubkey": "CONTENT FROM PUBLICKEY.PEM",
      "endpoints": [
        "https://releases.myapp.com/{{target}}/{{arch}}/{{current_version}}",
        // or a static github json file
        "https://github.com/user/repo/releases/latest/download/latest.json"
      ]
    }
  }
}

Consejo

Las variables personalizadas no son compatibles, pero puedes definir un target personalizado {{target}}.

installMode en Windows

En Windows hay una configuración opcional adicional "installMode" para cambiar cómo se instala la actualización.

tauri.conf.json

{
  "plugins": {
    "updater": {
      "windows": {
        "installMode": "passive"
      }
    }
  }
}

• "passive": Habrá una pequeña ventana con una barra de progreso. La actualización se instalará sin requerir interacción del usuario. Generalmente recomendado y es el modo por defecto.
• "basicUi": Se mostrará una interfaz de usuario básica que requiere interacción del usuario para finalizar la instalación.
• "quiet": No habrá comentarios de progreso para el usuario. Con este modo, el instalador no puede solicitar privilegios de administrador por sí mismo, por lo que solo funciona en instalaciones a nivel de usuario o cuando tu app ya se ejecuta con privilegios de administrador. Generalmente no recomendado.

Soporte de servidor

El plugin updater se puede utilizar de dos formas. Ya sea con un servidor de actualización dinámico o con un archivo JSON estático (para usar en servicios como S3 o GitHub gists).

Archivo JSON estático

Al usar estático, solo necesitas devolver un JSON que contenga la información requerida.

Claves	Descripción
version	Debe ser un SemVer válido, con o sin una v inicial, lo que significa que tanto 1.0.0 como v1.0.0 son válidos.
notes	Notas sobre la actualización.
pub_date	La fecha debe estar formateada según el RFC 3339 si está presente.
platforms	Cada clave de plataforma está en el formato OS-ARCH, donde OS es uno de linux, darwin o windows, y ARCH es uno de x86_64, aarch64, i686 o armv7.
signature	El contenido del archivo .sig generado, que puede cambiar con cada build. ¡Una ruta o URL no funciona!

Nota

Al utilizar targets personalizados, la cadena de target proporcionada se compara con la clave platforms en lugar del valor por defecto OS-ARCH.

Las claves obligatorias son "version", "platforms.[target].url" y "platforms.[target].signature"; las demás son opcionales.

{
  "version": "",
  "notes": "",
  "pub_date": "",
  "platforms": {
    "linux-x86_64": {
      "signature": "",
      "url": ""
    },
    "windows-x86_64": {
      "signature": "",
      "url": ""
    },
    "darwin-x86_64": {
      "signature": "",
      "url": ""
    }
  }
}

Ten en cuenta que Tauri validará todo el archivo antes de verificar el campo version, así que asegúrate de que todas las configuraciones de plataformas existentes sean válidas y estén completas.

Consejo

Tauri Action genera un archivo JSON estático para que lo uses en CDNs como GitHub Releases.

Servidor de actualización dinámico

Al utilizar un servidor de actualización dinámico, Tauri seguirá las instrucciones del servidor. Para desactivar la comprobación de versión interna puedes sobrescribir la comparación de versiones del plugin, esto instalará la versión enviada por el servidor (útil si necesitas hacer un rollback de tu app).

Tu servidor puede usar variables definidas en la URL del endpoint anterior para determinar si se requiere una actualización. Si necesitas más datos, puedes incluir encabezados de solicitud adicionales en Rust a tu gusto.

Tu servidor debe responder con un código de estado 204 No Content si no hay ninguna actualización disponible.

Si se requiere una actualización, tu servidor debe responder con un código de estado 200 OK y una respuesta JSON en este formato:

Claves	Descripción
version	Debe ser un SemVer válido, con o sin una v inicial, lo que significa que tanto 1.0.0 como v1.0.0 son válidos.
notes	Notas sobre la actualización.
pub_date	La fecha debe estar formateada según el RFC 3339 si está presente.
url	Debe ser una URL válida al paquete de actualización.
signature	El contenido del archivo .sig generado, que puede cambiar con cada build. ¡Una ruta o URL no funciona!

Las claves obligatorias son "url", "version" y "signature"; las demás son opcionales.

{
  "version": "",
  "pub_date": "",
  "url": "",
  "signature": "",
  "notes": ""
}

Consejo

CrabNebula, un socio oficial de Tauri, ofrece un servidor de actualización dinámico. Para obtener más información, consulta la documentación de Distribución con CrabNebula Cloud.

Comprobando actualizaciones

La API por defecto para comprobar e instalar actualizaciones aprovecha los endpoints configurados y se puede acceder tanto desde código JavaScript como Rust.

JavaScript

import { check } from '@tauri-apps/plugin-updater';
import { relaunch } from '@tauri-apps/plugin-process';

const update = await check();
if (update) {
  console.log(
    `found update ${update.version} from ${update.date} with notes ${update.body}`
  );
  let downloaded = 0;
  let contentLength = 0;
  // alternatively we could also call update.download() and update.install() separately
  await update.downloadAndInstall((event) => {
    switch (event.event) {
      case 'Started':
        contentLength = event.data.contentLength;
        console.log(`started downloading ${event.data.contentLength} bytes`);
        break;
      case 'Progress':
        downloaded += event.data.chunkLength;
        console.log(`downloaded ${downloaded} from ${contentLength}`);
        break;
      case 'Finished':
        console.log('download finished');
        break;
    }
  });

  console.log('update installed');
  await relaunch();
}

Para obtener más información, consulta la documentación de la API de JavaScript.

Rust

src-tauri/src/lib.rs

use tauri_plugin_updater::UpdaterExt;

pub fn run() {
  tauri::Builder::default()
    .setup(|app| {
      let handle = app.handle().clone();
      tauri::async_runtime::spawn(async move {
        update(handle).await.unwrap();
      });
      Ok(())
    })
    .run(tauri::generate_context!())
    .unwrap();
}

async fn update(app: tauri::AppHandle) -> tauri_plugin_updater::Result<()> {
  if let Some(update) = app.updater()?.check().await? {
    let mut downloaded = 0;

    // alternatively we could also call update.download() and update.install() separately
    update
      .download_and_install(
        |chunk_length, content_length| {
          downloaded += chunk_length;
          println!("downloaded {downloaded} from {content_length:?}");
        },
        || {
          println!("download finished");
        },
      )
      .await?;

    println!("update installed");
    app.restart();
  }

  Ok(())
}

Consejo

Para notificar al frontend sobre el progreso de la descarga, considera usar un comando con un channel.

Comando del actualizador

#[cfg(desktop)]
mod app_updates {
    use std::sync::Mutex;
    use serde::Serialize;
    use tauri::{ipc::Channel, AppHandle, State};
    use tauri_plugin_updater::{Update, UpdaterExt};

    #[derive(Debug, thiserror::Error)]
    pub enum Error {
        #[error(transparent)]
        Updater(#[from] tauri_plugin_updater::Error),
        #[error("there is no pending update")]
        NoPendingUpdate,
    }

    impl Serialize for Error {
        fn serialize<S>(&self, serializer: S) -> std::result::Result<S::Ok, S::Error>
        where
            S: serde::Serializer,
        {
            serializer.serialize_str(self.to_string().as_str())
        }
    }

    type Result<T> = std::result::Result<T, Error>;

    #[derive(Clone, Serialize)]
    #[serde(tag = "event", content = "data")]
    pub enum DownloadEvent {
        #[serde(rename_all = "camelCase")]
        Started {
            content_length: Option<u64>,
        },
        #[serde(rename_all = "camelCase")]
        Progress {
            chunk_length: usize,
        },
        Finished,
    }

    #[derive(Serialize)]
    #[serde(rename_all = "camelCase")]
    pub struct UpdateMetadata {
        version: String,
        current_version: String,
    }

    #[tauri::command]
    pub async fn fetch_update(
        app: AppHandle,
        pending_update: State<'_, PendingUpdate>,
    ) -> Result<Option<UpdateMetadata>> {
        let channel = "stable";
        let url = url::Url::parse(&format!(
            "https://cdn.myupdater.com/{{{{target}}}}-{{{{arch}}}}/{{{{current_version}}}}?channel={channel}",
        )).expect("invalid URL");

      let update = app
          .updater_builder()
          .endpoints(vec![url])?
          .build()?
          .check()
          .await?;

      let update_metadata = update.as_ref().map(|update| UpdateMetadata {
          version: update.version.clone(),
          current_version: update.current_version.clone(),
      });

      *pending_update.0.lock().unwrap() = update;

      Ok(update_metadata)
    }

    #[tauri::command]
    pub async fn install_update(pending_update: State<'_, PendingUpdate>, on_event: Channel<DownloadEvent>) -> Result<()> {
        let Some(update) = pending_update.0.lock().unwrap().take() else {
            return Err(Error::NoPendingUpdate);
        };

        let started = false;

        update
            .download_and_install(
                |chunk_length, content_length| {
                    if !started {
                        let _ = on_event.send(DownloadEvent::Started { content_length });
                        started = true;
                    }

                    let _ = on_event.send(DownloadEvent::Progress { chunk_length });
                },
                || {
                    let _ = on_event.send(DownloadEvent::Finished);
                },
            )
            .await?;

        Ok(())
    }

    struct PendingUpdate(Mutex<Option<Update>>);
}

#[cfg_attr(mobile, tauri::mobile_entry_point)]
pub fn run() {
    tauri::Builder::default()
        .plugin(tauri_plugin_process::init())
        .setup(|app| {
            #[cfg(desktop)]
            {
                app.handle().plugin(tauri_plugin_updater::Builder::new().build());
                app.manage(app_updates::PendingUpdate(Mutex::new(None)));
            }
            Ok(())
        })
        .invoke_handler(tauri::generate_handler![
            #[cfg(desktop)]
            app_updates::fetch_update,
            #[cfg(desktop)]
            app_updates::install_update
        ])
}

Para obtener más información, consulta la documentación de la API de Rust.

Ten en cuenta que no es necesario reiniciar tu app inmediatamente después de instalar una actualización y puedes elegir cómo gestionar la actualización esperando a que el usuario reinicie manualmente la app, o pidiéndole que seleccione cuándo hacerlo.

Nota

En Windows la aplicación se cierra automáticamente cuando se ejecuta el paso de instalación debido a una limitación de los instaladores de Windows.

Al comprobar y descargar actualizaciones es posible definir un tiempo de espera (timeout) de solicitud personalizado, un proxy y encabezados de solicitud.

JavaScript

import { check } from '@tauri-apps/plugin-updater';

const update = await check({
  proxy: '<proxy url>',
  timeout: 30000 /* milliseconds */,
  headers: {
    Authorization: 'Bearer <token>',
  },
});

Rust

use tauri_plugin_updater::UpdaterExt;
let update = app
  .updater_builder()
  .timeout(std::time::Duration::from_secs(30))
  .proxy("<proxy-url>".parse().expect("invalid URL"))
  .header("Authorization", "Bearer <token>")
  .build()?
  .check()
  .await?;

Configuración en tiempo de ejecución

Las API del actualizador también permiten configurar el actualizador en tiempo de ejecución para una mayor flexibilidad. Por razones de seguridad, algunas API solo están disponibles para Rust.

Endpoints

Establecer las URL que se deben consultar para comprobar actualizaciones en tiempo de ejecución permite actualizaciones más dinámicas, como canales de lanzamiento separados:

use tauri_plugin_updater::UpdaterExt;
let channel = if beta { "beta" } else { "stable" };
let update_url = format!("https://{channel}.myserver.com/{{{{target}}}}-{{{{arch}}}}/{{{{current_version}}}}");

let update = app
  .updater_builder()
  .endpoints(vec![update_url])?
  .build()?
  .check()
  .await?;

Consejo

Ten en cuenta que al usar format!() para interpolar la URL de actualización necesitas escapes dobles para las variables, por ejemplo: {{{{target}}}}.

Clave pública

Establecer la clave pública en tiempo de ejecución puede ser útil para implementar una lógica de rotación de claves. Se puede establecer mediante el plugin builder o el updater builder:

tauri_plugin_updater::Builder::new().pubkey("<your public key>").build()

use tauri_plugin_updater::UpdaterExt;

let update = app
  .updater_builder()
  .pubkey("<your public key>")
  .build()?
  .check()
  .await?;

Target personalizado

Por defecto, el actualizador te permite usar las variables {{target}} y {{arch}} para determinar qué recurso de actualización debe entregarse. Si necesitas más información sobre tus actualizaciones (por ejemplo, al distribuir una opción binaria Universal de macOS o al tener más variantes de compilación), puedes establecer un target personalizado.

JavaScript

import { check } from '@tauri-apps/plugin-updater';

const update = await check({
  target: 'macos-universal',
});

Rust

Los targets personalizados se pueden establecer mediante el plugin builder o el updater builder:

tauri_plugin_updater::Builder::new().target("macos-universal").build()

use tauri_plugin_updater::UpdaterExt;
let update = app
  .updater_builder()
  .target("macos-universal")
  .build()?
  .check()
  .await?;

Consejo

La clave por defecto $target-$arch se puede obtener usando tauri_plugin_updater::target() que devuelve un Option<String> que es None cuando el actualizador no es compatible con la plataforma actual.

Nota

• Al usar un target personalizado podría ser más fácil usarlo exclusivamente para determinar la plataforma de actualización, por lo que podrías eliminar la variable {{arch}}.
• El valor proporcionado como target es la clave que se compara con la clave de plataforma al usar un archivo JSON estático.

Permitir downgrades

Por defecto, Tauri comprueba si la versión de la actualización es mayor que la versión actual de la app para verificar si debe actualizar o no. Para permitir downgrades, debes usar la API version_comparator del updater builder:

use tauri_plugin_updater::UpdaterExt;

let update = app
  .updater_builder()
  .version_comparator(|current, update| {
    // default comparison: `update.version > current`
    update.version != current
  })
  .build()?
  .check()
  .await?;

Hook de Windows antes de salir

Debido a una limitación de los instaladores de Windows, Tauri cerrará automáticamente tu aplicación antes de instalar actualizaciones en Windows. Para realizar una acción antes de que eso suceda, usa la función on_before_exit:

use tauri_plugin_updater::UpdaterExt;

let update = app
  .updater_builder()
  .on_before_exit(|| {
    println!("app is about to exit on Windows!");
  })
  .build()?
  .check()
  .await?;

Nota

Los valores de la configuración se usan como respaldo si alguno de los valores del builder no está establecido.

Permisos

De forma predeterminada, todos los comandos y alcances (scopes) potencialmente peligrosos del plugin están bloqueados y no se puede acceder a ellos. Debes modificar los permisos en tu configuración de capabilities para habilitarlos.

Consulta la Visión General de Capacidades para obtener más información y la guía paso a paso para usar permisos de plugins.

src-tauri/capabilities/default.json

{
  "permissions": [
    ...,
    "updater:default",
  ]
}

Permiso Predeterminado

Este conjunto de permisos configura qué tipo de funciones del actualizador se exponen al frontend.

Permisos Otorgados

El flujo de trabajo completo, desde comprobar las actualizaciones hasta instalarlas, está habilitado.

Este conjunto de permisos predeterminado incluye lo siguiente:

• allow-check
• allow-download
• allow-install
• allow-download-and-install

Tabla de Permisos

Identificador	Descripción
updater:allow-check	Habilita el comando check sin ningún ámbito preconfigurado.
updater:deny-check	Deniega el comando check sin ningún ámbito preconfigurado.
updater:allow-download	Habilita el comando download sin ningún ámbito preconfigurado.
updater:deny-download	Deniega el comando download sin ningún ámbito preconfigurado.
updater:allow-download-and-install	Habilita el comando download_and_install sin ningún ámbito preconfigurado.
updater:deny-download-and-install	Deniega el comando download_and_install sin ningún ámbito preconfigurado.
updater:allow-install	Habilita el comando install sin ningún ámbito preconfigurado.
updater:deny-install	Deniega el comando install sin ningún ámbito preconfigurado.