November helps you generate a simple Node.js API tailored for Ember.js apps, with the help of Express and Sequelize.
Installation
$ npm install -g november-cli
Get started
$ november new my-app
This will create a new project with the following structure:
├── app
│ ├── actions
│ ├── controllers
│ ├── middleware
│ ├── models
│ ├── router.js
│
├── config
│ ├── config.json
│
├── lib
├── migrations
├── node_modules
├── public
├── server.js
├── test
By default, MySQL is used as a database, but you can use any relational database supported by Sequelize by changing the values in config/config.json
.
To run the app, run npm start
(or just nodemon
if you have it installed) in your app’s directory and visit localhost:9000
.
In your Ember.js app
Make sure you change the host in your Ember.js adapter file so that it can communicate with November:
# In your ember project folder $ ember generate adapter
// app/adapters/application.js; RESTAdapter;
Models
$ november generate model user
This generates:
- A model file (
app/models/user.js
) for the user, which will determine the structure of the database table - Routes in
app/router.js
for creating, reading, updating and deleting users (based on the conventions of Ember Data). Feel free to remove the actions you don't need. - Controller files, which hook up the routes to database actions:
app/controllers/user/add.js
app/controllers/user/list.js
app/controllers/user/load.js
app/controllers/user/update.js
app/controllers/user/remove.js
With the app and your local database running in the background, visit localhost:9000/users
, and you should see:
The table users
has automatically been created in your database.
Actions
Actions are for API endpoints which are not specifically tied to any model.
$ november generate action login
This generates:
- An action file (
app/actions/login.js
) - A route in
app/router.js
(POST
by default)
Render()
The render()
-method in your controllers is used for rendering both your models and your error messages. It takes a single argument.
Rendering models
If you pass a valid sequelize model to render()
, it will generate that model according to the JSON API conventions used by Ember Data.
The most basic usage:
render(<your-sequelize-model>);
...which can also be typed like this:
render({
model: <your-sequelize-model>
});
returns:
"user": <...>
If your sequelize model includes associated models, they are sideloaded by default:
"user": <...> "tweets": 1 5 "tweets": <...>
However, you can also specify if you want some (or all) associations to be embedded instead.
Here we specify that we want the tweets-association to be embedded. If we wanted all associations to be embedded, we would set embedded: true
;
... which returns:
"user": <...> "tweets": id: 1 <...> id: 5 <...>
Rendering errors
Controllers generated by November rely heavily on promises. If they catch an error, they call render(error)
.
Let's say we accidentally search for a field (name
) which doesn't exist in our database table:
// app/controllers/user/list.jsreqmodelsuser;
An error will be catched and render(err)
will return this JSON to the client:
... while still showing a more descriptive error to the developer in the console so that you can locate the problem:
You can also render your own exceptions to the user, by throwing a string with the error message or an array where the first element is the error code and the second is the error message:
// app/controllers/user/update.jsreqmodelsuser;
...what the client will see:
Todos
TDD is not really my thing, but it would be nice to get some automatic Mocha tests when you generate new models. :)
Contact
If you have any questions, feel free to ping me on Twitter or just open an issue!