fix(runtime): file drop not working with @wailsio/runtime npm module by leaanthony · Pull Request #4953 · wailsapp/wails

leaanthony · 2026-02-03T19:41:41Z

Problem

When using the @wailsio/runtime npm module (instead of the bundled /wails/runtime.js), native file drag-and-drop on macOS/Linux fails with:

TypeError: undefined is not an object (evaluating 'window.wails.Window.HandlePlatformFileDrop')

Root Cause

The Go backend calls window.wails.Window.HandlePlatformFileDrop() for native file drops, but:

Runtime	`window.wails.Window.HandlePlatformFileDrop`	`window._wails.handlePlatformFileDrop`
Bundled (`/wails/runtime.js`)	✅ Exists	✅ Exists
NPM (`@wailsio/runtime`)	❌ Empty object	✅ Exists

The bundled runtime sets window.wails = Runtime, so both paths work. The npm module only exports via ES modules and registers the handler at the internal window._wails path.

Solution

Changed the Go code to call the internal path that both runtime distributions set up:

// Before (only worked with bundled runtime):
"window.wails.Window.HandlePlatformFileDrop(%s, %d, %d);"

// After (works with both):
"window._wails.handlePlatformFileDrop(%s, %d, %d);"

This is consistent with other drag handlers (handleDragEnter, handleDragLeave, handleDragOver) which already use the window._wails path.

Testing

Added v3/test/dnd-npm-runtime/ - a test case that uses the npm module to verify the fix works:

cd v3/test/dnd-npm-runtime/frontend
npm install
npm run build
cd ..
go run .

Notes

This fix works for both the bundled runtime AND the npm module
The existing drag-n-drop example continues to work unchanged
Reported via Discord by @lea (FYRA)

Summary by CodeRabbit

Bug Fixes
- Restored native drag-and-drop file handling when using the npm runtime by aligning the frontend runtime integration point for platform file drops.
Tests
- Added a self-contained DND test app with a styled external drop zone, live drop-result feedback, and file categorization (Images, Documents, Other) to validate runtime behavior.
Documentation
- Added a README describing how to run and verify the DND npm runtime test.

The Go backend was calling window.wails.Window.HandlePlatformFileDrop() for native file drops on macOS/Linux. This only worked with the bundled runtime which sets window.wails = Runtime. When using the @wailsio/runtime npm module, window.wails is an empty object because the npm module only exports via ES modules and registers the handler at window._wails.handlePlatformFileDrop. Changed the Go code to call the internal path that both runtime distributions set up: window._wails.handlePlatformFileDrop() Also added a test case that uses the npm module to verify the fix. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

github-actions · 2026-02-03T19:42:06Z

⚠️ Missing Changelog Update

Hi @leaanthony, please update v3/UNRELEASED_CHANGELOG.md with a description of your changes.

This helps us keep track of changes for the next release.

coderabbitai · 2026-02-03T19:42:31Z

Caution

Review failed

The pull request is closed.

Walkthrough

Changed the JS bridge call used by the Go backend for native file drops from window.wails.Window.HandlePlatformFileDrop(...) to window._wails.handlePlatformFileDrop(...). Added a DND npm-runtime test (frontend, Go app, docs, build files) to validate behavior with @wailsio/runtime.

Changes

Cohort / File(s)	Summary
Core runtime change `v3/pkg/application/webview_window.go`	Replaced JS bridge invocation to call `window._wails.handlePlatformFileDrop(...)` instead of `window.wails.Window.HandlePlatformFileDrop(...)`.
Test app (backend) `v3/test/dnd-npm-runtime/main.go`	New Wails v3 test app embedding frontend/dist, enabling native file-drop, listening for `WindowFilesDropped`, and emitting `files-dropped` events to the frontend.
Test frontend (UI & logic) `v3/test/dnd-npm-runtime/frontend/index.html`, `v3/test/dnd-npm-runtime/frontend/main.js`	Added standalone test UI and runtime JS using `@wailsio/runtime` to receive `files-dropped`, categorize files (images/docs/other), and display drop details.
Test frontend (build config) `v3/test/dnd-npm-runtime/frontend/package.json`, `v3/test/dnd-npm-runtime/frontend/vite.config.js`	New npm project config with `@wailsio/runtime` dependency and Vite build configuration for the frontend test.
Docs / changelog `v3/test/dnd-npm-runtime/README.md`, `v3/UNRELEASED_CHANGELOG.md`	Added README documenting the DND npm-runtime test and updated UNRELEASED changelog entry describing the native file drag-and-drop fix.
Module manifest `go.mod`	Single-line manifest update.

