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