{"id":14969144,"url":"https://github.com/fastify/send","last_synced_at":"2025-04-05T04:09:28.472Z","repository":{"id":65231418,"uuid":"587678390","full_name":"fastify/send","owner":"fastify","description":"Fork of the send module to deal with CVE-2017-20165","archived":false,"fork":false,"pushed_at":"2025-03-07T19:05:35.000Z","size":586,"stargazers_count":13,"open_issues_count":2,"forks_count":14,"subscribers_count":12,"default_branch":"main","last_synced_at":"2025-03-29T03:04:52.697Z","etag":null,"topics":["fastify-library","file-download","send"],"latest_commit_sha":null,"homepage":"https://npmjs.com/package/@fastify/send","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/fastify.png","metadata":{"files":{"readme":"README.md","changelog":"HISTORY.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":"fastify","open_collective":"fastify"}},"created_at":"2023-01-11T10:20:27.000Z","updated_at":"2025-03-07T19:05:36.000Z","dependencies_parsed_at":"2023-02-16T08:01:06.605Z","dependency_job_id":"4c37ea4f-6813-4257-824d-5e9879634272","html_url":"https://github.com/fastify/send","commit_stats":{"total_commits":599,"total_committers":35,"mean_commits":"17.114285714285714","dds":"0.23372287145242066","last_synced_commit":"7dcacdbdfc636a44be03c35e6c22692e5dd0418c"},"previous_names":[],"tags_count":11,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fastify%2Fsend","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fastify%2Fsend/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fastify%2Fsend/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fastify%2Fsend/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/fastify","download_url":"https://codeload.github.com/fastify/send/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247284949,"owners_count":20913704,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["fastify-library","file-download","send"],"created_at":"2024-09-24T13:41:12.263Z","updated_at":"2025-04-05T04:09:28.416Z","avatar_url":"https://github.com/fastify.png","language":"JavaScript","funding_links":["https://github.com/sponsors/fastify","https://opencollective.com/fastify"],"categories":[],"sub_categories":[],"readme":"# @fastify/send\n\n[![CI](https://github.com/fastify/send/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/fastify/send/actions/workflows/ci.yml)\n[![NPM version](https://img.shields.io/npm/v/@fastify/send.svg?style=flat)](https://www.npmjs.com/package/@fastify/send)\n[![neostandard javascript style](https://img.shields.io/badge/code_style-neostandard-brightgreen?style=flat)](https://github.com/neostandard/neostandard)\n\nSend is a library for streaming files from the file system as an HTTP response\nsupporting partial responses (Ranges), conditional-GET negotiation (If-Match,\nIf-Unmodified-Since, If-None-Match, If-Modified-Since), high test coverage,\nand granular events which may be leveraged to take appropriate actions in your\napplication or framework.\n\n## Installation\n\nThis is a [Node.js](https://nodejs.org/en/) module available through the\n[npm registry](https://www.npmjs.com/). Installation is done using the\n[`npm install` command](https://docs.npmjs.com/getting-started/installing-npm-packages-locally):\n\n```bash\n$ npm install @fastify/send\n```\n\n### TypeScript\n\n`@types/mime@3` must be used if wanting to use TypeScript;\n`@types/mime@4` removed the `mime` types.\n\n```bash\n$ npm install -D @types/mime@3\n```\n\n## API\n\n```js\nconst send = require('@fastify/send')\n```\n\n### send(req, path, [options])\n\nProvide `statusCode`, `headers`, and `stream` for the given path to send to a\n`res`. The `req` is the Node.js HTTP request and the `path `is a urlencoded path\nto send (urlencoded, not the actual file-system path).\n\n#### Options\n\n##### acceptRanges\n\nEnable or disable accepting ranged requests, defaults to true.\nDisabling this will not send `Accept-Ranges` and ignore the contents\nof the `Range` request header.\n\n##### cacheControl\n\nEnable or disable setting `Cache-Control` response header, defaults to\ntrue. Disabling this will ignore the `immutable` and `maxAge` options.\n\n##### contentType\n\nBy default, this library uses the `mime` module to set the `Content-Type`\nof the response based on the file extension of the requested file.\n\nTo disable this functionality, set `contentType` to `false`.\nThe `Content-Type` header will need to be set manually if disabled.\n\n##### dotfiles\n\nSet how \"dotfiles\" are treated when encountered. A dotfile is a file\nor directory that begins with a dot (\".\"). Note this check is done on\nthe path itself without checking if the path exists on the\ndisk. If `root` is specified, only the dotfiles above the root are\nchecked (i.e. the root itself can be within a dotfile when set\nto \"deny\").\n\n  - `'allow'` No special treatment for dotfiles.\n  - `'deny'` Send a 403 for any request for a dotfile.\n  - `'ignore'` Pretend like the dotfile does not exist and 404.\n\nThe default value is _similar_ to `'ignore'`, with the exception that\nthis default will not ignore the files within a directory that begins\nwith a dot, for backward-compatibility.\n\n##### end\n\nByte offset at which the stream ends, defaults to the length of the file\nminus 1. The end is inclusive in the stream, meaning `end: 3` will include\nthe 4th byte in the stream.\n\n##### etag\n\nEnable or disable etag generation, defaults to true.\n\n##### extensions\n\nIf a given file doesn't exist, try appending one of the given extensions,\nin the given order. By default, this is disabled (set to `false`). An\nexample value that will serve extension-less HTML files: `['html', 'htm']`.\nThis is skipped if the requested file already has an extension.\n\n##### immutable\n\nEnable or disable the `immutable` directive in the `Cache-Control` response\nheader, defaults to `false`. If set to `true`, the `maxAge` option should\nalso be specified to enable caching. The `immutable` directive will prevent\nsupported clients from making conditional requests during the life of the\n`maxAge` option to check if the file has changed.\n\n##### index\n\nBy default send supports \"index.html\" files, to disable this\nset `false` or to supply a new index pass a string or an array\nin preferred order.\n\n##### lastModified\n\nEnable or disable `Last-Modified` header, defaults to true. Uses the file\nsystem's last modified value.\n\n##### maxAge\n\nProvide a max-age in milliseconds for HTTP caching, defaults to 0.\nThis can also be a string accepted by the\n[ms](https://www.npmjs.org/package/ms#readme) module.\n\n##### maxContentRangeChunkSize\n\nSpecify the maximum response content size, defaults to the entire file size.\nThis will be used when `acceptRanges` is true.\n\n##### root\n\nServe files relative to `path`.\n\n##### start\n\nByte offset at which the stream starts, defaults to 0. The start is inclusive,\nmeaning `start: 2` will include the 3rd byte in the stream.\n\n### .mime\n\nThe `mime` export is the global instance of the\n[`mime` npm module](https://www.npmjs.com/package/mime).\n\nThis is used to configure the MIME types that are associated with file extensions\nas well as other options for how to resolve the MIME type of a file (like the\ndefault type to use for an unknown file extension).\n\n## Caching\n\nIt does _not_ perform internal caching, you should use a reverse proxy cache\nsuch as Varnish for this, or those fancy things called CDNs. If your\napplication is small enough that it would benefit from single-node memory\ncaching, it's small enough that it does not need caching at all ;).\n\n## Debugging\n\nTo enable `debug()` instrumentation output export __NODE_DEBUG__:\n\n```\n$ NODE_DEBUG=send node app\n```\n\n## Running tests\n\n```\n$ npm install\n$ npm test\n```\n\n## Examples\n\n### Serve a specific file\n\nThis simple example will send a specific file to all requests.\n\n```js\nconst http = require('node:http')\nconst send = require('send')\n\nconst server = http.createServer(async function onRequest (req, res) {\n  const { statusCode, headers, stream } = await send(req, '/path/to/index.html')\n  res.writeHead(statusCode, headers)\n  stream.pipe(res)\n})\n\nserver.listen(3000)\n```\n\n### Serve all files from a directory\n\nThis simple example will just serve up all the files in a\ngiven directory as the top-level. For example, a request\n`GET /foo.txt` will send back `/www/public/foo.txt`.\n\n```js\nconst http = require('node:http')\nconst parseUrl = require('parseurl')\nconst send = require('@fastify/send')\n\nconst server = http.createServer(async function onRequest (req, res) {\n  const { statusCode, headers, stream } = await send(req, parseUrl(req).pathname, { root: '/www/public' })\n  res.writeHead(statusCode, headers)\n  stream.pipe(res)\n})\n\nserver.listen(3000)\n```\n\n### Custom file types\n\n```js\nconst http = require('node:http')\nconst parseUrl = require('parseurl')\nconst send = require('@fastify/send')\n\n// Default unknown types to text/plain\nsend.mime.default_type = 'text/plain'\n\n// Add a custom type\nsend.mime.define({\n  'application/x-my-type': ['x-mt', 'x-mtt']\n})\n\nconst server = http.createServer(function onRequest (req, res) {\n  const { statusCode, headers, stream } = await send(req, parseUrl(req).pathname, { root: '/www/public' })\n  res.writeHead(statusCode, headers)\n  stream.pipe(res)\n})\n\nserver.listen(3000)\n```\n\n### Custom directory index view\n\nThis is an example of serving up a structure of directories with a\ncustom function to render a listing of a directory.\n\n```js\nconst http = require('node:http')\nconst fs = require('node:fs')\nconst parseUrl = require('parseurl')\nconst send = require('@fastify/send')\n\n// Transfer arbitrary files from within /www/example.com/public/*\n// with a custom handler for directory listing\nconst server = http.createServer(async function onRequest (req, res) {\n  const { statusCode, headers, stream, type, metadata } = await send(req, parseUrl(req).pathname, { index: false, root: '/www/public' })\n  if(type === 'directory') {\n    // get directory list\n    const list = await readdir(metadata.path)\n    // render an index for the directory\n    res.writeHead(200, { 'Content-Type': 'text/plain; charset=utf-8' })\n    res.end(list.join('\\n') + '\\n')\n  } else {\n    res.writeHead(statusCode, headers)\n    stream.pipe(res)\n  }\n})\n\nserver.listen(3000)\n```\n\n### Serving from a root directory with custom error-handling\n\n```js\nconst http = require('node:http')\nconst parseUrl = require('parseurl')\nconst send = require('@fastify/send')\n\nconst server = http.createServer(async function onRequest (req, res) {\n  // transfer arbitrary files from within\n  // /www/example.com/public/*\n  const { statusCode, headers, stream, type, metadata } = await send(req, parseUrl(req).pathname, { root: '/www/public' })\n  switch (type) {\n    case 'directory': {\n      // your custom directory handling logic:\n      res.writeHead(301, {\n        'Location': metadata.requestPath + '/'\n      })\n      res.end('Redirecting to ' + metadata.requestPath + '/')\n      break\n    }\n    case 'error': {\n      // your custom error-handling logic:\n      res.writeHead(metadata.error.status ?? 500, {})\n      res.end(metadata.error.message)\n      break\n    }\n    default: {\n      // your custom headers\n      // serve all files for download\n      res.setHeader('Content-Disposition', 'attachment')\n      res.writeHead(statusCode, headers)\n      stream.pipe(res)\n    }\n  }\n})\n\nserver.listen(3000)\n```\n\n## License\n\nLicensed under [MIT](./LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffastify%2Fsend","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffastify%2Fsend","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffastify%2Fsend/lists"}