Gatsby Wordpress Typescript Blog Boilerplate
MIT License
This is an opinionated starter project to help you create lightning fast PWA websites with Gatsby and Wordpress CMS, built using Typescript, SCSS and Ant Design.
https://gatsby-wordpress-typescript-scss-blog.netlify.com/
This Gatsby starter template comes with 2 environments, one for development and testing, and another for production. This allows you to use different tokens, API URL's, social account id's etc as needed for your development, testing and production environments. The environment variables defined are as follows:
GATSBY_GITHUB_USER (Mandatory) This is the username of your Github account
GATSBY_GITHUB_REPO (Mandatory) This is the Github repository URL
GATSBY_SITE_NAME (Mandatory) This is the title of the generated Gatsby site
GATSBY_SITE_DESCRIPTION (Mandatory) This is the description of the generated Gatsby site
GATSBY_SITE_URL_PATH (Mandatory)
This is the URL where you will be deploying the generated Gatsby site, but without the http protocol
For example mywebsite.com
or localhost:8000
GATSBY_SITE_URL_PROTOCOL (Mandatory)
This is the http protocol of the URL where you will be deploying the generated Gatsby site, i.e. http
or https
GATSBY_WORDPRESS_URL_PATH (Mandatory)
This is the URL of your wordpress site from where you will fetch your posts/pages etc, but without the http protocol
For example mywebsite-wordpress.com
or localhost:8001
GATSBY_WORDPRESS_URL_PROTOCOL (Mandatory)
This is the http protocol of the URL of your wordpress site from where you will fetch your posts/pages etc, i.e. http
or https
GATSBY_SITE_AUTHOR This is the name of the Gatsby site author
GATSBY_ENABLE_COMMENTS (Optional)
This is a feature switch flag. If it's set to 1
, comment form will be displayed on all your blog posts. If this is not defined or it's value is anything other than 1
then commenting will be disabled on the website. Check out the documentation on Comments
section below.
GATSBY_PRIMARY_ACCENT_COLOR (Optional) This is the primary accent color of your website, which will be used as the theme color in your web manifest file.
GATSBY_INSTAGRAM_SOURCE (Optional)
This is the name of the Instagram account whose feed you want to display on your website.
Note: Do not include the @
symbol here.
GATSBY_TWITTER_SOURCE (Optional)
This is the handle of the Twitter account whose timeline/follow button you want to display on your website.
Note: Do not include the @
symbol here.
GATSBY_FACEBOOK_SOURCE (Optional)
This is the name of the Facebook account/page whose timeline/like button you want to display on your website.
Note: Do not include the @
symbol here.
GATSBY_GOOGLE_ANALYTICS (Optional) This is your Google Analytics tracking id.
GATSBY_STATICMAN_BASE (Optional) This is the base URL of the of your Staticman instance. You can use either the public Staticman instance or host your own. Note: This is required to enable comments on the website.
Note: Any new environment variables you want to define MUST have the GATSBY_
prefix. You can access them using process.env.GATSBY_MY_ENVIRONMENT_VARIABLE
. Also, process.env
object cannot be de-structured. To access any variable from this object, use the full variable name.
For example, the following code will NOT work.
const { GATSBY_MY_ENVIRONMENT_VARIABLE } = process.env;
Install Docker on your machine
Use the included docker-compose.yml file in this repository to setup Wordpress on your local machine by using the command docker-compose up -d
(Have a look at Docker's documentation for more details)
This will create a dockerized wordpress installation on your machine, which you can access here http://localhost:8001
As given in the docker-compose.yml file, your credentials are the following by default (make sure you change these credentials before deploying anything to production)
wordpress
wordpress
wordpress
wordpress
Once you're done setting up and installing Wordpress, you will see the Wordpress admin dashboard. Go to plugins, and add the following plugins
Advanced Custom Fields
ACF to REST API
Note: After installing these 2 plugins
Day and name
or Month and name
option as your permalink structure and click Save.ACF to REST API
setting just below the permalinks, select v2
from the Request Version
menuYoast SEO
Yoast to REST API
ACF Content Analysis for Yoast SEO
At this point you have a fully functional Wordpress blog setup, but you haven't added any posts to it. If you type gatsby develop
in your terminal in the project directory at this point, there won't be any posts or pages for Gatsby to pull. If you want to copy the example blog posts that I have used in the demo for this Gatsby starter template, follow these instructions
All-in-One WP Migration
by going Wordpress Admin Dashboard to http://localhost:8001/wp-admin -> Plugins -> Add New, and then activate this plugin.Import
-> Import From
-> File
localhost.wpress
from the root folder of this repository.If you're planning to use an already existing Wordpress blog as your CMS instead of setting everything up on your local machine, then simply ignore the instructions given in the section above. You might still want to consider installing the Wordpress plugins recommended above if you haven't already.
This Gatsby starter template uses Ant Design for theming and UI. Although, it's not mandatory to use it for any new visual components that you might create. Feel free to build everything from scratch or use any other UI framework of your choice.
The integration steps mentioned on the official documentation are very outdated. You can follow the instructions below to get started.
Add Staticman to your repository - Go to the Staticman Github App and click on configure. Grant Staticman write access to your repository. Whenever a user fills out a comment form, Staticman will automatically create a pull request. If you approve it, the comment will be stored as a .yml
file in your Github repository. The next time you build your Gatsby site, the comment will be visible. You can automate this by triggering a build everytime Staticman's pull request is merged to your release branch. You can use any CI/CD tool for this purpose.
Check the staticman.yml
file in the root directory of this project. All comments will be saved as a .yml
file in the src/data/comments
folder. The gatsby-transformer-yaml
plugin will then scan the folder, and you will be able to access your comments as the allCommentsYaml
object in your GraphQL schema.
Note: Please check out this plugin's documentation here to understand all the plugin customization options.
This Gatsby starter template uses gatsby-source-wordpress
to source content from your Wordpress CMS. While this plugin can apply image transformations on the featured images, it cannot do that for images within the post/page content. What this means is that if you have any image within your Wordpress post/page, it will have to be served from your original wordpress url without any image transforms. Obviously this isn't ideal, and there could be 2 possible solutions for this.
Insert images from URL in your Wordpress post/page instead of uploading images to the Wordpress wp-content/uploads
folder (Maybe a good CDN like AWS Cloudfront, Google Photos etc). By doing so, the images will be served from the CDN, and everything works as expected. You still won't be able to do fluid transforms on these images though.
This Gatsby starter template uses (untested) gatsby-wordpress-inline-images plugin to download images within Wordpress the post/page content, to the local static folder and also lets you applies fluid image transforms on those images. This is because gatsby-source-wordpress
doesn't process images in blocks of text which means your admin site has to serve the images. However, I haven't fully tested this plugin and you can feel free to comment it out from the gatsby-config.js
file if you run into any issues.
Note: Please check out this plugin's documentation here to understand all the plugin customization options.
This Gatsby starter template uses Husky to create Git hooks. Husky can prevent bad git commit, git pushes etc. You can use the husky hooks in the package.json
file to execute custom scripts and tasks before each git commit and git push. For example, this project uses the pre-commit
hook to run the lint script, and the pre-push
hook to create gatsby build and verify that everything works before git push happens to the repository. This is optional though, and you can opt out of it by simply commenting out the husky
object in the package.json
file.
This Gatsby starter template uses gatsby-plugin-offline
plugin. If you don't want your site to work offline, simply comment this plugin out from the gatsby-config.js
file.
This Gatsby starter template has some basic SEO capabilities out of the box such as robots.txt file, sitemap.xml file, meta tags defined in react-helmet
etc.
This Gatsby starter template uses the gatsby-plugin-pinterest-twitter-facebook plugin to load the following social media widgets. No API tokens needed for any of these widgets, and no complicated setup procedure. Just plug and play.
This Gatsby starter template displays a reading progress bar at the top of each page. Feel free to tweak it, hide or show it on certain pages, or remove it altogether if you don't like it.
Pin it
button while hovering over any image on your website.Note: Please check out this plugin's documentation here to understand all the plugin customization options.
This Gatsby starter template uses the gatsby-source-instagram plugin to display upto 12 most recent posts of any Instagram account.
Note: Please check out this plugin's documentation here to understand all the plugin customization options.
Once you have defined the mandatory environment variables mentioned above, and have a Wordpress site ready (either on your local machine or a pre-existing live website), follow these instructions to use this Gatsby starter template
Install dependencies
yarn
or npm install
Run the development server
yarn start
or npm run start
Note:
.tsx
or .ts
extension instead of .jsx
or .js
.scss
extension and import them into any React component, it will automatically get transpiled into CSS.If you face any issues while working with this Gatsby starter template, feel free to create a new issue here. Please check if there's any existing similar issue already created before creating a new one.
Fork this repo and make a PR.
This project is licensed under the MIT License - see the LICENCE.md file for details