dgbuilder/dgeflows/node_modules/serve-favicon/README.md

   1 # serve-favicon
   2
   3 [![NPM Version][npm-image]][npm-url]
   4 [![NPM Downloads][downloads-image]][downloads-url]
   5 [![Build Status][travis-image]][travis-url]
   6 [![Test Coverage][coveralls-image]][coveralls-url]
   7 [![Gittip][gittip-image]][gittip-url]
   8
   9 Node.js middleware for serving a favicon.
  10
  11 Why use this module?
  12
  13   - User agents request `favicon.ico` frequently and indiscriminately, so you
  14     may wish to exclude these requests from your logs by using this middleware
  15     before your logger middleware.
  16   - This module caches the icon in memory to improve performance by skipping
  17     disk access.
  18   - This module provides an `ETag` based on the contents of the icon, rather
  19     than file system properties.
  20   - This module will serve with the most compatible `Content-Type`.
  21
  22 ## Install
  23
  24 ```bash
  25 npm install serve-favicon
  26 ```
  27
  28 ## API
  29
  30 ### favicon(path, options)
  31
  32 Create new middleware to serve a favicon from the given `path` to a favicon file.
  33 `path` may also be a `Buffer` of the icon to serve.
  34
  35 #### Options
  36
  37 Serve favicon accepts these properties in the options object.
  38
  39 ##### maxAge
  40
  41 The `cache-control` `max-age` directive in `ms`, defaulting to 1 day. This can
  42 also be a string accepted by the [ms](https://www.npmjs.org/package/ms#readme)
  43 module.
  44
  45 ## Examples
  46
  47 Typically this middleware will come very early in your stack (maybe even first)
  48 to avoid processing any other middleware if we already know the request is for
  49 `/favicon.ico`.
  50
  51 ### express
  52
  53 ```javascript
  54 var express = require('express');
  55 var favicon = require('serve-favicon');
  56
  57 var app = express();
  58 app.use(favicon(__dirname + '/public/favicon.ico'));
  59
  60 // Add your routes here, etc.
  61
  62 app.listen(3000);
  63 ```
  64
  65 ### connect
  66
  67 ```javascript
  68 var connect = require('connect');
  69 var favicon = require('serve-favicon');
  70
  71 var app = connect();
  72 app.use(favicon(__dirname + '/public/favicon.ico'));
  73
  74 // Add your middleware here, etc.
  75
  76 app.listen(3000);
  77 ```
  78
  79 ### vanilla http server
  80
  81 This middleware can be used anywhere, even outside express/connect. It takes
  82 `req`, `res`, and `callback`.
  83
  84 ```javascript
  85 var http = require('http');
  86 var favicon = require('serve-favicon');
  87 var finalhandler = require('finalhandler');
  88
  89 var _favicon = favicon(__dirname + '/public/favicon.ico');
  90
  91 var server = http.createServer(function onRequest(req, res) {
  92   var done = finalhandler(req, res);
  93
  94   _favicon(req, res, function onNext(err) {
  95     if (err) return done(err);
  96
  97     // continue to process the request here, etc.
  98
  99     res.statusCode = 404;
 100     res.end('oops');
 101   });
 102 });
 103
 104 server.listen(3000);
 105 ```
 106
 107 ## License
 108
 109 [MIT](LICENSE)
 110
 111 [npm-image]: https://img.shields.io/npm/v/serve-favicon.svg?style=flat
 112 [npm-url]: https://npmjs.org/package/serve-favicon
 113 [travis-image]: https://img.shields.io/travis/expressjs/serve-favicon.svg?style=flat
 114 [travis-url]: https://travis-ci.org/expressjs/serve-favicon
 115 [coveralls-image]: https://img.shields.io/coveralls/expressjs/serve-favicon.svg?style=flat
 116 [coveralls-url]: https://coveralls.io/r/expressjs/serve-favicon?branch=master
 117 [downloads-image]: https://img.shields.io/npm/dm/serve-favicon.svg?style=flat
 118 [downloads-url]: https://npmjs.org/package/serve-favicon
 119 [gittip-image]: https://img.shields.io/gittip/dougwilson.svg?style=flat
 120 [gittip-url]: https://www.gittip.com/dougwilson/