Response
Utilities to send response headers and data
appendHeader(event, name, value)
Append a response header by name.
Example:
export default defineEventHandler((event) => {
appendResponseHeader(event, "content-type", "text/html");
});
appendHeaders(event, headers)
Append the response headers.
Example:
export default defineEventHandler((event) => {
appendResponseHeaders(event, {
"content-type": "text/html",
"cache-control": "no-cache",
});
});
appendResponseHeader(event, name, value)
Append a response header by name.
Example:
export default defineEventHandler((event) => {
appendResponseHeader(event, "content-type", "text/html");
});
appendResponseHeaders(event, headers)
Append the response headers.
Example:
export default defineEventHandler((event) => {
appendResponseHeaders(event, {
"content-type": "text/html",
"cache-control": "no-cache",
});
});
clearResponseHeaders(event, headerNames?)
Remove all response headers, or only those specified in the headerNames array.
Example:
export default defineEventHandler((event) => {
clearResponseHeaders(event, ["content-type", "cache-control"]); // Remove content-type and cache-control headers
});
defaultContentType(event, type?)
Set the response status code and message.
getResponseHeader(event, name)
Alias for getResponseHeaders.
Example:
export default defineEventHandler((event) => {
const contentType = getResponseHeader(event, "content-type"); // Get the response content-type header
});
getResponseHeaders(event)
Get the response headers object.
Example:
export default defineEventHandler((event) => {
const headers = getResponseHeaders(event);
});
getResponseStatus(event)
Get the current response status code.
Example:
export default defineEventHandler((event) => {
const status = getResponseStatus(event);
return `Status: ${status}`;
});
getResponseStatusText(event)
Get the current response status message.
Example:
export default defineEventHandler((event) => {
const statusText = getResponseStatusText(event);
return `Status: ${statusText}`;
});
isStream(data)
Checks if the data is a stream. (Node.js Readable Stream, React Pipeable Stream, or Web Stream)
isWebResponse(data)
Checks if the data is a Response object.
removeResponseHeader(event, name)
Remove a response header by name.
Example:
export default defineEventHandler((event) => {
removeResponseHeader(event, "content-type"); // Remove content-type header
});
send(event, data?, type?)
Directly send a response to the client.
Note: This function should be used only when you want to send a response directly without using the h3 event. Normally you can directly return a value inside event handlers.
sendIterable(event, iterable)
Iterate a source of chunks and send back each chunk in order. Supports mixing async work together with emitting chunks.
Each chunk must be a string or a buffer.
For generator (yielding) functions, the returned value is treated the same as yielded values.
Example:
sendIterable(event, work());
async function* work() {
// Open document body
yield "<!DOCTYPE html>\n<html><body><h1>Executing...</h1><ol>\n";
// Do work ...
for (let i = 0; i < 1000) {
await delay(1000);
// Report progress
yield `<li>Completed job #`;
yield i;
yield `</li>\n`;
}
// Close out the report
return `</ol></body></html>`;
}
async function delay(ms) {
return new Promise(resolve => setTimeout(resolve, ms));
}
sendNoContent(event, code?)
Respond with an empty payload.
Note that calling this function will close the connection and no other data can be sent to the client afterwards.
Example:
export default defineEventHandler((event) => {
return sendNoContent(event);
});
Example:
export default defineEventHandler((event) => {
sendNoContent(event); // Close the connection
console.log("This will not be executed");
});
sendRedirect(event, location, code)
Send a redirect response to the client.
It adds the location header to the response and sets the status code to 302 by default.
In the body, it sends a simple HTML page with a meta refresh tag to redirect the client in case the headers are ignored.
Example:
export default defineEventHandler((event) => {
return sendRedirect(event, "https://example.com");
});
Example:
export default defineEventHandler((event) => {
return sendRedirect(event, "https://example.com", 301); // Permanent redirect
});
sendStream(event, stream)
Send a stream response to the client.
Note: You can directly return a stream value inside event handlers alternatively which is recommended.
sendWebResponse(event, response)
Send a Response object to the client.
setHeader(event, name, value)
Set a response header by name.
Example:
export default defineEventHandler((event) => {
setResponseHeader(event, "content-type", "text/html");
});
setHeaders(event)
Set the response headers.
Example:
export default defineEventHandler((event) => {
setResponseHeaders(event, {
"content-type": "text/html",
"cache-control": "no-cache",
});
});
setResponseHeader(event, name, value)
Set a response header by name.
Example:
export default defineEventHandler((event) => {
setResponseHeader(event, "content-type", "text/html");
});
setResponseHeaders(event)
Set the response headers.
Example:
export default defineEventHandler((event) => {
setResponseHeaders(event, {
"content-type": "text/html",
"cache-control": "no-cache",
});
});
setResponseStatus(event, code?, text?)
Set the response status code and message.
Example:
export default defineEventHandler((event) => {
setResponseStatus(event, 404, "Not Found");
return "Not Found";
});
writeEarlyHints(event, hints, cb)
Write HTTP/1.1 103 Early Hints to the client.