How to make your Tauri app the default for file associations using NSIS

Introduction

If you’re building a desktop app that handles specific file types, setting it as the default is a crucial step to streamline the user experience. I’m currently working on Electro, a blazingly fast image viewer built with Rust & Tauri v2.

Recently, I spent about an hour learning about NSIS and Windows installers to configure Electro as the default Windows image viewer. This guide condenses that hour of learning and experimentation into a quick read for anyone looking to set their Tauri app as the default for specific file types on Windows.

1. Create an NSIS installer hook

Create a new file in src-tauri/windows/hooks.nsi. This file will contain the NSIS installer hook macro(s) that will be executed during the installation process.

2. Register the NSIS installer hook with Tauri

Navigate to your tauri.conf.json file and add the following snippet to include your custom NSIS installer hook:

1
2
3
4
5
6
7
8
9
{
  "bundle": {
    "windows": {
      "nsis": {
        "installerHooks": "./windows/hooks.nsi"
      }
    }
  }
}

Here is an example of a Tauri config file with the Windows NSIS installer hook property: Tauri config example with Windows NSIS installer hook property

3. Configure the NSIS installer hook

FileAssociation.nsh

First, download the FileAssociation.nsh script from the NSIS website. This script contains the necessary functionality to easily register your app as the default for different file types.

https://nsis.sourceforge.io/FileAssociation.nsh

!include "FileAssociation.nsh"

Register your app as the default for a specific file type

Unfortunately it seems like Tauri v2 does not support the !include directive for local .nsh files. As a workaround, you can copy the contents of the FileAssociation.nsh script directly into your hooks.nsi file. I know it’s not pretty, but it works.

If you’re interested in learning more, I have raised a GitHub issue to explore better approaches for including local external .nsh and .nsi files in Tauri v2 projects.

Here is an example of how to register your app as the default for .png files:

!macro NSIS_HOOK_POSTINSTALL
  ${registerExtension} "$INSTDIR\electro.exe" ".png" "PNG_File"
!macroend

You can obtain the full hooks.nsi file at the bottom of this tutorial.

4. Build the Project

Run the Tauri build command: npm run tauri build

5. Testing the Installer

I found that using a virtual machine (VM) like Windows Sandbox to test the installer made rapid interation much easier. Copy the generated installer to the VM, run it, and double-click a file associated with your app to confirm that it launches as expected.

Full `hooks.nsi` file

/*
_____________________________________________________________________________
 
                       File Association
_____________________________________________________________________________
 
 Based on code taken from http://nsis.sourceforge.net/File_Association 
 
 Usage in script:
 1. !include "FileAssociation.nsh"
 2. [Section|Function]
      ${FileAssociationFunction} "Param1" "Param2" "..." $var
    [SectionEnd|FunctionEnd]
 
 FileAssociationFunction=[RegisterExtension|UnRegisterExtension]
 
_____________________________________________________________________________
 
 ${RegisterExtension} "[executable]" "[extension]" "[description]"
 
"[executable]"     ; executable which opens the file format
                   ;
"[extension]"      ; extension, which represents the file format to open
                   ;
"[description]"    ; description for the extension. This will be display in Windows Explorer.
                   ;
 
 
 ${UnRegisterExtension} "[extension]" "[description]"
 
"[extension]"      ; extension, which represents the file format to open
                   ;
"[description]"    ; description for the extension. This will be display in Windows Explorer.
                   ;
 
_____________________________________________________________________________
 
                         Macros
_____________________________________________________________________________
 
 Change log window verbosity (default: 3=no script)
 
 Example:
 !include "FileAssociation.nsh"
 !insertmacro RegisterExtension
 ${FileAssociation_VERBOSE} 4   # all verbosity
 !insertmacro UnRegisterExtension
 ${FileAssociation_VERBOSE} 3   # no script
*/
 
 
!ifndef FileAssociation_INCLUDED
!define FileAssociation_INCLUDED
 
!include Util.nsh
 
!verbose push
!verbose 3
!ifndef _FileAssociation_VERBOSE
  !define _FileAssociation_VERBOSE 3
!endif
!verbose ${_FileAssociation_VERBOSE}
!define FileAssociation_VERBOSE `!insertmacro FileAssociation_VERBOSE`
!verbose pop
 
