The package.json file is a set of meta data about a theme.


The package.json file is a required file and sets some information about your theme. Edit this file and keep it up to date with the relevant information about your publication's theme.

To reference a working example of a package.json file, review the Casper file, and for further information about specific details of package.json handling, read the npm docs.


    "name": "your-theme-name",
    "description": "A brief explanation of your theme",
    "version": "0.5.0",
    "engines": {
        "ghost-api": "v3"
    "license": "MIT",
    "author": {
        "email": ""
    "config": {
        "posts_per_page": 10,
        "image_sizes": {}

The data in the file must be valid JSON, including double quotes around all property names. Every property except the last one should be separated by a comma.

Additional properties

Here are some of the most common optional properties that can be used in the package.json file:

  • config.posts_per_page - the default number of posts per page is 5, or you can set a custom amount with this property
  • config.image_sizes - read the responsive images guide for more details
  • engines.ghost-api - indicate what version of the Ghost Content API your theme is compatible with, defaults to v0.1
  • description - provide a short description about your theme and what makes it unique
  • license - a valid licence string, we recommend MIT 😉

Changes to the package.json require a restart, use the command ghost restart to do so.

Next steps

This concludes the introduction to and overview of Ghost themes. The rest of this documentation explores how contexts and helpers work, and provides a full reference list of available helpers to guide your theme development.

For community led support about theme development, visit the forum.