Prerequisites
Before getting started, you’ll need these global packages to be installed:- A supported version of Node.js - Ideally installed via nvm
- Yarn - to manage all the packages
- Docker (ie. Docker Desktop) - to run the MySQL database and other services
Create GitHub fork
First you’ll need to make a fork of the Ghost repository. Click on the fork button right at the top, wait for a copy to be created over on your personal GitHub account, and you should be all set!
Configure repository
The main Ghost repository is a monorepo containing the full Ghost code, including the Admin client and default theme which will also be automatically set upProperly rename your references
If you’re part of the Ghost core team, you don’t need to do this, as you can push straight toTryGhost/Ghost
.
Run setup & installation
setup
task will install dependencies, initialise the database, set up git hooks, and initialise submodules.
Start Ghost
Stay up to date
When your working copies become out of date due to upstream changes, this is the command that brings you back up to the latestmain
Dev Commands
When running locally there are a number development utility commands which come in handy for running tests, building packages, and other helpful tasks.Running Ghost
The most commonly used commands for running the core codebase locallyDatabase tools
Ghost uses its own tool calledknex-migrator
to manage database migrations.
Building Ghost from source
From the top-level directory of the monorepo, runghost-<version>.tgz
, which can be installed with Ghost-CLI’s --archive
flag.
Server Tests
Tests run with SQLite. To use MySQL, prepend commands withNODE_ENV=testing-mysql
Client Tests
Client tests should always be run inside theghost/admin
directory. Any time you have yarn dev
running the client tests will be available at http://localhost:4200/tests
Troubleshooting
Some common Ghost development problems and their solutions ERROR: (EADDRINUSE) Cannot start GhostThis error means that Ghost is already running, and you need to stop it. ERROR: ENOENT
This error means that the mentioned file doesn’t exist. ERROR Error: Cannot find module
Install did not complete. Run
yarn fix
.
Error: Cannot find module ‘./build/default/DTraceProviderBindings’You switched node versions. Run
yarn fix
.
ENOENT: no such file or directory, stat ‘path/to/favicon.ico’ at Error (native)Your admin client has not been built. Run
yarn dev
.
TypeError: Cannot read property ’tagName’ of undefinedYou can’t run
ember test
at the same time as yarn dev
. Wait for tests to finish before continuing and wait for the “Build successful” message before loading admin.
yarn.lock conflictsWhen rebasing a feature branch it’s possible you’ll get conflicts on
yarn.lock
because there were dependency changes in both main
and <feature-branch>
.
- Note what dependencies have changed in
package.json
(Eg.dev-1
was added and dev depdev-2
was removed) git reset HEAD package.json yarn.lock
- unstages the filesgit checkout -- package.json yarn.lock
- removes local changesyarn add dev-1 -D
- re-adds the dependency and updates yarn.lockyarn remove dev-2
- removes the dependency and updates yarn.lockgit add package.json yarn.lock
- re-stage the changesgit rebase --continue
- continue with the rebase
yarn
auto-generate the lockfile rather than trying to manually merge potentially incompatible changes.