!macro FileAssociation_VERBOSE _VERBOSE
  !verbose push
  !verbose 3
  !undef _FileAssociation_VERBOSE
  !define _FileAssociation_VERBOSE ${_VERBOSE}
  !verbose pop
!macroend
 
 
 
!macro RegisterExtensionCall _EXECUTABLE _EXTENSION _DESCRIPTION
  !verbose push
  !verbose ${_FileAssociation_VERBOSE}
  Push `${_DESCRIPTION}`
  Push `${_EXTENSION}`
  Push `${_EXECUTABLE}`
  ${CallArtificialFunction} RegisterExtension_
  !verbose pop
!macroend
 
!macro UnRegisterExtensionCall _EXTENSION _DESCRIPTION
  !verbose push
  !verbose ${_FileAssociation_VERBOSE}
  Push `${_EXTENSION}`
  Push `${_DESCRIPTION}`
  ${CallArtificialFunction} UnRegisterExtension_
  !verbose pop
!macroend
 
 
 
!define RegisterExtension `!insertmacro RegisterExtensionCall`
!define un.RegisterExtension `!insertmacro RegisterExtensionCall`
 
!macro RegisterExtension
!macroend
 
!macro un.RegisterExtension
!macroend
 
!macro RegisterExtension_
  !verbose push
  !verbose ${_FileAssociation_VERBOSE}
 
  Exch $R2 ;exe
  Exch
  Exch $R1 ;ext
  Exch
  Exch 2
  Exch $R0 ;desc
  Exch 2
  Push $0
  Push $1
 
  ReadRegStr $1 HKCR $R1 ""  ; read current file association
  StrCmp "$1" "" NoBackup  ; is it empty
  StrCmp "$1" "$R0" NoBackup  ; is it our own
    WriteRegStr HKCR $R1 "backup_val" "$1"  ; backup current value
NoBackup:
  WriteRegStr HKCR $R1 "" "$R0"  ; set our file association
 
  ReadRegStr $0 HKCR $R0 ""
  StrCmp $0 "" 0 Skip
    WriteRegStr HKCR "$R0" "" "$R0"
    WriteRegStr HKCR "$R0\shell" "" "open"
    WriteRegStr HKCR "$R0\DefaultIcon" "" "$R2,0"
Skip:
  WriteRegStr HKCR "$R0\shell\open\command" "" '"$R2" "%1"'
  WriteRegStr HKCR "$R0\shell\edit" "" "Edit $R0"
  WriteRegStr HKCR "$R0\shell\edit\command" "" '"$R2" "%1"'
 
  Pop $1
  Pop $0
  Pop $R2
  Pop $R1
  Pop $R0
 
  !verbose pop
!macroend
 
 
 
!define UnRegisterExtension `!insertmacro UnRegisterExtensionCall`
!define un.UnRegisterExtension `!insertmacro UnRegisterExtensionCall`
 
!macro UnRegisterExtension
!macroend
 
!macro un.UnRegisterExtension
!macroend
 
!macro UnRegisterExtension_
  !verbose push
  !verbose ${_FileAssociation_VERBOSE}
 
  Exch $R1 ;desc
  Exch
  Exch $R0 ;ext
  Exch
  Push $0
  Push $1
 
  ReadRegStr $1 HKCR $R0 ""
  StrCmp $1 $R1 0 NoOwn ; only do this if we own it
  ReadRegStr $1 HKCR $R0 "backup_val"
  StrCmp $1 "" 0 Restore ; if backup="" then delete the whole key
  DeleteRegKey HKCR $R0
  Goto NoOwn
 
Restore:
  WriteRegStr HKCR $R0 "" $1
  DeleteRegValue HKCR $R0 "backup_val"
  DeleteRegKey HKCR $R1 ;Delete key with association name settings
 
NoOwn:
 
  Pop $1
  Pop $0
  Pop $R1
  Pop $R0
 
  !verbose pop
!macroend
 
!endif # !FileAssociation_INCLUDED

!macro NSIS_HOOK_POSTINSTALL
  ${registerExtension} "$INSTDIR\electro.exe" ".png" "PNG_File"
!macroend

Introduction#

1. Create an NSIS installer hook#

2. Register the NSIS installer hook with Tauri#

3. Configure the NSIS installer hook#

FileAssociation.nsh#

Register your app as the default for a specific file type#

4. Build the Project#

5. Testing the Installer#

Full hooks.nsi file#