1 | <div align="center">
|
2 |
|
3 | <img src="logo/horizontal.png" alt="connect logo" width="450px">
|
4 |
|
5 | [![NPM Version][npm-version-image]][npm-url]
|
6 | [![NPM Downloads][npm-downloads-image]][npm-url]
|
7 | [![Build Status][travis-image]][travis-url]
|
8 | [![Test Coverage][coveralls-image]][coveralls-url]
|
9 |
|
10 | </div>
|
11 |
|
12 | Connect is an extensible HTTP server framework for [node](http://nodejs.org) using "plugins" known as _middleware_.
|
13 |
|
14 | ```js
|
15 | var connect = require('connect');
|
16 | var http = require('http');
|
17 |
|
18 | var app = connect();
|
19 |
|
20 | // gzip/deflate outgoing responses
|
21 | var compression = require('compression');
|
22 | app.use(compression());
|
23 |
|
24 | // store session state in browser cookie
|
25 | var cookieSession = require('cookie-session');
|
26 | app.use(cookieSession({
|
27 | keys: ['secret1', 'secret2']
|
28 | }));
|
29 |
|
30 | // parse urlencoded request bodies into req.body
|
31 | var bodyParser = require('body-parser');
|
32 | app.use(bodyParser.urlencoded({extended: false}));
|
33 |
|
34 | // respond to all requests
|
35 | app.use(function(req, res){
|
36 | res.end('Hello from Connect!\n');
|
37 | });
|
38 |
|
39 | //create node.js http server and listen on port
|
40 | http.createServer(app).listen(3000);
|
41 | ```
|
42 |
|
43 | ## Getting Started
|
44 |
|
45 | Connect is a simple framework to glue together various "middleware" to handle requests.
|
46 |
|
47 | ### Install Connect
|
48 |
|
49 | ```sh
|
50 | $ npm install connect
|
51 | ```
|
52 |
|
53 | ### Create an app
|
54 |
|
55 | The main component is a Connect "app". This will store all the middleware
|
56 | added and is, itself, a function.
|
57 |
|
58 | ```js
|
59 | var app = connect();
|
60 | ```
|
61 |
|
62 | ### Use middleware
|
63 |
|
64 | The core of Connect is "using" middleware. Middleware are added as a "stack"
|
65 | where incoming requests will execute each middleware one-by-one until a middleware
|
66 | does not call `next()` within it.
|
67 |
|
68 | ```js
|
69 | app.use(function middleware1(req, res, next) {
|
70 | // middleware 1
|
71 | next();
|
72 | });
|
73 | app.use(function middleware2(req, res, next) {
|
74 | // middleware 2
|
75 | next();
|
76 | });
|
77 | ```
|
78 |
|
79 | ### Mount middleware
|
80 |
|
81 | The `.use()` method also takes an optional path string that is matched against
|
82 | the beginning of the incoming request URL. This allows for basic routing.
|
83 |
|
84 | ```js
|
85 | app.use('/foo', function fooMiddleware(req, res, next) {
|
86 | // req.url starts with "/foo"
|
87 | next();
|
88 | });
|
89 | app.use('/bar', function barMiddleware(req, res, next) {
|
90 | // req.url starts with "/bar"
|
91 | next();
|
92 | });
|
93 | ```
|
94 |
|
95 | ### Error middleware
|
96 |
|
97 | There are special cases of "error-handling" middleware. There are middleware
|
98 | where the function takes exactly 4 arguments. When a middleware passes an error
|
99 | to `next`, the app will proceed to look for the error middleware that was declared
|
100 | after that middleware and invoke it, skipping any error middleware above that
|
101 | middleware and any non-error middleware below.
|
102 |
|
103 | ```js
|
104 | // regular middleware
|
105 | app.use(function (req, res, next) {
|
106 | // i had an error
|
107 | next(new Error('boom!'));
|
108 | });
|
109 |
|
110 | // error middleware for errors that occurred in middleware
|
111 | // declared before this
|
112 | app.use(function onerror(err, req, res, next) {
|
113 | // an error occurred!
|
114 | });
|
115 | ```
|
116 |
|
117 | ### Create a server from the app
|
118 |
|
119 | The last step is to actually use the Connect app in a server. The `.listen()` method
|
120 | is a convenience to start a HTTP server (and is identical to the `http.Server`'s `listen`
|
121 | method in the version of Node.js you are running).
|
122 |
|
123 | ```js
|
124 | var server = app.listen(port);
|
125 | ```
|
126 |
|
127 | The app itself is really just a function with three arguments, so it can also be handed
|
128 | to `.createServer()` in Node.js.
|
129 |
|
130 | ```js
|
131 | var server = http.createServer(app);
|
132 | ```
|
133 |
|
134 | ## Middleware
|
135 |
|
136 | These middleware and libraries are officially supported by the Connect/Express team:
|
137 |
|
138 | - [body-parser](https://www.npmjs.com/package/body-parser) - previous `bodyParser`, `json`, and `urlencoded`. You may also be interested in:
|
139 | - [body](https://www.npmjs.com/package/body)
|
140 | - [co-body](https://www.npmjs.com/package/co-body)
|
141 | - [raw-body](https://www.npmjs.com/package/raw-body)
|
142 | - [compression](https://www.npmjs.com/package/compression) - previously `compress`
|
143 | - [connect-timeout](https://www.npmjs.com/package/connect-timeout) - previously `timeout`
|
144 | - [cookie-parser](https://www.npmjs.com/package/cookie-parser) - previously `cookieParser`
|
145 | - [cookie-session](https://www.npmjs.com/package/cookie-session) - previously `cookieSession`
|
146 | - [csurf](https://www.npmjs.com/package/csurf) - previously `csrf`
|
147 | - [errorhandler](https://www.npmjs.com/package/errorhandler) - previously `error-handler`
|
148 | - [express-session](https://www.npmjs.com/package/express-session) - previously `session`
|
149 | - [method-override](https://www.npmjs.com/package/method-override) - previously `method-override`
|
150 | - [morgan](https://www.npmjs.com/package/morgan) - previously `logger`
|
151 | - [response-time](https://www.npmjs.com/package/response-time) - previously `response-time`
|
152 | - [serve-favicon](https://www.npmjs.com/package/serve-favicon) - previously `favicon`
|
153 | - [serve-index](https://www.npmjs.com/package/serve-index) - previously `directory`
|
154 | - [serve-static](https://www.npmjs.com/package/serve-static) - previously `static`
|
155 | - [vhost](https://www.npmjs.com/package/vhost) - previously `vhost`
|
156 |
|
157 | Most of these are exact ports of their Connect 2.x equivalents. The primary exception is `cookie-session`.
|
158 |
|
159 | Some middleware previously included with Connect are no longer supported by the Connect/Express team, are replaced by an alternative module, or should be superseded by a better module. Use one of these alternatives instead:
|
160 |
|
161 | - `cookieParser`
|
162 | - [cookies](https://www.npmjs.com/package/cookies) and [keygrip](https://www.npmjs.com/package/keygrip)
|
163 | - `limit`
|
164 | - [raw-body](https://www.npmjs.com/package/raw-body)
|
165 | - `multipart`
|
166 | - [connect-multiparty](https://www.npmjs.com/package/connect-multiparty)
|
167 | - [connect-busboy](https://www.npmjs.com/package/connect-busboy)
|
168 | - `query`
|
169 | - [qs](https://www.npmjs.com/package/qs)
|
170 | - `staticCache`
|
171 | - [st](https://www.npmjs.com/package/st)
|
172 | - [connect-static](https://www.npmjs.com/package/connect-static)
|
173 |
|
174 | Checkout [http-framework](https://github.com/Raynos/http-framework/wiki/Modules) for many other compatible middleware!
|
175 |
|
176 | ## API
|
177 |
|
178 | The Connect API is very minimalist, enough to create an app and add a chain
|
179 | of middleware.
|
180 |
|
181 | When the `connect` module is required, a function is returned that will construct
|
182 | a new app when called.
|
183 |
|
184 | ```js
|
185 | // require module
|
186 | var connect = require('connect')
|
187 |
|
188 | // create app
|
189 | var app = connect()
|
190 | ```
|
191 |
|
192 | ### app(req, res[, next])
|
193 |
|
194 | The `app` itself is a function. This is just an alias to `app.handle`.
|
195 |
|
196 | ### app.handle(req, res[, out])
|
197 |
|
198 | Calling the function will run the middleware stack against the given Node.js
|
199 | http request (`req`) and response (`res`) objects. An optional function `out`
|
200 | can be provided that will be called if the request (or error) was not handled
|
201 | by the middleware stack.
|
202 |
|
203 | ### app.listen([...])
|
204 |
|
205 | Start the app listening for requests. This method will internally create a Node.js
|
206 | HTTP server and call `.listen()` on it.
|
207 |
|
208 | This is an alias to the `server.listen()` method in the version of Node.js running,
|
209 | so consult the Node.js documentation for all the different variations. The most
|
210 | common signature is [`app.listen(port)`](https://nodejs.org/dist/latest-v6.x/docs/api/http.html#http_server_listen_port_hostname_backlog_callback).
|
211 |
|
212 | ### app.use(fn)
|
213 |
|
214 | Use a function on the app, where the function represents a middleware. The function
|
215 | will be invoked for every request in the order that `app.use` is called. The function
|
216 | is called with three arguments:
|
217 |
|
218 | ```js
|
219 | app.use(function (req, res, next) {
|
220 | // req is the Node.js http request object
|
221 | // res is the Node.js http response object
|
222 | // next is a function to call to invoke the next middleware
|
223 | })
|
224 | ```
|
225 |
|
226 | In addition to a plan function, the `fn` argument can also be a Node.js HTTP server
|
227 | instance or another Connect app instance.
|
228 |
|
229 | ### app.use(route, fn)
|
230 |
|
231 | Use a function on the app, where the function represents a middleware. The function
|
232 | will be invoked for every request in which the URL (`req.url` property) starts with
|
233 | the given `route` string in the order that `app.use` is called. The function is
|
234 | called with three arguments:
|
235 |
|
236 | ```js
|
237 | app.use('/foo', function (req, res, next) {
|
238 | // req is the Node.js http request object
|
239 | // res is the Node.js http response object
|
240 | // next is a function to call to invoke the next middleware
|
241 | })
|
242 | ```
|
243 |
|
244 | In addition to a plan function, the `fn` argument can also be a Node.js HTTP server
|
245 | instance or another Connect app instance.
|
246 |
|
247 | The `route` is always terminated at a path separator (`/`) or a dot (`.`) character.
|
248 | This means the given routes `/foo/` and `/foo` are the same and both will match requests
|
249 | with the URLs `/foo`, `/foo/`, `/foo/bar`, and `/foo.bar`, but not match a request with
|
250 | the URL `/foobar`.
|
251 |
|
252 | The `route` is matched in a case-insensitive manor.
|
253 |
|
254 | In order to make middleware easier to write to be agnostic of the `route`, when the
|
255 | `fn` is invoked, the `req.url` will be altered to remove the `route` part (and the
|
256 | original will be available as `req.originalUrl`). For example, if `fn` is used at the
|
257 | route `/foo`, the request for `/foo/bar` will invoke `fn` with `req.url === '/bar'`
|
258 | and `req.originalUrl === '/foo/bar'`.
|
259 |
|
260 | ## Running Tests
|
261 |
|
262 | ```bash
|
263 | npm install
|
264 | npm test
|
265 | ```
|
266 |
|
267 | ## People
|
268 |
|
269 | The Connect project would not be the same without all the people involved.
|
270 |
|
271 | The original author of Connect is [TJ Holowaychuk](https://github.com/tj)
|
272 |
|
273 | The current lead maintainer is [Douglas Christopher Wilson](https://github.com/dougwilson)
|
274 |
|
275 | [List of all contributors](https://github.com/senchalabs/connect/graphs/contributors)
|
276 |
|
277 | ## Node Compatibility
|
278 |
|
279 | - Connect `< 1.x` - node `0.2`
|
280 | - Connect `1.x` - node `0.4`
|
281 | - Connect `< 2.8` - node `0.6`
|
282 | - Connect `>= 2.8 < 3` - node `0.8`
|
283 | - Connect `>= 3` - node `0.10`, `0.12`, `4.x`, `5.x`, `6.x`, `7.x`, `8.x`, `9.x`, `10.x`, `11.x`, `12.x`; io.js `1.x`, `2.x`, `3.x`
|
284 |
|
285 | ## License
|
286 |
|
287 | [MIT](LICENSE)
|
288 |
|
289 | [coveralls-image]: https://badgen.net/coveralls/c/github/senchalabs/connect/master
|
290 | [coveralls-url]: https://coveralls.io/r/senchalabs/connect?branch=master
|
291 | [npm-downloads-image]: https://badgen.net/npm/dm/connect
|
292 | [npm-url]: https://npmjs.org/package/connect
|
293 | [npm-version-image]: https://badgen.net/npm/v/connect
|
294 | [travis-image]: https://badgen.net/travis/senchalabs/connect/master
|
295 | [travis-url]: https://travis-ci.org/senchalabs/connect
|