Next.js / Ghost Tutorial: 3 - Creating Next.js project and code repository
Now that we have our development environment in place, it's time to create the project with the required React and Next.js dependencies and finally begin to code our solution. In addition, a remote code repository will be created on Github, to be used throughout this tutorial.
We will deliberately not use create-react-app to scaffold our project but instead manually create all the project folders and files as well as link the required dependencies in order to keep the solution lean while hopefully gaining a better understanding of the bare minimum required to start any project with React and Next.js.
Let's do it!
Start by creating a new folder, move inside and initialize npm:
mkdir nextjs-ghost-tutorial
cd nextjs-ghost-tutorial
npm init
Once asked, choose a package name, version and description or accept the default values. We will modify some of them later.
Next, we will install Next.js (no pun intended) as well as the required React and React-dom packages.
npm install next react react-dom
You should now have a file named package-json and a folder node_modules in your project folder.
It is now time to open the project folder with your preferred code editor (for this tutorial I'm using Visual Studio code). From the command prompt, enter:
code .
The "scripts" section
Modify the scripts section inside package.json to look like this:
"scripts": {
"dev": "NODE_OPTIONS='--inspect' next dev",
"build": "next build",
"start": "next start",
"export": "next export"
},
The node option '--inspect' within "dev" serves debug and code profiling purposes and is optional. It can therefore be left out in which case it would look like this instead:
"dev": "next dev"
Now, install the official javacript Ghost Content API:
npm install @tryghost/content-api
If you go check the dependencies section inside package.json, you will find the following entry (version number may differ):
"@tryghost/content-api": "^1.4.10",
In the top level project folder, create the subfolder "pages" and inside there, create a new file named index.js with the following content:
function Home() {
return <div>Welcome at ghost next.js tutorial</div>
}
export default Home
Create another top-level folder named api with a new file named posts.js containing the following code line:
import GhostContentAPI from "@tryghost/content-api";
Your project folder structure should now look like this:
Let's launch the application for the first time to make sure everything works as expected:
npm run dev
If everything goes well, you should get "ready - started server on http://localhost:3000"
Point your browser to the url (don't forget to include the port) and you should see the welcome message from index.js.
Tip: Hit CTRL+C to stop the development server
Setup a remote code repository on GitHub
Before proceeding, this is a good time to create a version control repository for the project. Although this is not mandatory (depending on the deploy procedure it might be required though) I strongly recommend you to do so.
While I use GitHub and the instructions in this guide are tailored to it, you can of course use whatever source code repository plattform you are most familiar with.
I won't go into detail about Git, as that is clearly beyond the scope of this tutorial, but fortunately the Internet is full of useful tutorials on the subject (see also Further reading at the bottom of this post).
Step 1 - Login with your GitHub account and create a new repository with a name of your choice (you may choose to set it Public or Private):
Step 2 - Back on your local machine, enter the following commands at the top level of your project folder:
git init
git checkout -b main
Tip: The second command is used to ensure that the local branche is named "main" in consistency with the one GitHub just created on Step 1
Step 3 - We need to tell git to ignore some files, i.e. not to synchronize them with the remote repository, either because they are useless outside our local development environment, contain sensitive information such as passwords, API keys, etc., or because they will be dynamically installed/generated during the building procedure.
To do so, still in the top folder of your project, create the file ".gitignore" (notice the preceding ".") and add the following lines:
# dependencies
/node_modules
/.pnp
.pnp.js
# testing
/coverage
# next.js
/.next/
/out/
# production
/build
# misc
.DS_Store
*.pem
# debug
npm-debug.log*
yarn-debug.log*
yarn-error.log*
# local env files
.env.local
.env.development.local
.env.test.local
.env.production.local
# vercel
.vercel
Step 4 - Add the (not previously excluded) files to your local repository:
git add .
Step 5 - Do a inital commit. The -m flag provides a message to identify the commit and can be whatever you want:
git commit -m "Initial commit"
Step 6 - Go back to your browser and copy the remote repository URL:
Step 7 - To add the remote repository to your local git folder, paste the URL from step 6 and check if it has been stored correctly:
git remote add origin https://YOUR_URL
git remote -v
Step 8 - Finally, push the commited files to your repository on GitHub:
git push -f origin main
That was it! You should now have a working Next.js project and a code repository in place to be able to mess around with your code without regrets.
For praise, blame or suggestions for improvement:
Filipe Matos