Sequence Diagram(s)

sequenceDiagram
  participant Go as Go backend
  participant Webview as WebView/Eval
  participant Runtime as window._wails
  participant Frontend as App frontend

  rect rgba(60,130,200,0.5)
    Go->>Webview: Eval JS -> call window._wails.handlePlatformFileDrop(filesJSON, x, y)
  end
  rect rgba(80,160,80,0.5)
    Webview->>Runtime: invoke handlePlatformFileDrop(...)
    Runtime->>Frontend: emit "files-dropped" (files + details)
    Frontend->>Frontend: categorize files and update UI
  end

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related PRs

fix: Move HandlePlatformFileDrop to window._wails internal API #4616: Makes the same code-level change — updates backend call-site to window._wails.handlePlatformFileDrop(...).
fix(runtime): file drop not working with @wailsio/runtime npm module #4953: Same change switching the runtime JS bridge and includes the dnd-npm-runtime test additions.
fix(v3): overhaul drag-and-drop for Linux reliability and simplify Windows implementation #4848: Related replacement of the runtime handler path to window._wails.

Suggested labels

Bug, Javascript, runtime, v3-alpha, size:L

Suggested reviewers

fbbdev

Poem

🐇 I hopped through code and nudged a name,
From wails.Window to _wails it came,
Files drop in, events take flight,
Frontend listens, UI alight,
A tiny hop — everything's the same (but better).

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and concisely summarizes the main fix: resolving file drop functionality with the npm runtime module.
Description check	✅ Passed	The PR description provides a thorough explanation including problem statement, root cause analysis, solution, testing instructions, and notes on compatibility.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing touches

🧪 Generate unit tests (beta)

Create PR with unit tests
Post copyable unit tests in a comment
Commit unit tests in branch fix/npm-runtime-dnd-handler

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Copilot

Pull request overview

This PR fixes native file drag-and-drop failures when apps use the @wailsio/runtime npm package (instead of the bundled /wails/runtime.js) by switching the backend’s JS invocation to the runtime hook that exists in both distributions.

Changes:

Updated the drop-processing JS call to use window._wails.handlePlatformFileDrop(...) instead of window.wails.Window.HandlePlatformFileDrop(...).
Added a new manual test app under v3/test/dnd-npm-runtime/ that bundles a small Vite frontend using @wailsio/runtime.
Documented how to build/run the new test case.

Reviewed changes

Copilot reviewed 8 out of 8 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
`v3/pkg/application/webview_window.go`	Switches the JS call used for native file drops to `window._wails.handlePlatformFileDrop` for compatibility with both runtime distributions.
`v3/test/dnd-npm-runtime/main.go`	New test harness app that enables file drop and forwards drop info to the frontend.
`v3/test/dnd-npm-runtime/README.md`	Instructions/background for reproducing and validating the fix using the npm runtime.
`v3/test/dnd-npm-runtime/frontend/package.json`	Frontend dependencies including `@wailsio/runtime` and Vite.
`v3/test/dnd-npm-runtime/frontend/vite.config.js`	Vite build output configuration (`dist`).
`v3/test/dnd-npm-runtime/frontend/index.html`	UI for the drop target and display buckets.
`v3/test/dnd-npm-runtime/frontend/main.js`	Uses `@wailsio/runtime` Events to display dropped files and drop target details.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

cloudflare-workers-and-pages · 2026-02-03T19:48:27Z

Deploying wails with Cloudflare Pages

Latest commit:	`597d850`
Status:	⚡️ Build in progress...

View logs

Required for go:embed to work in CI. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

sonarqubecloud · 2026-02-03T20:01:58Z

Quality Gate failed

Failed conditions
78.4% Duplication on New Code (required ≤ 3%)

