feat: Add bundleHTML option for HTML file handling

[pa001024]

#54

Summary by CodeRabbit

• New Features

  • Added a public option to toggle HTML bundling (default: enabled) to control whether HTML is loaded as bundled modules or served directly.

• Bug Fixes

  • More resilient HTML loading: errors are logged (unless silenced) and processing continues to avoid blocking routes.
  • Consistent bundling behavior applied across environments, including index HTML handling.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[coderabbitai]

Walkthrough

Adds a new bundleHTML option (default: true) to staticPlugin and StaticOptions, and updates HTML-serving to choose between bundled imports or direct file reads based on bundleHTML, with try/catch logging and a unified htmlFile variable used across routes.

Changes

Cohort / File(s)	Summary
API surface src/types.ts	Added optional bundleHTML?: boolean to StaticOptions<Prefix> (JSDoc documents default true and notes "Enable bundling of HTML files (Bun only)").
Plugin implementation src/index.ts	Accepted bundleHTML in staticPlugin options (default true). For Bun and non-Bun HTML handling, conditionally load HTML via bundled import(...).default when bundleHTML is true or via getFile when false. Wrapped HTML loading in try/catch to log failures (unless silent), and replaced direct htmlBundle.default usage with a shared htmlFile variable across HTML-serving and index routes.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

• Review src/index.ts logic where bundleHTML is destructured and defaulted.
• Verify Bun vs non-Bun branches both respect bundleHTML and that getFile fallback is correct.
• Inspect the new try/catch for appropriate logging and non-swallowing of critical errors.
• Confirm htmlFile is used consistently for all HTML response paths and encoding/headers remain correct.

Poem

🐰 I hop through code with ears alert and bright,
Import or read — I pick what feels right,
Try a nibble, catch a tumble, then smile,
HTML bundled or served from the file,
Little rabbit patches things with delight. 🥕

Pre-merge checks and finishing touches

❌ 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%.	You can run @coderabbitai generate docstrings to improve docstring coverage.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately describes the main change: adding a new bundleHTML option for controlling HTML file handling in the static plugin.

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment

---

📜 Recent review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between b986176 and 6ce9d54.

📒 Files selected for processing (1)

• src/types.ts (1 hunks)

🚧 Files skipped from review as they are similar to previous changes (1)

• src/types.ts

---

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

• X
• Mastodon
• Reddit
• LinkedIn

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

[coderabbitai]

Actionable comments posted: 1

♻️ Duplicate comments (1)

src/index.ts (1)

229-246: Same type safety and error handling concerns apply here.

This code segment has the same issues identified in lines 90-100:

1. Missing explicit type annotation for htmlFile
2. No error handling around the dynamic import at line 237
3. Needs verification that HTML module imports work as expected

Apply similar error handling:

             for (const absolutePath of htmls) {
                 if (!absolutePath || shouldIgnore(absolutePath)) continue
 
                 let relativePath = absolutePath.replace(assetsDir, '')
                 const pathName = normalizePath(path.join(prefix, relativePath))
-                const htmlFile = bundleHTML ? (await import(absolutePath)).default : getFile(absolutePath)
+                let htmlFile
+                try {
+                    htmlFile = bundleHTML ? (await import(absolutePath)).default : getFile(absolutePath)
+                } catch (error) {
+                    if (!silent)
+                        console.error(
+                            `[@elysiajs/static] Failed to load HTML file: ${absolutePath}`,
+                            error
+                        )
+                    continue
+                }
 
                 app.get(pathName, htmlFile)

🧹 Nitpick comments (1)

src/types.ts (1)

104-109: Clarify the JSDoc description for better developer understanding.

The description "Enable bun bundle of *.html" is brief and doesn't explain what bundling means or its implications. Consider expanding it to clarify:

• That this option only applies when running on Bun
• What "bundling" means (importing HTML as modules vs serving directly from disk)
• Performance implications (bundled at startup vs read on demand)

Example improvement:

 /**
  * @default true
  *
- * Enable bun bundle of *.html
+ * Enable bundling of HTML files (Bun only).
+ * When true, HTML files are imported as modules at startup for better performance.
+ * When false, HTML files are served directly from disk.
  */
 bundleHTML?: boolean

📜 Review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 4d12f68 and ae774e2.

📒 Files selected for processing (2)

• src/index.ts (3 hunks)
• src/types.ts (1 hunks)

🧰 Additional context used

🧬 Code graph analysis (1)

src/index.ts (1)

src/utils.ts (1)

• getFile (194-199)

🔇 Additional comments (1)

src/index.ts (1)

33-33: LGTM!

The default value of true maintains backward compatibility while allowing users to opt into direct file serving when needed.