Using Ghost as an NPM module

You can now use Ghost as an npm module!

BREAKING CHANGE

The API for using Ghost as an npm module is changing in 0.5.2.

Calling ghost() will no longer start an express server. If you have setup Ghost this way with Ghost <0.5.2 you will need to change the code that calls the module. The new API signature is:

var ghost = require('ghost');
ghost().then(function (ghostServer) {
    ghostServer.start();
});

This documentation will be updated with more details closer to the release.

Using Ghost as an npm module

1. Include Ghost as a dependency in your package.json file

"dependencies": {
    "ghost": "0.5.2"
}

2. Run npm install to install Ghost.

3. Include the Ghost module where desired and then invoke it to get a promise for a ghostServer object.

var ghost = require('ghost');
ghost().then(function (ghostServer) {
    ghostServer.start();
});

At this point Ghost should be running!

GhostServer API

The GhostServer object returned by the ghost() promise has the following API:

Properties

.rootApp

The base Ghost express instance which has all of Ghost's middleware and configuration mounted on it.

.config

Reference to the Ghost config module

Methods

.start([express instance])

Starts a server listening for requests on the host & port or socket configured in config.js.

• Takes: an optional express instance (should have Ghost mounted on it)
• Returns: a promise which resolves with the ghostServer instance once the server has successfully started

.stop()

Stops the server

• Returns: a promise which resolves with the ghostServer instance once the server has successfully stopped

.restart()

• Returns: a promise which resolves with the ghostServer instance once the server has successfully restarted

Example customizations

Mount Ghost on a subdirectory

Ghost's default index.js uses this feature to add subdirectory support to Ghost. It is possible to create a parent express instance, call .use to add your own middleware and configuration, and then tell the ghostServer to start Ghost with your new parent app.

var ghost = require('ghost'),
    express = require('express'),
    parentApp = express();

ghost().then(function (ghostServer) {
    parentApp.use(ghostServer.config.paths.subdir, ghostServer.rootApp);

    ghostServer.start(parentApp);
});

In this snippet there are two express instances - parentApp can be your own express instance containing all of your own configuration and rootApp is the express instance you'll get from ghostServer which has all of Ghost's behaviour and configuration.

The line parentApp.use(ghostServer.config.paths.subdir, ghostServer.rootApp); mounts Ghost on a subdirectory inside the existing express app.

ghostServer.config.paths.subdir contains the subdirectory specified via the url property in config.js. For example, configuring url: 'http://localhost:2368/blog' will run Ghost under /blog. The property ghostServer.config.paths.subdir will equal /blog.

Note: If you pass an express instance to ghostServer.start which has not had the Ghost rootApp mounted on it (i.e. you haven't called .use()), then ghostServer will still start a server but it will not have Ghost's functionality.

Decide where the content/ directory should exist

By default Ghost will use the content/ directory that exists inside the module. To modify where Ghost's content/ directory should exist you can pass in a JS object into the ghost() function. For sake of easy maintenance you can also pass in a JSON file:

ghost({
config: path.join(__dirname, 'config.js')
});

An example config.js is based off the config.example.js.

The configuration property that changes the content/ location is:

paths: {
  contentPath: path.join(__dirname, 'content'),
}

Modify that to change where the content/ directory should exist.

NOTE: If you change the location of the content/ directory Ghost expects to find the same directory structure that exists in the module. To get started copy the default content directory structure as the basis for your custom content/ location.