What Actually Happens When You Download an EPUB Built With ES6
An EPUB is just a ZIP file containing HTML, CSS, and metadata. The fact that modern JavaScript features like template literals, classes, arrow functions, or modules work inside an EPUB depends entirely on which ebook reader you use. That is the part most people get wrong before they even start building. When you write a book or technical guide using ES6 syntax, compile it, and package it as an EPUB, you are relying on the reading app's WebView to support the JavaScript version you used. Most Kindle apps strip JavaScript entirely. Kobo supports a fair amount of ES2015. Apple Books on iPad handles modern ES6 without complaint. This means your download file is only as good as the reader that opens it. I spent about three weeks debugging why an interactive data visualization chapter rendered as blank white space on a Kobo Clara 2E. The HTML was valid. The CSS checked out in every browser. The problem was that Kobo's built-in browser does not support the const declaration in certain nested script contexts the same way newer WebViews do. I ended up rewriting the visualization scripts in ES5 with var and function declarations, then tested against Kobo's specific WebView version before re-exporting. It added about four hours to the build pipeline but saved the whole interactive chapter.
The workflow itself is straightforward if you know the bottlenecks. You write content using any modern tool, export it as valid XHTML, run it through a linter, package it with EPUBCheck, and generate the final .epub file. EPUB 3 supports inline JavaScript, which is what makes ES6 possible. EPUB 2 does not, so you need to verify which version your target format requires before anything else. A counter-intuitive detail most tutorials skip: module syntax does not work in EPUBs at all. You cannot use import or export keywords and expect any reader to process them. Every script needs to live in a single file or be manually concatenated before packaging. I learned this after a build succeeded locally but produced a non-functional ebook on six different devices. The EPUB spec simply does not define an import mechanism for the ebook reading context. Another pitfall involves let and const in older Kobo firmware versions. The Kobo Glo HD, for example, runs firmware that partially supports these declarations but fails silently when block-scoped variables are used inside event handlers. The workaround is to use var for any variable that will be referenced inside a addEventListener callback or an inline onclick attribute. It is a small detail that takes twenty minutes to fix after it breaks instead of five minutes to prevent.
Practical Build Steps
Start by validating your HTML with the W3C markup validator. EPUBs are XHTML, so the rules are stricter than regular web pages. Self-closing tags must include the slash. All attributes need quotes. Image references must use relative paths. Getting this right upfront removes roughly half the errors you would otherwise spend time fixing later. After validation, run EPUBCheck, preferably version 5 or later, because it enforces the correct schema for EPUB 3. It will flag missing MIME types, broken OPF references, and invalid JS placement. A clean EPUBCheck pass does not guarantee the ebook will display correctly in every reader, but it guarantees the file is structurally sound. For the actual download and distribution, I package the EPUB alongside a simple README that lists the supported readers and any known limitations. Some readers fail to open files over a certain size due to RAM constraints on older hardware. A 400-page EPUB with embedded JavaScript typically stays around 15 to 25 megabytes. Anything larger risks timeout errors on budget e-readers.
Get the Full Details
If your content is purely text with minimal interactivity, consider whether an EPUB is the right format at all. A PDF or a hosted HTML page might serve the same audience faster and with fewer compatibility headaches. ES6 interactivity in EPUBs is genuinely useful for things like code examples that run inline or dynamic navigation, but it is fragile by design. The trade-off is real.
What Not to Expect
Do not assume your download link will produce a universal file. Amazon Kindle still does not support EPUB natively and converts files through their own proprietary pipeline, which often strips or breaks JavaScript entirely. If Kindle distribution matters to you, plan for a separate workflow using KindleGen or KDP's HTML upload, not the EPUB route. Similarly, Google Play Books has specific CSS and JS limitations that differ from Apple Books. Testing against one platform and assuming cross-compatibility is how most people end up with broken interactive sections after publishing. I usually run my final EPUB through both Apple Books preview and the Google Play Books Previewer before releasing anything. The whole process, from raw content to a validated downloadable EPUB, takes somewhere between two and six hours depending on how complex the JavaScript interactivity is and how many readers you test against. If you skip validation or testing to save time, you will spend that time back later fixing reader-specific rendering issues that EPUBCheck should have caught in the first place.
