How to avoid the angular white screen of death
If you ever worked with angular or ionic, you might experienced a complete white page aka the white screen of death. Most likely the reason is browser incompatibility due to missing polyfills or the browser isn’t supported at all. Therefore angular won’t boot correctly and the page remains empty.
If you want to try this out, just throw an error before bootstrapping in your main.ts file.
if (environment.production) {
enableProdMode();
}throw new Error('White screen, reveal yourself!');platformBrowserDynamic()
.bootstrapModule(AppModule)
.catch((err) => console.error(err));
This is a worst case scenario, as there are no error messages or any instructions shown. Many of your users might just leave. If a user looks up your email address, you might get the information that an error occurred, but won’t have any information (e.g. a stack trace) to start debugging it. For native apps this gets even worse, as you’ll receive one star ratings in the app stores and comments like “Not working”. And many of them just leave their review and won’t reply to your answers.
How can we fix this?
Spoiler Alert: I’m not aware of any magic solution that will fix these kind of errors for us. The problem is that angular isn’t working correctly and therefore its global error handler or any code inside angular won’t handle it. Also there are various reasons depending on browser versions, operating systems and then it comes to hybrid apps, webview and native specifics.
But what we can do, is at least show an error message and some instructions, like the following:
A solution
We extend the index.html of our Single-Page-Application with some CSS, HTML and VanillaJS to detect the white screen and display an error message.
Some notes on the JS
The javascript is pretty self-explanatory. We have a function showWhitescreenError that logs the error and displays the div-Element, if it’s not already shown (maybe multiple errors occur). The function also appends the error stack to our displayed message. The JS itself does not use any modern ES features, as we want it to work properly on all devices.
To detect the white screen, there are two kind of errors I’m aware of:
- Uncaught error
An uncaught error is thrown on app start. We handle this with a global Event-Listener and show the error message after a given time (e.g. 5 seconds). We wait a few seconds, because angular might still work and we don’t want a flashing error message. - Empty app-root
The app-root remains empty, but no error is thrown. We check if the app-root has any children after a given time (e.g. 8 seconds), and show an error message if not.
Some notes on the CSS
Of course you can modify the HTML and CSS of the error message regarding your needs. You should generally avoid very modern CSS, as you might deal with old browser versions. I suggest to set a negative z-index to display the message behind the app-root (in case the app works and the white screen fix starts falsely). Also start with `display: none`, to hide the message until an error occurs. Leaving the necessary CSS to these two lines:
.whitescreen {
display: none;
z-index: -1000;
}Room for improvements?
We could bring more functionality into the error handling, like adding some platform specific information (e.g. operating system, browser version) or event send a HttpRequest with an error report to our backend. But adding more code might also result in new errors and our main goal is to display something instead of an empty screen.
Final thoughts
Does this fix really help? I used this approach on an angular and an ionic project and it definitely got us some users that sent screenshots and asked for help. In case of the ionic app, we suggested to try our PWA instead of the AppStore-Version and this worked for all of them so far. Also, since fixing the white screen, we got no new “Not working”-reviews in the stores.
Thank you for reading. I’m exited to hear your thoughts. Feel free to comment, share your experiences or suggest any improvements.
