[v2] Fully built apps fail to run when frontend:dir is not default

[Nifty255]

Description

Problem

Applications built using wails build fail to start when frontend:dir is not the default value. Using wails dev works completely fine. It is highly likely that the frontend's built assets are not being embedded in the application since in this case they reside in an unexpected directory. Tested on Windows 10 but likely affects other platforms.

Proof

By inserting this code before the attempt to call wails.Run, one can check for the presence of frontend assets in a console window when built with -windowsconsole:

dir := "frontend/dist"
entries, _ := assets.ReadDir(dir)
log.Printf("Files in assets %q dir: %d", dir, len(entries))
time.Sleep(time.Second * 15) // Leaves the console open long enough to see the issue

Result with a fresh project: 2026/03/01 19:35:40 Files in assets "frontend/dist" dir: 2 (index.html and assets dir)

Result with a renamed frontend: 2026/03/01 19:37:02 Files in assets "frontend/dist" dir: 1 (gitkeep)

Recommended Fix

In v2/pkg/commands/build/build.go, immediately after the call to builder.BuildFrontend and its error check, while still inside that skip check if-block:

if options.ProjectData.GetFrontendDir() != "frontend" {
  if options.SkipEmbedCreate {
    // Warn that the frontend's build couldn't be copied as creating the target embed folder was skipped.
  } else {
    frontendDistDir := fmt.Sprintf("%s/dist", options.ProjectData.GetFrontendDir())
    // Copy frontendDistDir to "frontend/dist"
  }
}

After finishing the build, delete all files in frontend/dist except gitkeep.

To Reproduce

1. Inside a blank folder, create a simple Wails app using wails init -n client.
2. Verify the app runs both with wails dev and wails build. Both should work as expected.
3. Rename the frontend directory to jsfrontend.
4. Add "frontend:dir": "./jsfrontend", to wails.json.
5. Run using wails dev, which should work.
6. Build with wails build and attempt to run the executable. This should fail to open.
7. Move jsfrontend outside the client folder and rename to frontend.
8. Change frontend:dir to "../frontend".
9. Run using wails dev, which should work.
10. Build with wails build and attempt to run the executable. This should fail to open.

Expected behaviour

Where a Wails project's frontend:dir is not the default value, the application should successfully build and start.

Screenshots

No response

Attempted Fixes

This is an issue within Wails v2. There is no external fix, though one workaround exists in a specific set of circumstances.

Possible Workarounds

For frontends that remain inside the wails project's directory, the embed directive for the assets can be changed from //go:embed all:frontend/dist to //go:embed all:<frontend:dir value>/dist

There is, however, NO workaround for frontends which are outside of the Wails project's directory, as the go:embed directive does not allow paths that begin with ., .., or /.

System Details

> wails doctor


          Wails Doctor



# Wails
Version | v2.11.0


# System
┌──────────────────────────────────────────────────────────────────────────────────────────────┐
| OS           | Windows 10 Pro                                                                |
| Version      | 2009 (Build: 19045)                                                           |
| ID           | 22H2                                                                          |
| Branding     | Windows 10 Pro                                                                |
| Go Version   | go1.22.2                                                                      |
| Platform     | windows                                                                       |
| Architecture | amd64                                                                         |
| CPU          | AMD Ryzen 9 7950X3D 16-Core Processor                                         |
| GPU          | AMD Radeon RX 7900 XTX (Advanced Micro Devices, Inc.) - Driver: 32.0.21032.24 |
| Memory       | 64GB                                                                          |
└──────────────────────────────────────────────────────────────────────────────────────────────┘

# Dependencies
┌───────────────────────────────────────────────────────┐
| Dependency | Package Name | Status    | Version       |
| WebView2   | N/A          | Installed | 145.0.3800.82 |
| Nodejs     | N/A          | Installed | 24.12.0       |
| npm        | N/A          | Installed | 11.6.2        |
| *upx       | N/A          | Available |               |
| *nsis      | N/A          | Available |               |
|                                                       |
└─────────────── * - Optional Dependency ───────────────┘

# Diagnosis
Optional package(s) installation details:
  - upx : Available at https://upx.github.io/
  - nsis : More info at https://wails.io/docs/guides/windows-installer/

 SUCCESS  Your system is ready for Wails development!

 ♥   If Wails is useful to you or your company, please consider sponsoring the project:
https://github.com/sponsors/leaanthony

Additional context

No response

[Nifty255]

I have discovered after the fact, by perusing Wails' code, that the workaround I noted is basically intended. You're supposed to ensure the configured custom frontend directory matches the embed directive. However, the issue remains if the configured custom frontend directory resides outside the project directory.

[leaanthony]

A fix for this issue has been proposed in draft PR #5178. The PR adds a syncFrontendToEmbedTarget step after the frontend build that copies the built assets from the custom frontend:dir/dist to the embed target directory, ensuring the //go:embed directive can find them.

[leaanthony]

Triage notes:

• Classification: Bug (v2) — confirmed fully-built v2 apps fail to run when frontend:dir is configured to a non-default path.
• Labels applied: v2
• Platform: Likely cross-platform (build/config issue), no specific platform needed.
• Status: No existing PR or fix in flight. This is a v2-only issue; v3 uses a different build system (Taskfile). Consider whether this is still worth fixing on the v2 branch or should be marked as v2-only / documented as known limitation.