Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 59 lines (38 sloc) 2.805 kB
b8ef4ff @creationix Initial Commit
authored
1 # Stack
2
3 Stack is a minimal http module system for node.js.
4
5 Basically it's the core idea of connect but in a standalone and super minimal stack function.
6
7e8e69a @creationix Improve the README
authored
7 ## Install
8
9 If you use npm, then install stack via npm. Also, remember to put it as a dependency in your own project's package.json file.
10
11 npm install stack
12
13 If you don't use npm (Like you're on a phone), then simply copy the single file `stack.js` somewhere you can get to it.
14
b8ef4ff @creationix Initial Commit
authored
15 ## Example
16
066828d @creationix Fix the example code
authored
17 http.createServer(require('stack')(
18 require('loggerMiddleware')(),
19 require('staticMiddleware')(root, mount),
20 //...
21 )).listen(8080);
b8ef4ff @creationix Initial Commit
authored
22
7e8e69a @creationix Improve the README
authored
23 ## Explanation
24
b8ef4ff @creationix Initial Commit
authored
25 As you can see, it takes a list of handler functions and will chain them up for you.
26
27 Each handler needs to be of the form:
28
29 function handler(req, res, next) {
30 // Either handle the request here using `req` and `res`
31 // or call `next()` to pass control to next layer
32 // any exceptions need to be caught and forwarded to `next(err)`
33 }
34
bf52ad4 @creationix More README fixes
authored
35 When using external modules a good convention is to make the module be a callable setup function that returns the handler function. The first example uses modules created after this pattern.
b8ef4ff @creationix Initial Commit
authored
36
37 module.exports = function setup(some, args) {
38 // Do server set up stuff here
39 return function handle(req, res, next) {
40 // Handle a single request here
41 };
42 };
43
44 ## What Stack Does
45
46 Besides providing this nice linear syntax for defining http handler layers Stack does a few things under the hood.
47
bf52ad4 @creationix More README fixes
authored
48 - Wraps each layer in a `try..catch` to catch any exceptions that happen in the main execution stack layer's handler function.
b8ef4ff @creationix Initial Commit
authored
49 - Provides a fallthrough error handler function that returns 404 for routes that fall through all the layers and 500 responses for exceptions.
de49b80 @creationix Make the error handler configurable
authored
50 (You can override this at Stack.errorHandler, if for example, you don't like showing stack traces for all errors or want to pretty it up a bit)
b8ef4ff @creationix Initial Commit
authored
51 - Forwards and exceptions passed to any next layer directly to the error handler. This means layers don't have to worry about errors from previous layers.
52
53 ## What Stack Does NOT Do
54
55 Stack does not provide any middleware layers of any kind. If you want logging, or static file serving or anything, you have to provide your own handlers.
56 The reason is two-fold. First, it keeps Stack nice and small and easy to maintain. This worked great for my Step library and I think it will work great for Stack.
57 Second, I found with Connect, that having a central place where all middleware is kept is not good for the community. People want different things from eachother, and it's impossible to accept patches and feature requests that make everyone happy. Better I think is to provide a nice system for layering third-party modules and let each module succeed on it's own merit.
58
Something went wrong with that request. Please try again.