KeystoneJS is a powerful new Node.js content management system and web app framework built on express and mongoose that makes it easy to create sophisticated web sites and apps, and gives you a beautiful, auto-generated Admin UI.
To get started, check out keystonejs.com!
Keystone gives you:
- A simple way to create an Express web app with custom routes, templates and models
- Out of the box session management and authentication
- Enhanced
modelswith additional field types and functionality, building on those natively supported by Mongoose - An updates framework for managing data updates or initialisation
- A beautiful Admin UI based on the defined
models - Integration with Cloudinary for image uploading, storage and resizing
- Integration with Mandrill for sending emails easily
- Integration with Embedly for powerful video and rich media embedding tools
Getting Started guide & documentation can be found at keystonejs.com/guide
To see a working demo of Keystone, visit demo.keystonejs.com
View the example project to see how to set up a simple Keystone app.
Discuss on the KeystoneJS Google Group
For an example of how to set up a more sophisticated website with Keystone, check out the SydJS Website and source code.
KeystoneJS is a big vision, and we'd love all the help we can get realising it.
Please feel free to contribute by reporting issues, discussing ideas, or submitting pull requests with patches and new features. We do our best to respond to all issues and pull requests within a day or two, and make patch releases to npm regularly.
We're also interested in hearing feedback about projects you're using Keystone for, and while we're working on better guides and documentation, are happy to give advice if you get stuck.
If you're going to contribute code, please try and mimic the existing code standards - we follow AirBNB's Javascript Style Guide fairly closely, with the exception of using tab indentation.
Check out the KeystoneJS getting started guide for a walk-through on how to use KeystoneJS.
The documentation is a work in progress, so it's also worth checking out the example projects.
Follow @keystonejs on twitter for updates.
Feel free to clone the demo site and use it as the basis for your own project.
npm install keystone
Then:
requireit in your web.js (or app.js, etc)- initialise it with configuration variables
- define your lists (similar to mongoose models)
- set up your routes
- start it
Keystone will automatically set up Express and Mongoose, although you can provide your own versions and have explicit control over your application configuration (see advanced usage, below).
If you want to test or develop against the master branch of KeystoneJS (or against your own branch), rather than a published version on npm, you just need to check it out then use npm link to link it to your project. On Mac OS, this is done like this:
- Checkout KeystoneJS locally, e.g. to
~/Development/KeystoneJS - From the KeystoneJS directory, run
sudo npm link(you will need to enter your system password) - From your project directory, e.g.
~/Development/MySite(the one with yourpackage.jsonfile in it) runnpm link keystone. This will create a link between~/Development/MySite/node_modules/keystoneand~/Development/KeystoneJS.
Then require('keystone') normally in your app - the development copy will be used. Note that running npm update will ignore new versions of keystone that have been published.
To go back to using a published version of KeystoneJS from npm, from your project directory, run npm unlink keystone then npm install.
If you want, Keystone can take care of everything required to set up your express app and then start it for you.
var keystone = require('keystone');
keystone.init({
'name': 'My Project',
'brand': 'Project Admin',
'favicon': 'public/favicon.ico',
'less': 'public',
'static': 'public',
'views': 'templates/views',
'view engine': 'jade',
'auto update': true,
'mongo': process.env.MONGOLAB_URI || 'mongodb://localhost/my-project',
'auth': true,
'user model': 'User',
'cookie secret': '--- your secret ---',
'emails': 'templates/emails',
'mandrill api key': '--- your api key ---',
'email rules': { find: '/images/', replace: (keystone.get('env') != 'production') ? 'http://localhost:3000/images/' : 'http://www.keystonejs.com/images/email/' },
'cloudinary config': { cloud_name: '--- your cloud name ---', api_key: '--- your api key ---', api_secret: '--- your api secret ---' }
});
require('./models');
keystone.set('routes', require('./routes'));
keystone.start();
Config variables can be passed in an object to the keystone.init method, or can be set any time before keystone.start is
called using keystone.set(key, value). This allows for a more flexible order of execution (e.g. if you refer to Lists in your
routes, you can set the routes after configuring your Lists, as in the example above).
See the KeystoneJS configuration documentation for details and examples of the available configuration options.
To understand how these settings are used, and how the Express application initialised, see Keystone.prototype.start in
/index.js.
Keystone builds on the basic data types provided by mongo and allows you to easily add rich, functional fields to your application's models.
You get helper methods on your models for dealing with each field type easily (such as formatting a date or number, resizing an image, getting an array of the available options for a select field, or using Google's Places API to improve addresses) as well as a beautiful, responsive admin UI to edit your data with.
See the KeystoneJS database documentation for details and examples of the various field types, as well as how to set up and use database models in your application.
Keystone's field types include:
- Boolean
- Text
- Textarea
- Url
- Html
- Date
- Datetime
- Key
- Number
- Money
- Select
- Markdown
- Name
- Password
- Location
- CloudinaryImage
- CloudinaryImages
- S3 File
- Embedly
Keystone also has Relationship fields for managing one-to-many and many-to-many relationships between different models.
When you first require Keystone, it creates a single instance of itself. Do this somewhere
near the top of your app.js (or web.js, etc) file. Any subsequent require('keystone')
statements will return the same instance of Keystone.
Keystone can be locked down with the auth config. This must be a function matching the
express middleware pattern fn(req,res,next). It will be called before any Keystone
routes are matched. If the user fails the validation check they should be redirected to
a signin or access-denied page implemented in the application.
The NODE_ENV environment variable is used to control template caching and html formatting,
and should be set to production for production environments.
It is also possible to integrate keystone into an existing express app, without using the start
method. This assumes less about your app and provides a lot of flexibility.
You can provide a mongoose or express instance to Keystone's connect function before defining
any lists. connect returns this so you can do this in the require call.
keystone.static(app) adds Keystone's static route-handling middleware to the Express
app. It's a good idea to do this after your application's other static assets, before
any dynamic logic (e.g. cookie parsing, session authentication, body parsing, etc)
keystone.routes(app); adds Keystone's dynamic routes to the Express app router. This
can be done before or after your application's routes are defined, although if they come
after, you can explicitly lock down or replace Keystone routes with your own (so be careful).
A massive thanks to the people & projects that have been the foundation of Keystone or helped during its development, including
- Node.js, obviously :)
- ExpressJS (the webserver for node.js)
- MongoDB (for the great database)
- Mongoose (for the ODM that makes this easier)
- Bootstrap (for the great css framework, you guys make clean, responsive UI easy)
- Cloudinary (for the amazing image service)
- Embedly (for the great api)
- Google (for the maps)
- Heroku (for the servers)
- jQuery (of course)
- Underscore.js (for making javascript better)
- Yusuke Kamiyamane (for some of the icons)
(The MIT License)
Copyright (c) 2013 Jed Watson
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the 'Software'), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.