# Background-Capable VFS Listener APIs

**URL:** https://platform.jetbrains.com/t/background-capable-vfs-listener-apis/3900
**Category:** Announcements
**Created:** [March 19, 2026, 12:37pm UTC](https://platform.jetbrains.com/t/background-capable-vfs-listener-apis/3900 "2026-03-19T12:37:27Z")
**Posts on this page:** 1
**Page:** 1

<div class="post-metadata">

### Author: ![patrick.scheibe](https://sea1.discourse-cdn.com/flex001/user_avatar/platform.jetbrains.com/patrick.scheibe/32/2594_2.png) [@patrick.scheibe](https://platform.jetbrains.com/u/patrick.scheibe)
#### Post date: [March 19, 2026, 12:37pm UTC](https://platform.jetbrains.com/t/background-capable-vfs-listener-apis/3900/1 "2026-03-19T12:37:27Z")

</div>

**TL;DR:** Watch a 2 min video explanation:

[![](https://us1.discourse-cdn.com/flex001/uploads/jetbrains_platform/original/2X/4/408226bacfd23287a6c6c845cf0da3831d5aca26.jpeg "IntelliJ Platform VFS: Background-Capable Listener APIs for Plugin Authors #JetBrains #plugins") ](https://www.youtube.com/watch?v=4EfWxdn7s7A)

* * *

The IntelliJ Platform now offers background-capable variants for Virtual File System listener APIs. If your plugin watches many file events, these new hooks can help reduce UI freezes during heavy file operations.

## What Existed Before

### Classic bulk listeners

The traditional path used [`BulkFileListener`](https://github.com/JetBrains/intellij-community/blob/a103d3aca45b29d24ff837de181c6ce8b7f682a5/platform/core-api/src/com/intellij/openapi/vfs/newvfs/BulkFileListener.java#L10-L41) subscribed to [`VirtualFileManager.VFS_CHANGES`](https://github.com/JetBrains/intellij-community/blob/a103d3aca45b29d24ff837de181c6ce8b7f682a5/platform/core-api/src/com/intellij/openapi/vfs/VirtualFileManager.java#L32-L37). Callbacks ran on the EDT inside a write-action, causing UI stalls during heavy file operations.

### Old async listeners

[`AsyncFileListener`](https://github.com/JetBrains/intellij-community/blob/a103d3aca45b29d24ff837de181c6ce8b7f682a5/platform/core-api/src/com/intellij/openapi/vfs/AsyncFileListener.java#L14-L106) already split work into [`prepareChange(...)`](https://github.com/JetBrains/intellij-community/blob/a103d3aca45b29d24ff837de181c6ce8b7f682a5/platform/core-api/src/com/intellij/openapi/vfs/AsyncFileListener.java#L53-L72) (precompute) and appliers ([`beforeVfsChange()`](https://github.com/JetBrains/intellij-community/blob/a103d3aca45b29d24ff837de181c6ce8b7f682a5/platform/core-api/src/com/intellij/openapi/vfs/AsyncFileListener.java#L75-L86) / [`afterVfsChange()`](https://github.com/JetBrains/intellij-community/blob/a103d3aca45b29d24ff837de181c6ce8b7f682a5/platform/core-api/src/com/intellij/openapi/vfs/AsyncFileListener.java#L88-L104)). However, old registration via [`addAsyncFileListener(...)`](https://github.com/JetBrains/intellij-community/blob/a103d3aca45b29d24ff837de181c6ce8b7f682a5/platform/core-api/src/com/intellij/openapi/vfs/VirtualFileManager.java#L205-L210) or extension point [`com.intellij.vfs.asyncListener`](https://github.com/JetBrains/intellij-community/blob/a103d3aca45b29d24ff837de181c6ce8b7f682a5/platform/core-api/resources/META-INF/Core.xml#L11) had EDT-oriented applier execution.

## What’s New

Four new API components are now available:

- [`BulkFileListenerBackgroundable`](https://github.com/JetBrains/intellij-community/blob/a103d3aca45b29d24ff837de181c6ce8b7f682a5/platform/core-api/src/com/intellij/openapi/vfs/newvfs/BulkFileListenerBackgroundable.kt#L6-L28) marker interface (experimental)
- [`VirtualFileManager.VFS_CHANGES_BG`](https://github.com/JetBrains/intellij-community/blob/a103d3aca45b29d24ff837de181c6ce8b7f682a5/platform/core-api/src/com/intellij/openapi/vfs/VirtualFileManager.java#L38-L41) message topic
- [`addAsyncFileListenerBackgroundable(...)`](https://github.com/JetBrains/intellij-community/blob/a103d3aca45b29d24ff837de181c6ce8b7f682a5/platform/core-api/src/com/intellij/openapi/vfs/VirtualFileManager.java#L212-L217) method
- [`com.intellij.vfs.asyncListenerBackgroundable`](https://github.com/JetBrains/intellij-community/blob/a103d3aca45b29d24ff837de181c6ce8b7f682a5/platform/core-api/resources/META-INF/Core.xml#L12) extension point

### Old vs. New

**Bulk listeners:**

- Old: `BulkFileListener` on `VFS_CHANGES` — EDT-oriented dispatch, write-action semantics
- New: `BulkFileListenerBackgroundable` on `VFS_CHANGES_BG` — same write-action semantics, but thread may be background

**Async listeners:**

- Old: `addAsyncFileListener(...)` / `com.intellij.vfs.asyncListener` — EDT-oriented applier handling
- New: `addAsyncFileListenerBackgroundable(...)` / `com.intellij.vfs.asyncListenerBackgroundable` — background-capable applier execution

The key semantic shift: callbacks still happen under write-action constraints, but the thread is no longer guaranteed to be EDT.

## Why It Matters

Heavy file-event analysis can now avoid EDT-oriented listener paths. This reduces UI pressure during indexing, refresh, and large branch switches.

## Migration Considerations

If you consider migrating existing VFS listeners:

- Audit registrations on [`VirtualFileManager.VFS_CHANGES`](https://github.com/JetBrains/intellij-community/blob/a103d3aca45b29d24ff837de181c6ce8b7f682a5/platform/core-api/src/com/intellij/openapi/vfs/VirtualFileManager.java#L32-L37), [`addAsyncFileListener(...)`](https://github.com/JetBrains/intellij-community/blob/a103d3aca45b29d24ff837de181c6ce8b7f682a5/platform/core-api/src/com/intellij/openapi/vfs/VirtualFileManager.java#L205-L210), and [`com.intellij.vfs.asyncListener`](https://github.com/JetBrains/intellij-community/blob/a103d3aca45b29d24ff837de181c6ce8b7f682a5/platform/core-api/resources/META-INF/Core.xml#L11)
- Move only listeners that are thread-safe and don’t depend on UI thread access
- Remove direct UI calls and guard shared mutable state
- Keep [`prepareChange(...)`](https://github.com/JetBrains/intellij-community/blob/a103d3aca45b29d24ff837de181c6ce8b7f682a5/platform/core-api/src/com/intellij/openapi/vfs/AsyncFileListener.java#L53-L72) cancellable and side-effect free

## Important Caveats

These APIs are experimental and may change. Older IDE baselines may not have them at all. Plugins targeting multiple IDE versions will need compatibility strategies, either separate builds by baseline or runtime feature detection with fallback to legacy registration.

For implementation details, see the [source code](https://github.com/JetBrains/intellij-community/tree/master/platform/core-api/src/com/intellij/openapi/vfs) in `platform/core-api/src/com/intellij/openapi/vfs/`.