Automatically prepend <!DOCTYPE html> in res.html() helper

mjackson · mjackson · commit e4f41c48fcdf · 2025-11-18T22:31:13.000-05:00
diff --git a/packages/fetch-router/CHANGELOG.md b/packages/fetch-router/CHANGELOG.md
@@ -2,6 +2,10 @@
 
 This is the changelog for [`fetch-router`](https://github.com/remix-run/remix/tree/main/packages/fetch-router). It follows [semantic versioning](https://semver.org/).
 
+## Unreleased
+
+- `html()` response helper now automatically prepends `<!DOCTYPE html>` to the body if it is not already present
+
 ## v0.9.0 (2025-11-18)
 
 - Add `session` middleware for automatic management of `context.session` across requests
diff --git a/packages/fetch-router/src/lib/response-helpers/html.test.ts b/packages/fetch-router/src/lib/response-helpers/html.test.ts
@@ -8,36 +8,172 @@ describe('html()', () => {
   it('creates a Response with HTML content-type header', async () => {
     let response = html('<h1>Hello</h1>')
     assert.equal(response.headers.get('Content-Type'), 'text/html; charset=UTF-8')
-    assert.equal(await response.text(), '<h1>Hello</h1>')
+    assert.equal(await response.text(), '<!DOCTYPE html><h1>Hello</h1>')
   })
 
   it('preserves custom headers and status from init', async () => {
     let response = html('<h1>Hello</h1>', { headers: { 'X-Custom': 'a' }, status: 201 })
     assert.equal(response.headers.get('Content-Type'), 'text/html; charset=UTF-8')
     assert.equal(response.headers.get('X-Custom'), 'a')
     assert.equal(response.status, 201)
+    assert.equal(await response.text(), '<!DOCTYPE html><h1>Hello</h1>')
   })
 
   it('allows overriding Content-Type header', async () => {
     let response = html('<h1>Hello</h1>', { headers: { 'Content-Type': 'text/plain' } })
     assert.equal(response.headers.get('Content-Type'), 'text/plain')
   })
 
-  it('handles ReadableStream body without modification', async () => {
-    let stream = new ReadableStream({
-      start(controller) {
-        controller.enqueue(new TextEncoder().encode('<h1>Stream</h1>'))
-        controller.close()
-      },
-    })
-    let response = html(stream)
-    assert.equal(response.headers.get('Content-Type'), 'text/html; charset=UTF-8')
-    assert.equal(await response.text(), '<h1>Stream</h1>')
-  })
-
   it('accepts SafeHtml from escape tag without re-escaping', async () => {
     let snippet = safeHtml`<strong>${'Hi'}</strong>`
     let response = html(snippet)
-    assert.equal(await response.text(), '<strong>Hi</strong>')
+    assert.equal(await response.text(), '<!DOCTYPE html><strong>Hi</strong>')
+  })
+
+  describe('DOCTYPE prepending', () => {
+    describe('string body', () => {
+      it('prepends DOCTYPE to string body', async () => {
+        let response = html('<html><body>Hello</body></html>')
+        assert.equal(await response.text(), '<!DOCTYPE html><html><body>Hello</body></html>')
+      })
+
+      it('does not prepend DOCTYPE if already present', async () => {
+        let response = html('<!DOCTYPE html><html><body>Hello</body></html>')
+        assert.equal(await response.text(), '<!DOCTYPE html><html><body>Hello</body></html>')
+      })
+
+      it('handles DOCTYPE with leading whitespace', async () => {
+        let response = html('  <!DOCTYPE html><html><body>Hello</body></html>')
+        assert.equal(await response.text(), '  <!DOCTYPE html><html><body>Hello</body></html>')
+      })
+
+      it('handles DOCTYPE case-insensitively', async () => {
+        let response = html('<!doctype html><html><body>Hello</body></html>')
+        assert.equal(await response.text(), '<!doctype html><html><body>Hello</body></html>')
+      })
+    })
+
+    describe('SafeHtml body', () => {
+      it('prepends DOCTYPE to SafeHtml body', async () => {
+        let snippet = safeHtml`<html><body>Hello</body></html>`
+        let response = html(snippet)
+        assert.equal(await response.text(), '<!DOCTYPE html><html><body>Hello</body></html>')
+      })
+
+      it('does not prepend DOCTYPE if already present in SafeHtml', async () => {
+        let snippet = safeHtml`<!DOCTYPE html><html><body>Hello</body></html>`
+        let response = html(snippet)
+        assert.equal(await response.text(), '<!DOCTYPE html><html><body>Hello</body></html>')
+      })
+    })
+
+    describe('Blob body', () => {
+      it('prepends DOCTYPE to Blob body', async () => {
+        let blob = new Blob(['<html><body>Hello</body></html>'], { type: 'text/html' })
+        let response = html(blob)
+        assert.equal(await response.text(), '<!DOCTYPE html><html><body>Hello</body></html>')
+      })
+
+      it('does not prepend DOCTYPE if already present in Blob', async () => {
+        let blob = new Blob(['<!DOCTYPE html><html><body>Hello</body></html>'], {
+          type: 'text/html',
+        })
+        let response = html(blob)
+        assert.equal(await response.text(), '<!DOCTYPE html><html><body>Hello</body></html>')
+      })
+    })
+
+    describe('ArrayBuffer body', () => {
+      it('prepends DOCTYPE to ArrayBuffer body', async () => {
+        let buffer = new TextEncoder().encode('<html><body>Hello</body></html>')
+        let response = html(buffer.buffer)
+        assert.equal(await response.text(), '<!DOCTYPE html><html><body>Hello</body></html>')
+      })
+
+      it('does not prepend DOCTYPE if already present in ArrayBuffer', async () => {
+        let buffer = new TextEncoder().encode('<!DOCTYPE html><html><body>Hello</body></html>')
+        let response = html(buffer.buffer)
+        assert.equal(await response.text(), '<!DOCTYPE html><html><body>Hello</body></html>')
+      })
+    })
+
+    describe('Uint8Array body', () => {
+      it('prepends DOCTYPE to Uint8Array body', async () => {
+        let buffer = new TextEncoder().encode('<html><body>Hello</body></html>')
+        let response = html(buffer)
+        assert.equal(await response.text(), '<!DOCTYPE html><html><body>Hello</body></html>')
+      })
+
+      it('does not prepend DOCTYPE if already present in Uint8Array', async () => {
+        let buffer = new TextEncoder().encode('<!DOCTYPE html><html><body>Hello</body></html>')
+        let response = html(buffer)
+        assert.equal(await response.text(), '<!DOCTYPE html><html><body>Hello</body></html>')
+      })
+    })
+
+    describe('DataView body', () => {
+      it('prepends DOCTYPE to DataView body', async () => {
+        let buffer = new TextEncoder().encode('<html><body>Hello</body></html>')
+        let dataView = new DataView(buffer.buffer)
+        let response = html(dataView)
+        assert.equal(await response.text(), '<!DOCTYPE html><html><body>Hello</body></html>')
+      })
+
+      it('does not prepend DOCTYPE if already present in DataView', async () => {
+        let buffer = new TextEncoder().encode('<!DOCTYPE html><html><body>Hello</body></html>')
+        let dataView = new DataView(buffer.buffer)
+        let response = html(dataView)
+        assert.equal(await response.text(), '<!DOCTYPE html><html><body>Hello</body></html>')
+      })
+    })
+
+    describe('ReadableStream body', () => {
+      it('prepends DOCTYPE to ReadableStream body', async () => {
+        let stream = new ReadableStream({
+          start(controller) {
+            controller.enqueue(new TextEncoder().encode('<html><body>Hello</body></html>'))
+            controller.close()
+          },
+        })
+        let response = html(stream)
+        assert.equal(await response.text(), '<!DOCTYPE html><html><body>Hello</body></html>')
+      })
+
+      it('does not prepend DOCTYPE if already present in ReadableStream', async () => {
+        let stream = new ReadableStream({
+          start(controller) {
+            controller.enqueue(
+              new TextEncoder().encode('<!DOCTYPE html><html><body>Hello</body></html>'),
+            )
+            controller.close()
+          },
+        })
+        let response = html(stream)
+        assert.equal(await response.text(), '<!DOCTYPE html><html><body>Hello</body></html>')
+      })
+
+      it('handles empty ReadableStream', async () => {
+        let stream = new ReadableStream({
+          start(controller) {
+            controller.close()
+          },
+        })
+        let response = html(stream)
+        assert.equal(await response.text(), '<!DOCTYPE html>')
+      })
+
+      it('handles multi-chunk ReadableStream', async () => {
+        let stream = new ReadableStream({
+          start(controller) {
+            controller.enqueue(new TextEncoder().encode('<html>'))
+            controller.enqueue(new TextEncoder().encode('<body>'))
+            controller.enqueue(new TextEncoder().encode('Hello</body></html>'))
+            controller.close()
+          },
+        })
+        let response = html(stream)
+        assert.equal(await response.text(), '<!DOCTYPE html><html><body>Hello</body></html>')
+      })
+    })
   })
 })
diff --git a/packages/fetch-router/src/lib/response-helpers/html.ts b/packages/fetch-router/src/lib/response-helpers/html.ts
@@ -1,19 +1,19 @@
 import { isSafeHtml, type SafeHtml } from '@remix-run/html-template'
 
+const DOCTYPE = '<!DOCTYPE html>'
+
+type HtmlBody = string | SafeHtml | Blob | BufferSource | ReadableStream<Uint8Array>
+
 /**
- * A helper for working with HTML [`Response`](https://developer.mozilla.org/en-US/docs/Web/API/Response)s.
+ * A helper for working with HTML [`Response`](https://developer.mozilla.org/en-US/docs/Web/API/Response)s
+ * that ensures the response has a valid DOCTYPE and appropriate `Content-Type` header.
  *
  * @param body The body of the response.
  * @param init (optional) The `ResponseInit` object for the response.
  * @returns A `Response` object with a HTML body and the appropriate `Content-Type` header.
  */
-export function html(body: BodyInit | SafeHtml, init?: ResponseInit): Response {
-  let payload: BodyInit
-  if (isSafeHtml(body)) {
-    payload = String(body)
-  } else {
-    payload = body
-  }
+export function html(body: HtmlBody, init?: ResponseInit): Response {
+  let payload: BodyInit = ensureDoctype(body)
 
   let headers = new Headers(init?.headers)
   if (!headers.has('Content-Type')) {
@@ -22,3 +22,76 @@ export function html(body: BodyInit | SafeHtml, init?: ResponseInit): Response {
 
   return new Response(payload, { ...init, headers })
 }
+
+function ensureDoctype(body: HtmlBody): BodyInit {
+  if (isSafeHtml(body)) {
+    let str = String(body)
+    return startsWithDoctype(str) ? str : DOCTYPE + str
+  }
+
+  if (typeof body === 'string') {
+    return startsWithDoctype(body) ? body : DOCTYPE + body
+  }
+
+  if (body instanceof Blob) {
+    return prependDoctypeToStream(body.stream())
+  }
+
+  if (body instanceof ArrayBuffer || ArrayBuffer.isView(body)) {
+    let text = new TextDecoder().decode(body)
+    return startsWithDoctype(text) ? text : DOCTYPE + text
+  }
+
+  if (body instanceof ReadableStream) {
+    return prependDoctypeToStream(body)
+  }
+
+  return body
+}
+
+function startsWithDoctype(str: string): boolean {
+  return /^\s*<!doctype html/i.test(str)
+}
+
+function prependDoctypeToStream(stream: ReadableStream<Uint8Array>): ReadableStream<Uint8Array> {
+  let doctypeBytes = new TextEncoder().encode(DOCTYPE)
+  let reader = stream.getReader()
+
+  return new ReadableStream({
+    async start(controller) {
+      try {
+        // Read first chunk to check for DOCTYPE
+        let firstChunk = await reader.read()
+
+        if (firstChunk.done) {
+          // Empty stream, just add DOCTYPE
+          controller.enqueue(doctypeBytes)
+          controller.close()
+          return
+        }
+
+        // Check if the first chunk starts with DOCTYPE
+        let text = new TextDecoder().decode(firstChunk.value, { stream: true })
+        if (startsWithDoctype(text)) {
+          // Already has DOCTYPE, pass through
+          controller.enqueue(firstChunk.value)
+        } else {
+          // Prepend DOCTYPE
+          controller.enqueue(doctypeBytes)
+          controller.enqueue(firstChunk.value)
+        }
+
+        // Pass through remaining chunks
+        while (true) {
+          let { done, value } = await reader.read()
+          if (done) break
+          controller.enqueue(value)
+        }
+
+        controller.close()
+      } catch (error) {
+        controller.error(error)
+      }
+    },
+  })
+}