See analysis details on SonarQube Cloud

github-actions · 2026-02-03T20:26:29Z

⚠️ Missing Changelog Update

Hi @leaanthony, please update v3/UNRELEASED_CHANGELOG.md with a description of your changes.

This helps us keep track of changes for the next release.

…ailsapp#4953) * fix(runtime): use internal path for HandlePlatformFileDrop The Go backend was calling window.wails.Window.HandlePlatformFileDrop() for native file drops on macOS/Linux. This only worked with the bundled runtime which sets window.wails = Runtime. When using the @wailsio/runtime npm module, window.wails is an empty object because the npm module only exports via ES modules and registers the handler at window._wails.handlePlatformFileDrop. Changed the Go code to call the internal path that both runtime distributions set up: window._wails.handlePlatformFileDrop() Also added a test case that uses the npm module to verify the fix. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> * docs: add changelog entry for npm runtime DND fix Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> * chore: add built frontend dist for dnd-npm-runtime test Required for go:embed to work in CI. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> * docs: update README to reflect pre-built frontend Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>

Copilot AI review requested due to automatic review settings February 3, 2026 19:41

Copilot started reviewing on behalf of leaanthony February 3, 2026 19:42 View session

docs: add changelog entry for npm runtime DND fix

d0f8005

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Copilot AI reviewed Feb 3, 2026

View reviewed changes

Comment thread v3/test/dnd-npm-runtime/main.go

leaanthony and others added 2 commits February 4, 2026 06:58

chore: add built frontend dist for dnd-npm-runtime test

0e97e1a

Required for go:embed to work in CI. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

docs: update README to reflect pre-built frontend

42fb8f7

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Merge branch 'v3-alpha' into fix/npm-runtime-dnd-handler

597d850

leaanthony merged commit c0d2c1e into v3-alpha Feb 3, 2026
4 of 7 checks passed

leaanthony deleted the fix/npm-runtime-dnd-handler branch February 3, 2026 20:25

coderabbitai Bot mentioned this pull request May 8, 2026

fix(v3,linux): enable frameless resize edge detection on Linux (#4680) #5366

Merged

6 tasks

coderabbitai Bot mentioned this pull request May 16, 2026

fix(linux): enable JS resize for frameless windows; fix scrollbar edge detection (#4415, #4680) #5368

Merged

5 tasks

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

fix(runtime): file drop not working with @wailsio/runtime npm module#4953

fix(runtime): file drop not working with @wailsio/runtime npm module#4953
leaanthony merged 5 commits into
v3-alphafrom
fix/npm-runtime-dnd-handler

leaanthony commented Feb 3, 2026 •

edited by coderabbitai Bot

Loading

Uh oh!

github-actions Bot commented Feb 3, 2026

Uh oh!

coderabbitai Bot commented Feb 3, 2026 •

edited

Loading

Review failed

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

cloudflare-workers-and-pages Bot commented Feb 3, 2026 •

edited

Loading

Uh oh!

sonarqubecloud Bot commented Feb 3, 2026

Uh oh!

Uh oh!

github-actions Bot commented Feb 3, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Conversation

leaanthony commented Feb 3, 2026 • edited by coderabbitai Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Problem

Root Cause

Solution

Testing

Notes

Summary by CodeRabbit

Uh oh!

github-actions Bot commented Feb 3, 2026

⚠️ Missing Changelog Update

Uh oh!

coderabbitai Bot commented Feb 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Review failed

Walkthrough

Changes

Sequence Diagram(s)

Estimated code review effort

Possibly related PRs

Suggested labels

Suggested reviewers

Poem

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

cloudflare-workers-and-pages Bot commented Feb 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Deploying wails with Cloudflare Pages

Uh oh!

sonarqubecloud Bot commented Feb 3, 2026

Quality Gate failed

Uh oh!

Uh oh!

github-actions Bot commented Feb 3, 2026

⚠️ Missing Changelog Update

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

leaanthony commented Feb 3, 2026 •

edited by coderabbitai Bot

Loading

coderabbitai Bot commented Feb 3, 2026 •

edited

Loading

cloudflare-workers-and-pages Bot commented Feb 3, 2026 •

edited

Loading