Your First Application

Creating your first application with Wails v3 is an exciting journey into the world of modern desktop app development. This guide will walk you through the process of creating a basic application, showcasing the power and simplicity of Wails.

1. Creating a New Project

   Open your terminal and run the following command to create a new Wails project:

   wails3 init -n myfirstapp

   This command creates a new directory called myfirstapp with all the necessary files.

2. Exploring the Project Structure

   Navigate to the myfirstapp directory. You’ll find several files and folders:

   • Directorybuild/ Contains files used by the build process

     • appicon.png The application icon
     • config.yml Build configuration
     • Taskfile.yml Build tasks
     • Directorydarwin/ macOS specific build files

       • Info.dev.plist Development configuration
       • Info.plist Production configuration
       • Taskfile.yml macOS build tasks
       • icons.icns macOS application icon
     • Directorylinux/ Linux specific build files

       • Taskfile.yml Linux build tasks
       • Directoryappimage/ AppImage packaging

         • build.sh AppImage build script
       • Directorynfpm/ NFPM packaging

         • nfpm.yaml Package configuration
         • Directoryscripts/ Build scripts

           • …
     • Directorywindows/ Windows specific build files

       • Taskfile.yml Windows build tasks
       • icon.ico Windows application icon
       • info.json Application metadata
       • wails.exe.manifest Windows manifest file
       • Directorynsis/ NSIS installer files

         • project.nsi NSIS project file
         • wails_tools.nsh NSIS helper scripts
   • Directoryfrontend/ Frontend application files

     • index.html Main HTML file
     • main.js Main JavaScript file
     • package.json NPM package configuration
     • Directorypublic/ Static assets

       • …
     • Inter Font License.txt Font license
   • .gitignore Git ignore file
   • README.md Project documentation
   • Taskfile.yml Project tasks
   • go.mod Go module file
   • go.sum Go module checksums
   • greetservice.go Greeting service
   • main.go Main application code

   Take a moment to explore these files and familiarize yourself with the structure.

   Note

   Although Wails v3 uses Task as its default build system, there is nothing stopping you from using make or any other alternative build system.

3. Building Your Application

   To build your application, execute:

   wails3 build

   This command compiles a debug version of your application and saves it in a new bin directory.

   Note

   wails3 build is shorthand for wails3 task build and will run the build task in Taskfile.yml.

   Once built, you can run this like you would any normal application:

   Mac

   ./bin/myfirstapp

   Windows

   bin\myfirstapp.exe

   Linux

   ./bin/myfirstapp

   You’ll see a simple UI, the starting point for your application. As it is the debug version, you’ll also see logs in the console window. This is useful for debugging purposes.

4. Dev Mode

   We can also run the application in development mode. This mode allows you to make changes to your frontend code and see the changes reflected in the running application without having to rebuild the entire application.

   1. Open a new terminal window.
   2. Run wails3 dev. The application will compile and run in debug mode.
   3. Open frontend/index.html in your editor of choice.
   4. Edit the code and change Please enter your name below to Please enter your name below!!!.
   5. Save the file.

   This change will reflect in your application immediately.

   Any changes to backend code will trigger a rebuild:

   1. Open greetservice.go.
   2. Change the line that has return "Hello " + name + "!" to return "Hello there " + name + "!".
   3. Save the file.

   The application will update within a matter of seconds.

5. Packaging Your Application

   Once your application is ready for distribution, you can create platform-specific packages:

   Mac

   To create a .app bundle:

   wails3 package

   This will create a production build and package it into a .app bundle in the bin directory.

   Windows

   To create an NSIS installer:

   wails3 package

   This will create a production build and package it into an NSIS installer in the bin directory.

   Linux

   Wails supports multiple package formats for Linux distribution:

   # Create all package types (AppImage, deb, rpm, and Arch Linux)
   wails3 package
   
   # Or create specific package types
   wails3 task linux:create:appimage  # AppImage format
   wails3 task linux:create:deb       # Debian package
   wails3 task linux:create:rpm       # Red Hat package
   wails3 task linux:create:aur       # Arch Linux package

   For more detailed information about packaging options and configuration, check out our Packaging Guide.

6. Setting up Version Control and Module Name

   Your project is created with the placeholder module name changeme. It’s recommended to update this to match your repository URL:

   1. Create a new repository on GitHub (or your preferred Git host)
   2. Initialize git in your project directory:

      git init
      git add .
      git commit -m "Initial commit"

   3. Set your remote repository (replace with your repository URL):

      git remote add origin https://github.com/username/myfirstapp.git

   4. Update your module name in go.mod to match your repository URL:

      go mod edit -module github.com/username/myfirstapp

   5. Push your code:

      git push -u origin main

   This ensures your Go module name aligns with Go’s module naming conventions and makes it easier to share your code.

   Pro Tip

   You can automate all of the initialisation steps by using the -git flag when creating your project:

   wails3 init -n myfirstapp -git github.com/username/myfirstapp

   This supports various Git URL formats:

   • HTTPS: https://github.com/username/project
   • SSH: [email protected]:username/project or ssh://[email protected]/username/project
   • Git protocol: git://github.com/username/project
   • Filesystem: file:///path/to/project.git

Congratulations!

You’ve just created, developed and packaged your first Wails application. This is just the beginning of what you can achieve with Wails v3.

Next Steps

If you are new to Wails, we recommend reading through our Tutorials next which will be a practical guide through the various features of Wails. The first tutorial is Creating a Service.

If you are a more advanced user, check out our Guides for more detailed information on how to use Wails.