MV3 Chrome Extensions: non-obvious issues I wish I knew before building one

If you've ever built a Chrome Extension with Manifest V3, you've probably hit at least one of these walls. I did. Multiple times. Here's what I learned the hard way. 1. Service workers don't persist state This is the biggest mindset shift from MV2. Any variable you declare in background.js is gone the moment Chrome decides to kill the service worker — and it will, unpredictably. The fix: never store anything in variables. Use chrome.storage for everything. // Wrong let userSettings = {}; // Right chrome . storage . local . set ({ userSettings }); 2. Async messaging silently fails without return true This one cost me hours of debugging. When you send a message from popup.js to background.js and expect an async response, you must return true inside the onMessage listener — otherwise Chrome closes the message channel before the response arrives. chrome . runtime . onMessage . addListener (( message , sender , sendResponse ) => { if ( message . type === ' RUN_ACTION ' ) { doSomethingAsync