这是对 express.js guide 的一个翻译。翻译人：Sofish Lin。
$ npm install express或者在任何地方使用可执行的 express(1) 安装：
$ npm install -g express最快上手 express 的方法是利用可执行的 express(1) 来生成一个应用，如下所示：
创建一个 app：
$ npm install -g express
$ express /tmp/foo && cd /tmp/foo安装依赖包：
$ npm install -d启动服务器:
$ node app.js要创建一个 express.HTTPServer_ 实例，只需调用（simply invoke）createServer() 方法。 通用些 实例 app 我们可以定义基于 HTTP 动作（HTTP Verbs）的路由，以 app.get() 为例：
var app = require('express').createServer();
app.get('/', function(req, res){
res.send('hello world');
});
app.listen(3000);如上述初始化一个 express.HTTPSServer 实例。然后我们给它传一个配置对象，接受 key、cert 和其他在 https 文档 所提到的（属性/方法）。
var app = require('express').createServer({ key: ... });Express 支持任意环境，如产品阶段（production）和开发阶段（development）。开发者可以使用 configure() 方法来当前所需环境。如果 configure() 的调用不包含任何环境名，它将运行于各阶段环境中所指定的回调。
译注： 像 production / development / stage 这些别名都是可以自已取的，如 application.js 中的 app.configure 所示。实际用法看下面例子。
下面这个例子仅在开发阶段 dumpExceptions (抛错)，并返回堆栈异常。不过在两个环境中我们都使用 methodOverride 和 bodyParser。注意一下 app.router 的使用，它可以（可选）用来加载（mount）程序的路由，另外首次调用 app.get()、app.post() 等也将会加载路由。
app.configure(function(){
app.use(express.methodOverride());
app.use(express.bodyParser());
app.use(app.router);
});
app.configure('development', function(){
app.use(express.static(__dirname + '/public'));
app.use(express.errorHandler({ dumpExceptions: true, showStack: true }));
});
app.configure('production', function(){
var oneYear = 31557600000;
app.use(express.static(__dirname + '/public', { maxAge: oneYear }));
app.use(express.errorHandler());
});对于相似的环境你可以（译注：这里可以比可能更适合中文表达，you may also）传递多个环境字符串：
app.configure('stage', 'prod', function(){
// config
});对于内部的任意设置（#For internal and arbitrary settings) Express 提供了 set(key[, val])、 enable(key) 和 disable(key) 方法:
译注：设置详见：application.js 的 app.set。
app.configure(function(){
app.set('views', __dirname + '/views');
app.set('views');
// => "/absolute/path/to/views"
app.enable('some feature');
// 等价于：app.set('some feature', true);
app.disable('some feature');
// 等价于：app.set('some feature', false);
app.enabled('some feature')
// => false
});变更环境我们可以设置 NODE_ENV 环境亦是，如：
$ NODE_ENV=production node app.js这非常重要，因为多数缓存机制只在产品阶段是被打开的。
Express 支持下列快捷（out of the box）设置:
basepath用于res.redirect()的应用程序基本路径（base path），显式地处理绑定的应用程序（transparently handling mounted apps.）viewView 默认的根目录为 CWD/viewsview engine默认 View 引擎处理（View 文件）并不需要使用后缀view cache启用 View 缓存 (在产品阶段被启用)charet改变编码，默认为 utf-8case sensitive routes路由中区分大小写strit routing启用后（路由中的）结尾/将不会被忽略（译注：即app.get('/sofish')和app.get('/sofish/')将是不一样的）json callback启用res.send()/res.json()显式的的 jsonp 支持（transparent jsonp support）
Express utilizes the HTTP verbs to provide a meaningful, expressive routing API.
For example we may want to render a user's account for the path /user/12, this
can be done by defining the route below. The values associated to the named placeholders
are available as req.params.
app.get('/user/:id', function(req, res){ res.send('user ' + req.params.id); });
A route is simple a string which is compiled to a RegExp internally. For example when /user/:id is compiled, a simplified version of the regexp may look similar to:
/user/([^\/]+)/?
Regular expression literals may also be passed for complex uses. Since capture
groups with literal RegExp's are anonymous we can access them directly req.params. So our first capture group would be req.params[0] and the second would follow as req.params[1].
app.get(/^/users?(?:/(\d+)(?:..(\d+))?)?/, function(req, res){ res.send(req.params); });
Curl requests against the previously defined route:
$ curl http://dev:3000/user [null,null] $ curl http://dev:3000/users [null,null] $ curl http://dev:3000/users/1 ["1",null] $ curl http://dev:3000/users/1..15 ["1","15"]
Below are some route examples, and the associated paths that they may consume:
"/user/:id" /user/12
"/users/:id?" /users/5 /users
"/files/*" /files/jquery.js /files/javascripts/jquery.js
"/file/." /files/jquery.js /files/javascripts/jquery.js
"/user/:id/:operation?" /user/1 /user/1/edit
"/products.:format" /products.json /products.xml
"/products.:format?" /products.json /products.xml /products
"/user/:id.:format?" /user/12 /user/12.json
For example we can POST some json, and echo the json back using the bodyParser middleware which will parse json request bodies (as well as others), and place the result in req.body:
var express = require('express') , app = express.createServer();
app.use(express.bodyParser());
app.post('/', function(req, res){ res.send(req.body); });
app.listen(3000);
Typically we may use a "dumb" placeholder such as "/user/:id" which has no restrictions, however say for example we are limiting a user id to digits, we may use '/user/:id([0-9]+)' which will not match unless the placeholder value contains only digits.
We may pass control to the next matching route, by calling the third argument, the next() function. When a match cannot be made, control is passed back to Connect, and middleware continue to be invoked in the order that they are added via use(). The same is true for several routes which have the same path defined, they will simply be executed in order until one does not call next() and decides to respond.
app.get('/users/:id?', function(req, res, next){ var id = req.params.id; if (id) { // do something } else { next(); } });
app.get('/users', function(req, res){ // do something else });
The app.all() method is useful for applying the same logic for all HTTP verbs in a single call. Below we use this to load a user from our fake database, and assign it to req.user.
var express = require('express') , app = express.createServer();
var users = [{ name: 'tj' }];
app.all('/user/:id/:op?', function(req, res, next){ req.user = users[req.params.id]; if (req.user) { next(); } else { next(new Error('cannot find user ' + req.params.id)); } });
app.get('/user/:id', function(req, res){ res.send('viewing ' + req.user.name); });
app.get('/user/:id/edit', function(req, res){ res.send('editing ' + req.user.name); });
app.put('/user/:id', function(req, res){ res.send('updating ' + req.user.name); });
app.get('*', function(req, res){ res.send(404, 'what???'); });
app.listen(3000);
Middleware via Connect can be passed to express.createServer() as you would with a regular Connect server. For example:
var express = require('express');
var app = express.createServer( express.logger() , express.bodyParser() );
Alternatively we can use() them which is useful when adding middleware within configure() blocks, in a progressive manner.
app.use(express.logger({ format: ':method :url' }));
Typically with connect middleware you would require('connect') like so:
var connect = require('connect'); app.use(connect.logger()); app.use(connect.bodyParser());
This is somewhat annoying, so express re-exports these middleware properties, however they are identical:
app.use(express.logger()); app.use(express.bodyParser());
Middleware ordering is important, when Connect receives a request the first middleware we pass to createServer() or use() is executed with three parameters, request, response, and a callback function usually named next. When next() is invoked the second middleware will then have it's turn and so on. This is important to note because many middleware depend on each other, for example methodOverride() checks _req.body.method for the HTTP method override, however bodyParser() parses the request body and populates req.body. Another example of this is cookie parsing and session support, we must first use() cookieParser() followed by session().
Many Express applications may contain the line app.use(app.router), while this may appear strange, it's simply the middleware function that contains all defined routes, and performs route lookup based on the current request url and HTTP method. Express allows you to position this middleware, though by default it will be added to the bottom. By positioning the router, we can alter middleware precedence, for example we may want to add error reporting as the last middleware so that any exception passed to next() will be handled by it, or perhaps we want static file serving to have low precedence, allowing our routes to intercept requests to a static file to count downloads etc. This may look a little like below
app.use(express.logger(...)); app.use(express.bodyParser(...)); app.use(express.cookieParser(...)); app.use(express.session(...)); app.use(app.router); app.use(express.static(...)); app.use(express.errorHandler(...));
First we add logger() so that it may wrap node's req.end() method, providing us with response-time data. Next the request's body will be parsed (if any), followed by cookie parsing and session support, meaning req.session will be defined by the time we hit our routes in app.router. If a request such as GET /javascripts/jquery.js is handled by our routes, and we do not call next() then the static() middleware will never see this request, however if were to define a route as shown below, we can record stats, refuse downloads, consume download credits etc.
var downloads = {};
app.use(app.router); app.use(express.static(__dirname + '/public'));
app.get('/*', function(req, res, next){ var file = req.params[0]; downloads[file] = downloads[file] || 0; downloads[file]++; next(); });
Routes may utilize route-specific middleware by passing one or more additional callbacks (or arrays) to the method. This feature is extremely useful for restricting access, loading data used by the route etc.
Typically async data retrieval might look similar to below, where we take the :id parameter, and attempt loading a user.
app.get('/user/:id', function(req, res, next){ loadUser(req.params.id, function(err, user){ if (err) return next(err); res.send('Viewing user ' + user.name); }); });
To keep things DRY and to increase readability we can apply this logic within a middleware. As you can see below, abstracting this logic into middleware allows us to reuse it, and clean up our route at the same time.
function loadUser(req, res, next) { // You would fetch your user from the db var user = users[req.params.id]; if (user) { req.user = user; next(); } else { next(new Error('Failed to load user ' + req.params.id)); } }
app.get('/user/:id', loadUser, function(req, res){ res.send('Viewing user ' + req.user.name); });
Multiple route middleware can be applied, and will be executed sequentially to apply further logic such as restricting access to a user account. In the example below only the authenticated user may edit his/her account.
function andRestrictToSelf(req, res, next) { req.authenticatedUser.id == req.user.id ? next() : next(new Error('Unauthorized')); }
app.get('/user/:id/edit', loadUser, andRestrictToSelf, function(req, res){ res.send('Editing user ' + req.user.name); });
Keeping in mind that middleware are simply functions, we can define function that returns the middleware in order to create a more expressive and flexible solution as shown below.
function andRestrictTo(role) { return function(req, res, next) { req.authenticatedUser.role == role ? next() : next(new Error('Unauthorized')); } }
app.del('/user/:id', loadUser, andRestrictTo('admin'), function(req, res){ res.send('Deleted user ' + req.user.name); });
Commonly used "stacks" of middleware can be passed as an array (applied recursively), which can be mixed and matched to any degree.
var a = [middleware1, middleware2] , b = [middleware3, middleware4] , all = [a, b];
app.get('/foo', a, function(){}); app.get('/bar', a, function(){});
app.get('/', a, middleware3, middleware4, function(){}); app.get('/', a, b, function(){}); app.get('/', all, function(){});
For this example in full, view the route middleware example in the repository.
There are times when we may want to "skip" passed remaining route middleware, but continue matching subsequent routes. To do this we invoke next() with the string "route" next('route'). If no remaining routes match the request url then Express will respond with 404 Not Found.
We have seen app.get() a few times, however Express also exposes other familiar HTTP verbs in the same manner, such as app.post(), app.del(), etc.
A common example for POST usage, is when "submitting" a form. Below we simply set our form method to "post" in our html, and control will be given to the route we have defined below it.
By default Express does not know what to do with this request body, so we should add the bodyParser middleware, which will parse application/x-www-form-urlencoded and application/json request bodies and place the variables in req.body. We can do this by "using" the middleware as shown below:
app.use(express.bodyParser());
Our route below will now have access to the req.body.user object which will contain the name and email properties when defined.
app.post('/', function(req, res){ console.log(req.body.user); res.redirect('back'); });
When using methods such as PUT with a form, we can utilize a hidden input named _method, which can be used to alter the HTTP method. To do so we first need the methodOverride middleware, which should be placed below bodyParser so that it can utilize it's req.body containing the form values.
app.use(express.bodyParser()); app.use(express.methodOverride());
The reason that these are not always defaults, is simply because these are not required for Express to be fully functional. Depending on the needs of your application, you may not need these at all, your methods such as PUT and DELETE can still be accessed by clients which can use them directly, although methodOverride provides a great solution for forms. Below shows what the usage of PUT might look like:
app.put('/', function(){ console.log(req.body.user); res.redirect('back'); });
Error handling middleware are simply middleware with an arity of 4, aka the signature (err, req, res, next). When you next(err) an error, only these middleware are executed and have a chance to respond. For example:
app.use(app.bodyParser()); app.use(app.methodOverride()); app.use(app.router); app.use(function(err, req, res, next){ res.send(500, 'Server error'); });
Route param pre-conditions can drastically improve the readability of your application, through implicit loading of data, and validation of request urls. For example if you are constantly fetching common data for several routes, such as loading a user for /user/:id, we might typically do something like below:
app.get('/user/:userId', function(req, res, next){ User.get(req.params.userId, function(err, user){ if (err) return next(err); res.send('user ' + user.name); }); });
With preconditions our params can be mapped to callbacks which may perform validation, coercion, or even loading data from a database. Below we invoke app.param() with the parameter name we wish to map to some middleware, as you can see we receive the id argument which contains the placeholder value. Using this we load the user and perform error handling as usual, and simple call next() to pass control to the next precondition or route handler.
app.param('userId', function(req, res, next, id){ User.get(id, function(err, user){ if (err) return next(err); if (!user) return next(new Error('failed to find user')); req.user = user; next(); }); });
Doing so, as mentioned drastically improves our route readability, and allows us to easily share this logic throughout our application:
app.get('/user/:userId', function(req, res){ res.send('user ' + req.user.name); });
View filenames take the form "<name>.<engine>", where <engine> is the name of the module that will be required. For example the view layout.ejs will tell the view system to require('ejs'), the module being loaded must export the method exports.compile(str, options), and return a Function to comply with Express. To alter this behaviour app.register() can be used to map engines to file extensions, so that for example "foo.html" can be rendered by ejs.
Below is an example using Jade to render index.html, and since we do not use layout: false the rendered contents of index.jade will be passed as the body local variable in layout.jade.
app.get('/', function(req, res){ res.render('index.jade', { title: 'My Site' }); });
The new view engine setting allows us to specify our default template engine, so for example when using jade we could set:
app.set('view engine', 'jade');
Allowing us to render with:
res.render('index');
vs:
res.render('index.jade');
When view engine is set, extensions are entirely optional, however we can still mix and match template engines:
res.render('another-page.ejs');
To apply application-level locals, or view engine options may be set using app.local() or app.locals(), for example if we don't want layouts for most of our templates we may do:
app.local('layout', false);
Which can then be overridden within the res.render() call if desired, and is otherwise functionally equivalent to passing directly to res.render():
res.render('myview.ejs', { layout: true });
When an alternate layout is required, we may also specify a path. For example if we have view engine set to jade and a file named ./views/mylayout.jade we can simply pass:
res.render('page', { layout: 'mylayout' });
Otherwise we must specify the extension:
res.render('page', { layout: 'mylayout.jade' });
These paths may also be absolute:
res.render('page', { layout: __dirname + '/../../mylayout.jade' });
The Express view system has built-in support for partials and collections, which are "mini" views representing a document fragment. For example rather than iterating in a view to display comments, we could use partial collection:
partial('comment', { collection: comments });
If no other options or local variables are desired, we can omit the object and simply pass our array, which is equivalent to above:
partial('comment', comments);
When using the partial collection support a few "magic" locals are provided for free:
- firstInCollection true if this is the first object
- indexInCollection index of the object in the collection
- lastInCollection true if this is the last object
- collectionLength length of the collection
Local variables passed (or generated) take precedence, however locals passed to the parent view are available in the child view as well. So for example if we were to render a blog post with partial('blog/post', post) it would generate the post local, but the view calling this function had the local user, it would be available to the blog/post view as well.
For documentation on altering the object name view res.partial().
NOTE: be careful about when you use partial collections, as rendering an array with a length of 100 means we have to render 100 views. For simple collections you may inline the iteration instead of using partial collection support to decrease overhead.
View lookup is performed relative to the parent view, for example if we had a page view named views/user/list.jade, and within that view we did partial('edit') it would attempt to load views/user/edit.jade, whereas partial('../messages') would load views/messages.jade.
The view system also allows for index templates, allowing you to have a directory of the same name. For example within a route we may have res.render('users') either views/users.jade, or views/users/index.jade.
When utilizing index views as shown above, we may reference views/users/index.jade from a view in the same directory by partial('users'), and the view system will try ../users/index, preventing us from needing to call partial('index').
Below are a few template engines commonly used with Express:
- Haml haml implementation
- Jade haml.js successor
- EJS Embedded JavaScript
- CoffeeKup CoffeeScript based templating
- jQuery Templates for node
Sessions support can be added by using Connect's session middleware. To do so we also need the cookieParser middleware place above it, which will parse and populate cookie data to req.cookies.
app.use(express.cookieParser()); app.use(express.session({ secret: "keyboard cat" }));
By default the session middleware uses the memory store bundled with Connect, however many implementations exist. For example connect-redis supplies a Redis session store and can be used as shown below:
var RedisStore = require('connect-redis')(express); app.use(express.cookieParser()); app.use(express.session({ secret: "keyboard cat", store: new RedisStore }));
Now the req.session and req.sessionStore properties will be accessible to all routes and subsequent middleware. Properties on req.session are automatically saved on a response, so for example if we wish to shopping cart data:
var RedisStore = require('connect-redis')(express); app.use(express.bodyParser()); app.use(express.cookieParser()); app.use(express.session({ secret: "keyboard cat", store: new RedisStore }));
app.post('/add-to-cart', function(req, res){ // Perhaps we posted several items with a form // (use the bodyParser() middleware for this) var items = req.body.items; req.session.items = items; res.redirect('back'); });
app.get('/add-to-cart', function(req, res){ // When redirected back to GET /add-to-cart // we could check req.session.items && req.session.items.length // to print out a message if (req.session.items && req.session.items.length) { req.notify('info', 'You have %s items in your cart', req.session.items.length); } res.render('shopping-cart'); });
The req.session object also has methods such as Session#touch(), Session#destroy(), Session#regenerate() among others to maintain and manipulate sessions. For more information view the Connect Session documentation.
Express 1.x developers may reference the Migration Guide to get up to speed on how to upgrade your application to work with Express 2.x, Connect 1.x, and Node 0.4.x.
Get the case-insensitive request header key, with optional defaultValue:
req.header('Host'); req.header('host'); req.header('Accept', '/');
The Referrer and Referer header fields are special-cased, either will work:
// sent Referrer: http://google.com
req.header('Referer'); // => "http://google.com"
req.header('Referrer'); // => "http://google.com"
Check if the Accept header is present, and includes the given type.
When the Accept header is not present true is returned. Otherwise the given type is matched by an exact match, and then subtypes. You may pass the subtype such as "html" which is then converted internally to "text/html" using the mime lookup table.
// Accept: text/html req.accepts('html'); // => true
// Accept: text/*; application/json req.accepts('html'); req.accepts('text/html'); req.accepts('text/plain'); req.accepts('application/json'); // => true
req.accepts('image/png'); req.accepts('png'); // => false
Check if the incoming request contains the Content-Type header field, and it contains the give mime type.
// With Content-Type: text/html; charset=utf-8 req.is('html'); req.is('text/html'); // => true
// When Content-Type is application/json req.is('json'); req.is('application/json'); // => true
req.is('html'); // => false
Ad-hoc callbacks can also be registered with Express, to perform assertions again the request, for example if we need an expressive way to check if our incoming request is an image, we can register "an image" callback:
app.is('an image', function(req){
return 0 == req.headers['content-type'].indexOf('image');
});
Now within our route callbacks, we can use to to assert content types such as "image/jpeg", "image/png", etc.
app.post('/image/upload', function(req, res, next){ if (req.is('an image')) { // do something } else { next(); } });
Keep in mind this method is not limited to checking Content-Type, you can perform any request assertion you wish.
Wildcard matches can also be made, simplifying our example above for "an image", by asserting the subtype only:
req.is('image/*');
We may also assert the type as shown below, which would return true for "application/json", and "text/json".
req.is('*/json');
Return the value of param name when present or default.
- Checks route params (req.params), ex: /user/:id
- Checks query string params (req.query), ex: ?id=12
- Checks urlencoded body params (req.body), ex: id=12
To utilize urlencoded request bodies, req.body should be an object. This can be done by using the _express.bodyParser middleware.
Get field's param value, defaulting to '' when the param or field is not present.
req.get('content-disposition', 'filename'); // => "something.png"
req.get('Content-Type', 'boundary'); // => "--foo-bar-baz"
Queue flash msg of the given type.
req.notify('info', 'email sent'); req.notify('error', 'email delivery failed'); req.notify('info', 'email re-sent'); // => 2
req.notify('info'); // => ['email sent', 'email re-sent']
req.notify('info'); // => []
req.notify(); // => { error: ['email delivery failed'], info: [] }
Flash notification message may also utilize formatters, by default only the %s string and %d integer formatters is available:
req.notify('info', 'email delivery to %s from %s failed.', toUser, fromUser);
Argument HTML is escaped, to prevent XSS, however HTML notification format is valid.
Also aliased as req.xhr, this getter checks the X-Requested-With header to see if it was issued by an XMLHttpRequest:
req.xhr req.isXMLHttpRequest
Get or set the response header key.
res.header('Content-Length'); // => undefined
res.header('Content-Length', 123); // => 123
res.header('Content-Length'); // => 123
Sets the charset for subsequent Content-Type header fields. For example res.send() and res.render() default to "utf8", so we may explicitly set the charset before rendering a template:
res.charset = 'ISO-8859-1'; res.render('users');
or before responding with res.send():
res.charset = 'ISO-8859-1'; res.send(str);
or with node's res.end():
res.charset = 'ISO-8859-1'; res.header('Content-Type', 'text/plain'); res.end(str);
Sets the Content-Type response header to the given type.
var filename = 'path/to/image.png'; res.contentType(filename); // Content-Type is now "image/png"
A literal Content-Type works as well:
res.contentType('application/json');
Or simply the extension without leading .:
res.contentType('json');
Sets the Content-Disposition response header to "attachment", with optional filename.
res.attachment('path/to/my/image.png');
Sets the res.statusCode property to code and returns for chaining:
res.status(500).send('Something bad happened');
is equivalent to:
res.statusCode = 500; res.send('Something bad happened');
and:
res.send(500, 'Something bad happened');
Used by res.download() to transfer an arbitrary file.
res.sendfile('path/to/my.file');
This method accepts an optional callback which is called when
an error occurs, or when the transfer is complete. By default failures call next(err), however when a callback is supplied you must do this explicitly, or act on the error.
res.sendfile(path, function(err){ if (err) { next(err); } else { console.log('transferred %s', path); } });
Options may also be passed to the internal fs.createReadStream() call, for example altering the bufferSize:
res.sendfile(path, { bufferSize: 1024 }, function(err){ // handle });
Transfer the given file as an attachment with optional alternative filename.
res.download('path/to/image.png'); res.download('path/to/image.png', 'foo.png');
This is equivalent to:
res.attachment(file); res.sendfile(file);
An optional callback may be supplied as either the second or third argument, which is passed to res.sendfile(). Within this callback you may still respond, as the header has not been sent.
res.download(path, 'expenses.doc', function(err){ // handle });
An optional second callback, callback2 may be given to allow you to act on connection related errors, however you should not attempt to respond.
res.download(path, function(err){ // error or finished }, function(err){ // connection related error });
The res.send() method is a high level response utility allowing you to pass objects to respond with json, strings for html, Buffer instances, or numbers representing the status code. The following are all valid uses:
res.send(new Buffer('wahoo')); res.send({ some: 'json' }); res.send(201, { message: 'User created' }); res.send('
some html
'); res.send(404, 'Sorry, cant find that'); res.send(404); // "Not Found" res.send(500); // "Internal Server Error"The Content-Type response header is defaulted appropriately unless previously defined via res.header() / res.contentType() etc.
Note that this method _end()_s the response, so you will want to use node's res.write() for multiple writes or streaming.
Send an explicit JSON response. This method is ideal for JSON-only APIs, while it is much like res.send(obj), send is not ideal for cases when you want to send for example a single string as JSON, since the default for res.send(string) is text/html.
res.json(null); res.json({ user: 'tj' }); res.json(500, 'oh noes!'); res.json(404, 'I dont have that');
Redirect to the given url with a default response status of 302.
res.redirect('/', 301); res.redirect('/account'); res.redirect('http://google.com'); res.redirect('home'); res.redirect('back');
Express supports "redirect mapping", which by default provides home, and back. The back map checks the Referrer and Referer headers, while home utilizes the "home" setting and defaults to "/".
Sets the given cookie name to val, with options httpOnly, secure, expires etc. The path option defaults to the app's "home" setting, which is typically "/".
// "Remember me" for 15 minutes res.cookie('rememberme', 'yes', { expires: new Date(Date.now() + 900000), httpOnly: true });
The maxAge property may be used to set expires relative to Date.now() in milliseconds, so our example above can now become:
res.cookie('rememberme', 'yes', { maxAge: 900000 });
To parse incoming Cookie headers, use the cookieParser middleware, which provides the req.cookies object:
app.use(express.cookieParser());
app.get('/', function(req, res){ // use req.cookies.rememberme });
Clear cookie name by setting "expires" far in the past. Much like res.cookie() the path option also defaults to the "home" setting.
res.clearCookie('rememberme');
Render view with the given options and optional callback fn. When a callback function is given a response will not be made automatically, however otherwise a response of 200 and text/html is given.
The options passed are the local variables as well, for example if we want to expose "user" to the view, and prevent a local we do so within the same object:
var user = { name: 'tj' }; res.render('index', { layout: false, user: user });
This options object is also considered an "options" object. For example when you pass the status local, it's not only available to the view, it sets the response status to this number. This is also useful if a template engine accepts specific options, such as debug, or compress. Below is an example of how one might render an error page, passing the status for display, as well as it setting res.statusCode.
res.render('error', { status: 500, message: 'Internal Server Error' });
Render view partial with the given options. This method is always available to the view as a local variable.
- object the object named by as or derived from the view name
- as Variable name for each collection or object value, defaults to the view name.
- as: 'something' will add the something local variable
- as: this will use the collection value as the template context
- as: global will merge the collection value's properties with locals
- collection Array of objects, the name is derived from the view name itself. For example video.html will have a object video available to it.
The following are equivalent, and the name of collection value when passed to the partial will be movie as derived from the name.
partial('theatre/movie.jade', { collection: movies }); partial('theatre/movie.jade', movies); partial('movie.jade', { collection: movies }); partial('movie.jade', movies); partial('movie', movies); // In view: movie.director
To change the local from movie to video we can use the "as" option:
partial('movie', { collection: movies, as: 'video' }); // In view: video.director
Also we can make our movie the value of this within our view so that instead of movie.director we could use this.director.
partial('movie', { collection: movies, as: this }); // In view: this.director
Another alternative is to "expand" the properties of the collection item into pseudo globals (local variables) by using as: global, which again is syntactic sugar:
partial('movie', { collection: movies, as: global }); // In view: director
This same logic applies to a single partial object usage:
partial('movie', { object: movie, as: this }); // In view: this.director
partial('movie', { object: movie, as: global }); // In view: director
partial('movie', { object: movie, as: 'video' }); // In view: video.director
partial('movie', { object: movie }); // In view: movie.director
When a non-collection (does not have .length) is passed as the second argument, it is assumed to be the object, after which the object's local variable name is derived from the view name:
var movie = new Movie('Nightmare Before Christmas', 'Tim Burton') partial('movie', movie) // => In view: movie.director
The exception of this, is when a "plain" object, aka "{}" or "new Object" is passed, which is considered an object with local variable. For example some may expect a "movie" local with the following, however since it is a plain object "director" and "title" are simply locals:
var movie = { title: 'Nightmare Before Christmas', director: 'Tim Burton' }; partial('movie', movie)
For cases like this where passing a plain object is desired, simply assign it to a key, or use the object key which will use the filename-derived variable name. The examples below are equivalent:
partial('movie', { locals: { movie: movie }}) partial('movie', { movie: movie }) partial('movie', { object: movie })
This exact API can be utilized from within a route, to respond with a fragment via Ajax or WebSockets, for example we can render a collection of users directly from a route:
app.get('/users', function(req, res){ if (req.xhr) { // respond with the each user in the collection // passed to the "user" view res.partial('user', users); } else { // respond with layout, and users page // which internally does partial('user', users) // along with other UI res.render('users', { users: users }); } });
Get or set the given local variable name. The locals built up for a response are applied to those given to the view rendering methods such as res.render().
app.all('/movie/:id', function(req, res, next){ Movie.get(req.params.id, function(err, movie){ // Assigns res.locals.movie = movie res.local('movie', movie); }); });
app.get('/movie/:id', function(req, res){ // movie is already a local, however we // can pass more if we wish res.render('movie', { displayReviews: true }); });
Assign several locals with the given obj. The following are equivalent:
res.local('foo', bar); res.local('bar', baz);
res.locals({ foo: bar, bar, baz });
Apply an application level setting name to val, or get the value of name when val is not present:
app.set('views', __dirname + '/views'); app.set('views'); // => ...path...
Alternatively you may simply access the settings via app.settings:
app.settings.views // => ...path...
Enable the given setting name:
app.enable('some arbitrary setting'); app.set('some arbitrary setting'); // => true
app.enabled('some arbitrary setting'); // => true
Check if setting name is enabled:
app.enabled('view cache'); // => false
app.enable('view cache'); app.enabled('view cache'); // => true
Disable the given setting name:
app.disable('some setting'); app.set('some setting'); // => false
app.disabled('some setting'); // => false
Check if setting name is disabled:
app.enable('view cache');
app.disabled('view cache'); // => false
app.disable('view cache'); app.disabled('view cache'); // => true
Define a callback function for the given env (or all environments) with callback function:
app.configure(function(){ // executed for each env });
app.configure('development', function(){ // executed for 'development' only });
For use with res.redirect() we can map redirects at the application level as shown below:
app.redirect('google', 'http://google.com');
Now in a route we may call:
res.redirect('google');
We may also map dynamic redirects:
app.redirect('comments', function(req, res){ return '/post/' + req.params.id + '/comments'; });
So now we may do the following, and the redirect will dynamically adjust to the context of the request. If we called this route with GET /post/12 our redirect Location would be /post/12/comments.
app.get('/post/:id', function(req, res){ res.redirect('comments'); });
When mounted, res.redirect() will respect the mount-point. For example if a blog app is mounted at /blog, the following will redirect to /blog/posts:
res.redirect('/posts');
Registers static view locals.
app.locals({ name: function(first, last){ return first + ', ' + last } , firstName: 'tj' , lastName: 'holowaychuk' });
Our view could now utilize the firstName and lastName variables, as well as the name() function exposed.
<%= name(firstName, lastName) %>
Express also provides a few locals by default:
settingsthe app's settings objectlayout(path)specify the layout from within a view
Registers dynamic view locals. Dynamic locals are simply functions which accept req, res, and are evaluated against the Server instance before a view is rendered, and are unique to that specific request. The return value of this function becomes the local variable it is associated with.
app.dynamicLocals({ session: function(req, res){ return req.session; } });
All views would now have session available so that session data can be accessed via session.name etc:
<%= session.name %>
The app.lookup http methods returns an array of callback functions associated with the given path.
Suppose we define the following routes:
app.get('/user/:id', function(){}); app.put('/user/:id', function(){}); app.get('/user/:id/:op?', function(){});
We can utilize this lookup functionality to check which routes have been defined, which can be extremely useful for higher level frameworks built on Express.
app.lookup.get('/user/:id'); // => [Function]
app.lookup.get('/user/:id/:op?'); // => [Function]
app.lookup.put('/user/:id'); // => [Function]
app.lookup.all('/user/:id'); // => [Function, Function]
app.lookup.all('/hey'); // => []
To alias app.lookup.VERB(), we can simply invoke app.VERB() without a callback, as a shortcut, for example the following are equivalent:
app.lookup.get('/user'); app.get('/user');
Each function returned has the following properties:
var fn = app.get('/user/:id/:op?')[0];
fn.regexp // => /^/user/(?:([^\/]+?))(?:/([^\/]+?))?/?$/i
fn.keys // => ['id', 'op']
fn.path // => '/user/:id/:op?'
fn.method // => 'GET'
The app.match http methods return an array of callback functions which match the given url, which may include a query string etc. This is useful when you want reflect on which routes have the opportunity to respond.
Suppose we define the following routes:
app.get('/user/:id', function(){});
app.put('/user/:id', function(){});
app.get('/user/:id/:op?', function(){});
Our match against GET will return two functions, since the :op in our second route is optional.
app.match.get('/user/1'); // => [Function, Function]
This second call returns only the callback for /user/:id/:op?.
app.match.get('/user/23/edit'); // => [Function]
We can also use all() to disregard the http method:
app.match.all('/user/20'); // => [Function, Function, Function]
Each function matched has the following properties:
var fn = app.match.get('/user/23/edit')[0];
fn.keys // => ['id', 'op']
fn.params // => { id: '23', op: 'edit' }
fn.method // => 'GET'
Assign a callback fn which is called when this Server is passed to Server#use().
var app = express.createServer(), blog = express.createServer();
blog.mounted(function(parent){ // parent is app // "this" is blog });
app.use(blog);
Register the given template engine exports as ext. For example we may wish to map ".html" files to jade:
app.register('.html', require('jade'));
This is also useful for libraries that may not match extensions correctly. For example my haml.js library is installed from npm as "hamljs" so instead of layout.hamljs, we can register the engine as ".haml":
app.register('.haml', require('haml-js'));
For engines that do not comply with the Express specification, we can also wrap their api this way. Below we map .md to render markdown files, rendering the html once since it will not change on subsequent calls, and support local substitution in the form of "{name}".
app.register('.md', { compile: function(str, options){ var html = md.toHTML(str); return function(locals){ return html.replace(/{([^}]+)}/g, function(_, name){ return locals[name]; }); }; } });
Bind the app server to the given port, which defaults to 3000. When host is omitted all connections will be accepted via INADDR_ANY.
app.listen(); app.listen(3000); app.listen(3000, 'n.n.n.n');
The port argument may also be a string representing the path to a unix domain socket:
app.listen('/tmp/express.sock');
Then try it out:
$ telnet /tmp/express.sock GET / HTTP/1.1
HTTP/1.1 200 OK Content-Type: text/plain Content-Length: 11
Hello World