1 | # serve-favicon
|
2 |
|
3 | [![NPM Version][npm-image]][npm-url]
|
4 | [![NPM Downloads][downloads-image]][downloads-url]
|
5 | [![Linux Build][travis-image]][travis-url]
|
6 | [![Windows Build][appveyor-image]][appveyor-url]
|
7 | [![Test Coverage][coveralls-image]][coveralls-url]
|
8 |
|
9 | Node.js middleware for serving a favicon.
|
10 |
|
11 | A favicon is a visual cue that client software, like browsers, use to identify
|
12 | a site. For an example and more information, please visit
|
13 | [the Wikipedia article on favicons](https://en.wikipedia.org/wiki/Favicon).
|
14 |
|
15 | Why use this module?
|
16 |
|
17 | - User agents request `favicon.ico` frequently and indiscriminately, so you
|
18 | may wish to exclude these requests from your logs by using this middleware
|
19 | before your logger middleware.
|
20 | - This module caches the icon in memory to improve performance by skipping
|
21 | disk access.
|
22 | - This module provides an `ETag` based on the contents of the icon, rather
|
23 | than file system properties.
|
24 | - This module will serve with the most compatible `Content-Type`.
|
25 |
|
26 | **Note** This module is exclusively for serving the "default, implicit favicon",
|
27 | which is `GET /favicon.ico`. For additional vendor-specific icons that require
|
28 | HTML markup, additional middleware is required to serve the relevant files, for
|
29 | example [serve-static](https://npmjs.org/package/serve-static).
|
30 |
|
31 | ## Install
|
32 |
|
33 | This is a [Node.js](https://nodejs.org/en/) module available through the
|
34 | [npm registry](https://www.npmjs.com/). Installation is done using the
|
35 | [`npm install` command](https://docs.npmjs.com/getting-started/installing-npm-packages-locally):
|
36 |
|
37 | ```sh
|
38 | $ npm install serve-favicon
|
39 | ```
|
40 |
|
41 | ## API
|
42 |
|
43 | ### favicon(path, options)
|
44 |
|
45 | Create new middleware to serve a favicon from the given `path` to a favicon file.
|
46 | `path` may also be a `Buffer` of the icon to serve.
|
47 |
|
48 | #### Options
|
49 |
|
50 | Serve favicon accepts these properties in the options object.
|
51 |
|
52 | ##### maxAge
|
53 |
|
54 | The `cache-control` `max-age` directive in `ms`, defaulting to 1 year. This can
|
55 | also be a string accepted by the [ms](https://www.npmjs.org/package/ms#readme)
|
56 | module.
|
57 |
|
58 | ## Examples
|
59 |
|
60 | Typically this middleware will come very early in your stack (maybe even first)
|
61 | to avoid processing any other middleware if we already know the request is for
|
62 | `/favicon.ico`.
|
63 |
|
64 | ### express
|
65 |
|
66 | ```javascript
|
67 | var express = require('express')
|
68 | var favicon = require('serve-favicon')
|
69 | var path = require('path')
|
70 |
|
71 | var app = express()
|
72 | app.use(favicon(path.join(__dirname, 'public', 'favicon.ico')))
|
73 |
|
74 | // Add your routes here, etc.
|
75 |
|
76 | app.listen(3000)
|
77 | ```
|
78 |
|
79 | ### connect
|
80 |
|
81 | ```javascript
|
82 | var connect = require('connect')
|
83 | var favicon = require('serve-favicon')
|
84 | var path = require('path')
|
85 |
|
86 | var app = connect()
|
87 | app.use(favicon(path.join(__dirname, 'public', 'favicon.ico')))
|
88 |
|
89 | // Add your middleware here, etc.
|
90 |
|
91 | app.listen(3000)
|
92 | ```
|
93 |
|
94 | ### vanilla http server
|
95 |
|
96 | This middleware can be used anywhere, even outside express/connect. It takes
|
97 | `req`, `res`, and `callback`.
|
98 |
|
99 | ```javascript
|
100 | var http = require('http')
|
101 | var favicon = require('serve-favicon')
|
102 | var finalhandler = require('finalhandler')
|
103 | var path = require('path')
|
104 |
|
105 | var _favicon = favicon(path.join(__dirname, 'public', 'favicon.ico'))
|
106 |
|
107 | var server = http.createServer(function onRequest (req, res) {
|
108 | var done = finalhandler(req, res)
|
109 |
|
110 | _favicon(req, res, function onNext (err) {
|
111 | if (err) return done(err)
|
112 |
|
113 | // continue to process the request here, etc.
|
114 |
|
115 | res.statusCode = 404
|
116 | res.end('oops')
|
117 | })
|
118 | })
|
119 |
|
120 | server.listen(3000)
|
121 | ```
|
122 |
|
123 | ## License
|
124 |
|
125 | [MIT](LICENSE)
|
126 |
|
127 | [npm-image]: https://img.shields.io/npm/v/serve-favicon.svg
|
128 | [npm-url]: https://npmjs.org/package/serve-favicon
|
129 | [travis-image]: https://img.shields.io/travis/expressjs/serve-favicon/master.svg?label=linux
|
130 | [travis-url]: https://travis-ci.org/expressjs/serve-favicon
|
131 | [appveyor-image]: https://img.shields.io/appveyor/ci/dougwilson/serve-favicon/master.svg?label=windows
|
132 | [appveyor-url]: https://ci.appveyor.com/project/dougwilson/serve-favicon
|
133 | [coveralls-image]: https://img.shields.io/coveralls/expressjs/serve-favicon.svg
|
134 | [coveralls-url]: https://coveralls.io/r/expressjs/serve-favicon?branch=master
|
135 | [downloads-image]: https://img.shields.io/npm/dm/serve-favicon.svg
|
136 | [downloads-url]: https://npmjs.org/package/serve-favicon
|