Converting an existing Gatsby project to TinaCMS

TinaCMS does not officially support Gatsby. We recommend migrating your Gatsby site to a well supported framework such as Next.JS instead.

Introduction

In this tutorial, we'll guide you through converting an existing Gatsby MDX blog to TinaCMS. We've provided a starter repo for you to follow along, which is a fork of the official Gatsby MD blog starter.

Limitations

There are a few limitations to the approach outlined in this guide.

• Loss of Gatsby's image optimization
• Gatsby uses GitHub Flavored Markdown, which TinaCMS does not fully support

Getting started

First, clone our sample Gatsby project. Then you'll want to navigate into the blog's directory.

Adding TinaCMS

Awesome! You're set up and ready to start adding TinaCMS. You can initialize it using the command below.

After running the command above you'll receive a few prompts

1. When prompted to select a framework select other
2. Choose yarn as your package manager
3. When asked if you'd like to use Typescript choose yes
4. Set the public assets location to public

Setting up Gatsby for TinaCMS

Now that we've added TinaCMS to our project, there are a few more steps to integrate it with Gatsby. Start by adding the following line at the top of tina/config.js

Next, we'll set up the URL for the visual editor using Express.

To make sure TinaCMS runs when the app is in development mode, update the startup command in package.json as follows:

To fix any bugs related to conflicting GraphQL versions inside of node modules we'll also force Gatsby to use the same version as TinaCMS in package.json.

Add the following:

Configuring our Schema

First we'll configure where our images get stored and update the schema so that we're ready to work with markdown files. Open tina/config.ts and make the following changes.

By moving our images to static, we're ensuring that they'll be tracked in git and bundled at run time.

Next we'll add the existing frontmatter fields to our schema. We'll also change the path to point to our existing blogs

Updating your images

You'll need to reupload your images to match our new media directory.

TinaCMS does not currently support relative image directories (e.g. those used for the original blog). You can either port your images by re-uploading them or changing the url to match our media folder.

For example the new image in content/blog/hello-world/index.mdx will look like this.

You'll also need to move the existing images into the new folder we defined.

Reformatting your markdown

As the hello world sample uses a list type that is unsupported by TinaCMS, we'll update the lists to the supported format manually. Make the following changes to content/blog/hello-world/index.mdx.

You may need to update other elements on your site. For unsupported markdown elements in TinaCMS, refer to our guide.

We should be able to read and edit our existing pages in TinaCMS now.

Styling

We'll add some CSS to fix the images in our articles since they aren't being handled by to fix the width of our images since they're no longer being processed by Gatsby.

Add the following to the top of src/style.css. This will resize any images in our blog.

Congratulations! Your Gatsby MDX blog is now set up with TinaCMS. Run yarn develop to test it out.

(Recommended) Adding Visual editing

Warning - If you do decide to add visual editing you will need to swap any custom MDX plugins you're using

Up until now we've only set up TinaCMS as an editor for our markdown files. The display logic is still being handled by Gatsby's plugins.

There are some pros and cons to using Gatsby's MDX plugin instead of TinaCMS's.

Pros:

• You can use your existing markdown plugins

Cons:

• You won't be able to use React components in your markdown files
• You won't be get contextual editing when editing your markdown files

Generally, we recommend using TinaCMS's GraphQL API to load your pages, which we'll do now.

Because we'll be using TinaCMS's graphql client for this approach we no longer need to skip it. In fact we'll need it to retrieve the GraphQL queries required for visual editing.

Generating the pages

First, we'll new types for the response from TinaCMS's GraphQL API and remove the existing ones. Modify the types in src/types.ts to reflect the new data we'll be getting back from TinaCMS's API.

Using these types, we'll add a helper to map out the response from TinaCMS's GraphQL API. This will give the page data a similar format to the response from the GraphQL queries we're replacing.

Next we'll update the createPages function to use TinaCMS's GraphQL API to generate the pages and remove the existing call.

Using the response from TinaCMS's GraphQL API we'll change the way that pages get generated

Updating the blog post page

First we'll define our types inside of src/types.ts.

Next we'll use a static query to get the data for our blog post page template.

Add a static query to get the data for the page using TinaCMS.

We'll also update the page query to exclude the markdown from the query since, we'll be using TinaCMS to populate the page instead.

Now that we've configured our page with a new data source we can use the useTina hook to implement visual editing.

First update the page props for BlogPostTemplate. We'll add in our server fetched data and pull that in using the useTina hook

Then we'll swap out all of the existing data with the data we get back from TinaCMS. Note the addition of the tinaField property, which is used to add contextual editing for each of the fields.

Don't forget to update the Head component with data from the server as well.

There's one other step we'll do. Unfortunately, our date isn't being formatted using by the graphql query. To fix this we'll use a library to format our date.

Then we'll add a useEffect to update the date when the date changes. We're using useEffect here so that the date will be recomputed when we use the visual editor. Using useState will cause the date to update when our data source changes.

Updating the home page

We also need to update the homepage to reflect content changes, as it was previously populated using gatsby-mdx. Make the following updates to src/pages/index.tsx:

On the homepage, we’ll need to implement a server-side fetch to retrieve the full list of articles through TinaCMS.

Then we'll add the server side data to the component.

Finally, we'll use the server side data to populate the landing page. Make the following changes to src/pages/index.tsx.

We'll also format the date in this file.

We don't need to use the useTina hook here because the homepage is static.

The final step for enabling contextual editing is to configure the routing property of our collection. This setting will ensure that we navigate to the correct page when opening a file in TinaCMS's visual editor. Since each blog post is stored in its own folder within the content directory, we can use the first folder in the breadcrumbs array to determine the correct path.

(Optional) Adding React components