DEV Community: Kendall Strautman

Index Signatures in Typescript

Kendall Strautman — Wed, 25 Nov 2020 01:21:24 +0000

This is a pattern I've found incredibly helpful of late. Let's say you have a collection of fruit in a basket. You may make a type for all the possible fruits. 🍐🍍🍈🥭🍒🥝🍇

type Fruit = 'pomegranate' | 'pear' | 'persimmon' | 'guava' | 'jackfruit'

Let's say the basket is represented by an object literal, consisting of key-value pairs, the key being the fruit id.

const fruitBasket = {
    1: 'jackfruit',
    2: 'guava',
    3: 'pomegranate',
    4: 'pear',
    5: 'guava'
}

Every fruit basket will be different, and random to a degree. They will all contain different amounts of fruit, although we expect the baskets to contain only the fruits outlined in the Fruit type. To create an interface for the fruit basket, we need to use an index signature in the interface.

type Fruit = 'pomegranate' | 'pear' | 'persimmon' | 'guava' | 'jackfruit'

interface FruitBasket {
    [key: number]: Fruit
}

const fruitBasket: FruitBasket = {
    //...
}

This way, the fruit basket can have an innumerable amount of fruit items, the keys can all be unique numbers or ids and the fruit will be safely typed.

I find this pattern helpful when needing to type objects or components where they may have a prop or key-value pair where I don't know the key ahead of time.

You could take this a step further, say I don't know exactly what kind of fruit is acceptable, or perhaps there are different iterations of fruit baskets, one for fall, spring, and winter fruits. We can adjust the fruit basket interface to accept a parameter.

type ClassicFruit = 'apple' | 'banana' | 'orange' | 'strawberry'
type TropicalFruit = 'pineapple' | 'mango' | 'papaya' | 'lychee' 

interface FruitBasket<T> {
    [key: number]: <T>
}

const classicBasket: FruitBasket<ClassicFruit> = {
    //...
}

const tropicalBasket: FruitBasket<TropicalFruit> = {
   //...
}

This way, we could swap out the specifics of the fruit, depending on the type of basket.

Dive deeper into this in the TS documentation! Happy coding 🤖

Custom Field Plugins in TinaCMS

Kendall Strautman — Mon, 17 Feb 2020 19:51:30 +0000

In the previous post, we learned how to create a custom field component and register it to the sidebar. With that baseline, let's go full circle on the topic of custom fields in TinaCMS. In this short but sweet post 🧁, we’ll cover how to turn a field component into a field plugin.

Field Plugin vs. Field Component

Plugins extend functionality in the CMS; field plugins allow us to create and register custom fields. There are a few reasons why you may want to create a field plugin. With a custom field, you can completely control the editing experience and functionality. If the primary fields provided by Tina don't fit your use case, you can fill the gaps.

A field component is just one piece of a field plugin (more on this later). A custom field component can achieve the same functionality as a plugin. But if you plan on reusing the custom field on different forms, it is recommended to take the extra steps to make a plugin 🔌.

Creating field plugins helps confine complex logic to a single module. This makes it easier to update or swap out custom field functionality later down the line. Using the plugin API makes our 'higher-level' code more reusable and contained, keeping the fields independent from the core CMS.

For those who want to dig deeper, this approach seeks to embody the Dependency Inversion Principle.

Getting Started 👏

To follow along, you should have a custom field component set-up with a Tina form. If not, you can get some more context from the previous post: how to create a custom field component. In the following examples, I am using the same llama-filters 🦙 demo from our previous post.

There are two steps to adding a field plugin to the CMS. First, we'll define the field component object and register it with the CMS. Next, we'll use the field plugin in a form definition so we can edit content in the sidebar with our fancy custom field plugin.

Want to see a working example? Check out the Authors Field Plugin from the Tina Grande Starter.

1. Add the Field Plugin to the CMS

To register the custom field as a plugin with the CMS, we’ll need to head to the file where we can access the CMS instance. In the Next.js demo, we’ll look at _app.js.

// _app.js

import React from 'react'
import App from 'next/app'
import { Tina, TinaCMS } from 'tinacms'
import { GitClient } from '@tinacms/git-client'
/*
 ** 1. Import the custom field component
 */
import RangeInput from '../components/RangeInput'

/*
 ** 2. Define the field plugin
 */
const customFieldPlugin = {
  name: 'range-input',
  Component: RangeInput,
}

export default class Site extends App {
  constructor() {
    super()
    this.cms = new TinaCMS({
      apis: {
        git: new GitClient('http://localhost:3000/___tina'),
      },
      sidebar: {
        position: 'overlay',
        hidden: process.env.NODE_ENV === 'production',
      },
    })
    /*
     ** 3. Register the plugin with the cms
     */
    this.cms.fields.add(customFieldPlugin)
  }

  render() {
    //...
  }
}

You’ll want to import the custom field component and then register the plugin with the CMS directly. Notice how we import the RangeInput component created in the previous post. This is the custom field component that we're now attaching to a field plugin.

If you’re working with Gatsby, this looks slightly different. Hint: you’ll head to the gatsby-browser.js file to access the CMS instance.

Field Plugin Interface

Let's break down the field plugin further. The interface below should provide some insight into all that can go into creating a field plugin. When you register a field plugin with Tina, it expects an object with a similar shape.

interface FieldPlugin {
  name: string
  Component: React.FC<any>
  type?: string
  validate?(
    value: any,
    allValues: any,
    meta: any,
    field: Field
  ): string | object | undefined
  parse?: (value: any, name: string, field: Field) => any
  format?: (value: any, name: string, field: Field) => any
  defaultValue?: any
}

At a minimum, field plugins require a name and a component. The name is used to reference the custom field in form definitions (more on this later). The Component is what is actually rendered in the sidebar.

You can see that there are additional configuration functions and options. Note that the properties with a question mark are optional. These options are incredibly useful for creating fields that require validation, parsing, or formatting.

To see a more complex example, checkout the documentation on creating an email field.

2. Use the custom field in a form

Now that the plugin is registered with the CMS, we can use it in any form definition. Going back to the llama-filters demo, let’s head to index.js where the Tina form is configured. We need to update the form options for our image saturation field to reference the field plugin name, as opposed to calling the component directly.

/*
** 1. Remove the import of the custom field component
*/
- import RangeInput from '../components/RangeInput'
import React from 'react'
import { useLocalJsonForm } from 'next-tinacms-json'

export default function Index(props) {
  //...
}

const formOptions = {
 fields: [
   /*
   ** 2. Reference the field plugin `name` instead
   **    of passing the custom component directly
   */
   {
     label: 'Image Saturation',
     name: 'saturation',
-    component: RangeInput
+    component: 'range-input'
   }
 ]
}

Index.getInitialProps = async function() {
  //...
}

That's it! With the plugin defined and registered with the CMS, you can reuse this field ad infinitum. In my opinion, creating a field plugin helps maintain a consistent interface for defining forms. This way, the custom field works behind the scenes as if it were a native Tina field, which is pretty slick.

Short and sweet, as promised 🍰

This post, combined with the former, should give you all the building blocks to start making your own field plugins. Feel free to dive into the documentation on fields or plugins. Make sure to share your groovy custom fields with us @tina_cms 🖖. Or, if you feel there is a fundamental field missing from Tina, open up a PR to contribute your custom field!

How to Make a Custom Field Component with TinaCMS

Kendall Strautman — Wed, 22 Jan 2020 00:03:37 +0000

Form fields are the bread and butter of any CMS. While Tina provides a solid collection of fields 'out-of-the-box', you can also create your own. This post will show you the basic concepts of how to create custom field components and use them in the Tina sidebar.

Prerequisites 👩‍🏫

Throughout the post, I'll refer to a few core TinaCMS concepts such as forms, the sidebar, and fields. It will be helpful to have some basic working knowledge of how TinaCMS works before reading. Feel free to refer to the documentation or read a post on using Tina with Gatsby or Next.js to get familiar.

Why would you create a custom field?

Tina was intended to be fully customizable and extensible. Creating custom fields can provide precise control over the sidebar configuration and styling, along with implementing unique field functionality.

Want to jump ahead? Feel free to check out a finished version of the custom range input field seen in the gif above, or take a peak at a more complex Authors field plugin in the Tina Grande repo.

Two Methods — Let’s start simple

There are two ways to add custom fields to Tina. The first approach involves defining a React component and passing it into the component property of a field definition. The Tina Team refers to this as an inline field component. This option is more straightforward; it will be the method of focus in this post.

The second approach involves defining a custom component, then registering that component as a field plugin with the CMS. All the core fields provided by Tina are used as plugins.

There are some advantages to creating a plugin versus an inline field — the main points being reusability and access to additional functions for parsing, validation etc. But for simpler cases, when you need a custom field in just one form or don’t necessarily need validation, an inline field component will do just fine 👌.

Creating a custom inline field

Say we have a Tina Form set up for an About Me page:

Note: The examples below will be referencing a Next.js setup, but this approach can be applied to Gatsby as well.

 const formOptions = {
   label: 'About Me Page',
   fields: [
     {
       label: "Name",
       name: "name",
       component: "text",
     },
     {
       label: "Hometown",
       name: "hometown",
       component: "text",
     },
     {
       label:"Color",
       name:"background_color",
       description: "Background Color",
       component: "color"
     },
   ]
 }

We could add a custom inline field component to further organize the sidebar:

const formOptions = {
   label: 'Info Page',
   fields: [
     {
       label: "Name",
       name: "name",
       component: "text",
     },
     {
       label: "Hometown",
       name: "hometown",
       component: "text",
     },
     // This is our custom inline field 👀
     {
       name: "_",
       component: () => <h4>Page Styles</h4>,
     },
     {
       label:"Color",
       name:"background_color",
       description: "Background Color",
       component: "color"
     },
   ]
 }

Pretty cool huh? 🤩

Notice how in all of the other field objects, the component property is referencing a Tina field plugin, whereas with our custom inline field, we are passing in a React component.

Now this example component is super simple — a glorified label. This type of component can be helpful with organizing or customizing the sidebar, but we can go further and pass in more complex fields.

Custom Range Slider 🎨

Say we had an image on the About Me page and we wanted to be able to control some CSS filters on that image. The pen below shows all the CSS filters we have to play with.

We can create a custom input field to provide editing control over these visual filters. Let’s make a custom field that controls image saturation.

Tip: Saturation in photography relates to the intensity of particular colors in an image. A highly saturated image would be very bright, with colors bordering on neon. An image with low saturation would appear muted and grey.

1. Create the input field component

To create a custom input field, we need to make a React component that takes input and updates data when the input is altered. For this example, we are going to make a range input field that handles the state of the saturation value and updates that state whenever the range control is slid.

// An example of a custom range field component
function RangeInput(props) {
   return (
     <>
       <div>
         <label htmlFor="saturation">Image Saturation</label>
       </div>
       <div>
         <input
            name="saturation"
            id="saturation"
            type="range"
            min="0"
            max="10"
            step=".1"
            /*
            ** This special input
            ** object sets essential
            ** input props: value,
            ** onChange, onFocus etc.
            */
            {...props.input}
          />
        </div>
     </>
   )
 }

👽 Take a closer look — Props:

Notice this line, {...props.input}. You may be wondering where this magical object with all of the necessary input props is coming from?

When the custom field is registered with Tina, this input object is passed in as a prop to the field. This object contains necessary data and callbacks for the input to function properly: value, name, onChange, onFocus, onBlur.

Tip: If your custom component is not a standard HTML input element, you will need to manually pass in the necessary input props, as opposed to using the spread operator.

All of the props passed to the field component are:

field — A reference to the field definition.
input — The object with data and callbacks for the field to set and update data. Outlined above ☝️.
meta — This provides metadata about the state of the field.
tinaForm — A reference to the form where this field is registerd.

The react-final-form documentation describes the input and meta props incredibly well. When creating custom fields, you'll typically be accessing the field and input props.

Where should the custom field live?

As we saw in the first example, we can pass in the custom field component directly via the component property — component: () => <p>Hi<p>. But when we are creating more complex fields, we will most likely want to extract the field into its own function.

In the example above, RangeInput could be defined alongside the AboutMe component where the Tina form is set up:

/*
** Custom field defined alongside
** component using a Tina Form
*/
import { useLocalJsonForm, JsonFile } from "next-tinacms-json";

export default function AboutMe(props) {
  // Tina Form config
  const [data] = useLocalJsonForm(props.data, formOptions)
  return (
    //...
  )
}

function RangeInput(props) {
  //...
}

const formOptions = {
  /*
  ** RangeInput will be referenced
  ** in the custom field definition
  */
}

AboutMe.getInitialProps = async function() {
  //...
}

It could also be defined in its own file and imported into the file where the Tina form options are configured:

/*
** Custom field definition kept in
** separate file and imported
*/
import { useLocalJsonForm, JsonFile } from "next-tinacms-json";
import RangeInput from '../components/RangeInput';

export default function AboutMe(props) {
  // Tina Form config
  const [data] = useLocalJsonForm(props.data, formOptions)
  return (
    //...
  )
}

const formOptions = {
  /*
  ** RangeInput will be referenced
  ** in the custom field definition
  */
}

AboutMe.getInitialProps = async function() {
  //...
}

As with many things in development, the answer depends on your usecase 😉. Feel free to reference this demo repo to see a working example structure for Next.js.

2. Add the value to the source data

Now that the custom input field is defined, we need to add the image_saturation value to our source data. The source data could be a Markdown or JSON file. If you already have a Tina Form set up, it should be linked with a data source, so head to that file.

For our example, let's say we have a local JSON file called about.json. This file contains the data used in the About Me page. In it we can add the image_saturation value.

The value can be any integer or floating point number that exists between the range defined in our RangeInput component — 0 to 10, with a step of 0.1 (meaning each 'slide step' of the range increments or decrements the value by 0.1). As a saturation value, zero would be totally grayscale or no color, so we can fill in something like 3 to get a more 'normal' look.

// Example About Me Page source data --> about.json
{
 “name”: “Koba Weasley”,
 “hometown”: “Bend, Oregon”,
 "background_color": "#B1BCBC",
 "image_saturation": 3,
}

Tip: If you’re using Gatsby, you will need to update your GraphQL query to get this new data. Add the image_saturation field to your query.

So now we have a source value that can be connected to the custom input field. This way, Tina can update the value in the source file in sync with the changes picked up by the RangeInput component.

3. Add the custom field to a Tina Form

How about we wire up this custom field to Tina? 🎊

In this step, we need to create the custom field definition and pass in the RangeInput component inline. We'll go back to our About Me page form options:

const formOptions = {
   label: 'About Me Page',
   fields: [
     {
       label: "Name",
       name: "name",
       component: "text",
     },
     {
       label: "Hometown",
       name: "hometown",
       component: "text",
     },
     {
       name: "",
       component: () => <h4>Page Styles</h4>,
     },
     // Pass `RangeInput` to the `component` property
     {
       label: "Image Saturation",
       name: "image_saturation",
       component: RangeInput,
     },
     {
       label:"Color",
       name:"background_color",
       description: "Background Color",
       component: "color"
     },
   ]
 }

Start the development server and you should see the custom RangeInput field in the sidebar. If you slide it, you should see the value updating in about.json.

4. Dynamically set the CSS filter

If all went well, our custom input field should be wired up, but there's one last thing to do. We haven’t connected the saturation value with a CSS filter to actually see an effect on the image.

In order to do this, you’ll need to be using a CSS-in-JS framework so we can dynamically update the filter values through the component props. If you’re using Next.js, styled-jsx works out-of-the-box and is pretty fantastic. Below is an example of the saturation value being connected to the CSS filter with styled-jsx:

/*
**  Example component for the
**  About Me page in Next.js
*/
import { useLocalJsonForm } from "next-tinacms-json";

function AboutMe(props) {
  const [data] = useLocalJsonForm(props.data, formOptions)
  return (
    <Layout bgColor={data.background_color}>
      <section>
        <h1>Hi 👩‍🎤 my name is {data.name}</h1>
        <p>Currently gallivanting around {data.hometown}</p>
        {/* This is the image that will get the treatment */}
        <img alt="random-unsplash" src="https://source.unsplash.com/random/800x600" />
      </section>
      {/* Pass in the image_saturation value */}
      <style jsx>{`
        img {
          filter: saturate(${data.image_saturation});
        }
      `}</style>
    </Layout>
  )
}

Some other examples of awesome CSS-in-JS frameworks are styled-components and emotion.js. Note that the above implementation for these alternative frameworks this will look slightly different.

Next Steps

A good next step would be adding styles to the custom RangeInput component. You could use @tinacms/styles to fit the vibe of other Tina fields ✌️. Or you could go wild and spice up the sidebar in your own way 🤠.

If we wanted to reuse this component throughout the site, we could take a step further and make it into a Field Plugin. Stay tuned for a follow-up post that dives into creating custom Field Plugins, or swing by the docs to get a head start.

Feel free to check out a finished version of this custom range input field, or take a peak at a more complex Authors field plugin in the Tina Grande repo.

Takeaways 🕺🏻

Making custom field components for TinaCMS is incredibly exciting! Hopefully this post got your creative gears turning on the numerous variables to tinker with in the content editing experience.

The biggest takeaway from this short exploration of custom fields is that you can put any React component into the sidebar. This flexibility is very powerful; it opens the door for you to custom-tune the editing controls for a project depending on its unique needs. And while creating custom components may not be necessary all the time, simply knowing it’s an option is reassuring, if not inspiring.

How to Add and Delete Files with TinaCMS

Kendall Strautman — Tue, 10 Dec 2019 23:56:15 +0000

Originally published on TinaCMS.org

Creating and deleting content — two fundamental sides of the CMS coin. This article will cover how to set up this functionality with TinaCMS on a Gatsby site. But first, some overview.

Tina Overview — sidebar, forms, plugins

When you install Tina, you immediately get access to a ‘sidebar’. This sidebar is the main interface for editing and managing content with Tina

To make content editable on your site, you need to register a form to Tina. Forms appear in the sidebar, displaying fields where you can edit content on the page.

Plugins extend the functionality of the core CMS. Behind the scenes, plugins do some big work with Tina. They register forms, create new screen views, and allow us to add new content. If you're interested to learn more, read this post on Tina's dynamic plugin system.

Creating New Files

The Steps 🚶‍♀️

These steps will be our journey-map for setting up content-creation functionality in a Gatsby website. They follow along with the documentation closely.

Where to add the plugin

Before we get into the steps, we need to zoom out to consider the editing process in our site. As a developer, you get to decide when editors can create new content.

To be more specific, you can register the content-creator plugin on any component in the site. When that component renders, editors will be able to create new content.

You may want create a new blog only when you're on the blog list page. To do this, you'll register the plugin on the list component.

If you always want to be able to create new blogs, you'll register the plugin on a component that is always rendered. Examples of this could be the Layout or Root component.

Consider the experience before you dig into code. One of the incredible things about Tina is that you have this finite control, so use it.

Step 1: Set-up a content-creator plugin

Okay, let’s get into it. In this step we are going to create a content-creator plugin 👩‍🎨.

There are different plugins for creating new markdown or JSON files. In this tutorial, we'll use RemarkCreatorPlugin for markdown files. Feel free to read about the JsonCreatorPlugin in the documentation.

Head to the component file where you want to add this plugin. This example will use the Layout component. This way, the ability to create new posts is always available to the editor.

The example below shows how to create an instance of a RemarkCreatorPlugin. The basic information the plugin needs is a label, filename, and fields array.


/*
** Layout.js
*/

/*
** 1. import RemarkCreatorPlugin to
**    construct a `content-creator` plugin.
*/
import { RemarkCreatorPlugin } from 'gatsby-tinacms-remark'

/*
** 2. instantiate RemarkCreatorPlugin with
**    label, filename, and fields.
*/
const CreatePostPlugin = new RemarkCreatorPlugin({

  /*
  ** LABEL: A simple action label displayed when editors
  ** interact with the + button in the sidebar.
  */
  label: 'New Blog Post',

  /*
  ** FILENAME: A function whose return value
  ** should be the path to the new file.
  */
  filename: form => {
    return form.filename
  },

  /*
  ** FIELDS: An array of field objects defining the shape
  ** of the form to fill out when creating a new file.
  */
  fields: [
    {
      name: 'filename',
      component: 'text',
      label: 'Filename',
      placeholder: 'content/blog/hello-world/index.md',
      description: 'The full path to the new markdown file, relative to the repository root.',
    },
  ],
})

Formatting the path to the new file

There are many ways you could set up the return value for the filename. A helpful pattern to use could be to hard-code the directory path, and then 'slugify' the title. You can do this manually with Regex or use a handy package aptly called slugify.

const CreatePostPlugin = new RemarkCreatorPlugin({
   //...
  filename: form => {
    // 'form' holds the data inputted by the 'create-form'
    const slug = form.title.replace(/\s+/, '-').toLowerCase()

    return `content/blog/${slug}.md`
  },
})

Notice how data submitted by the create-form is being used. When a new file is created, you can have the editor enter a title, and then all the create-form data is passed to the filename function.

You can use the data from create-form to creatively generate new file paths or populate default data (more on that later). Overall, formatting the filename depends on the structure of your project. Pick a simple solution that makes sense to you or checkout more examples here.

2. Register the plugin with the sidebar

In the previous step, we created the plugin, now we actually need to add it to the sidebar (and cms).

If you haven't already, install the tinacms package.

$ yarn add tinacms || npm install tinacms

Then import withPlugin from tinacms. withPlugin is a higher-order component used for adding plugins to the CMS.

Export the component and plugin using withPlugin and you should now be able to add new posts from the Tina sidebar. The location of the new files will be based on the return value from the filename function.

// 1. Import withPlugin
import { withPlugin } from 'tinacms'
import { RemarkCreatorPlugin } from 'gatsby-tinacms-remark'

function Layout(props) {
  return (
      /*
      ** Nothing gets changed in the actual component
      ** to register the `content-creator` plugin
      */
    )
  }

// 2. Create instance of `RemarkCreatorPlugin`
const CreateBlogPlugin = new RemarkCreatorPlugin( {
  label: 'Add New Blog',
  filename: form => {
    const slug = form.title.replace(/\s+/g, '-').toLowerCase()
    return `content/posts/${slug}.md`
  },
  fields: [
    {
      label: 'Title',
      name: 'title',
      component: 'text',
      required: true
    },
  ],
})

// 3. Export the component & `content-creator` plugin
export default withPlugin(Layout, CreateBlogPlugin)

Start up your development server (gatsby develop) and you should see a blue plus (+) icon in the top menu of the sidebar. Click it and you’ll see the label you set in your plugin configuration. Try to create a new file! See what happens.

Troubleshooting Tip: If you don't see the icon, check if the component where you added the plugin is actively rendered.

3. Customize The Create Form

In our initial example, the create-form only captured a title. We can add more fields to capture data that will populate the new file, such as the date and author.

const CreatePostPlugin = new RemarkCreatorPlugin({
  label: 'Create Post',
  fields: [
    {
      name: 'title',
      component: 'text',
      label: 'Title',
      description: 'The title of your new post',
      required: true
    },
    {
     name: 'date',
     component: 'date',
     label: 'Date',
     description: 'The default will be today'
   },
   {
     name: 'author',
     component: 'text'
     label: 'Author',
     description: 'Who wrote this?',
   }
  ],
  filename: form => {
    const slug = form.title.replace(/\s+/, '-').toLowerCase()
    return `content/blog/${slug}.md`
  },
})

Notice the use of a required property on the title field. Use this to ensure you get all the required data necessary for creating the new file.

Learn about the default fields to choose from in the documentation. If you're interested in creating a custom field, read more on that here.

4. Configure Defaults

RemarkCreatorPlugin can take additional information to populate default data into newly created files. For markdown, we can add default frontmatter values and a markdown body — see the example below.

const CreateBlogButton = new RemarkCreatorPlugin( {
 label: 'Add New Post',

 filename: form => {
     const slug = form.title.replace(/\s+/g, '-').toLowerCase()
     return `content/posts/${slug}.md`
 },

 fields: [
   {
     label: 'Title',
     name: 'title',
     component: 'text',
     required: true
   },
   {
     label: 'Date',
     name: 'date',
     component: 'date',
     description: 'The default will be today'
   },
   {
     label: 'Author',
     description: 'Who wrote this, yo?',
     name: 'author',
     component: 'text'
   }
 ],

 /*
 ** 1. Add default frontmatter with data inputted
 **    through fields in the `create-form`
 */
 frontmatter: postInfo => ({
   title: postInfo.title,
   date: postInfo.date ? postInfo.date : new Date(),
   author: postInfo.author ? postInfo.author: ‘Kurt Vonnegut’
 }),

 // 2. Add a default markdown body
 body: postInfo => `New post, who dis?`
})

Both the frontmatter and body functions receive the data captured by fields in the create-form. Use the inputted values to populate the new file, or setup defaults if nothing was entered.

Deleting Files

With the power to create, comes the power to delete 🧙‍♀️. I promise you this step is much simpler.

Instead of adding a ‘delete’ plugin, we simply need to pass a delete-action to the main form options.
Head to a file where you have a Tina form configured in your project. This will typically be a template file that generates multiple posts, casestudies, etc. If you don’t have a Tina form configured in your project, learn more about creating forms with Gatsby+Tina here.

You don't want to give the editors the power to delete files that they shouldn't. So think about where you want this action to be available. For something like a blog, it makes sense to add the delete-action to a blog template form. But it might not make sense to add the delete-action to a form that edits global site configuration, for example.

Below is an example blog template with the delete-action added:

// 1. Import `DeleteAction`
import { remarkForm, DeleteAction } from 'gatsby-tinacms-remark'

function BlogTemplate(props) {
  return (
    <>
      <h1>{props.markdownRemark.frontmatter.title}</h1>
      <p>{props.markdownRemark.frontmatter.description}</p>
    </>
  )
}

// 2. Add the `DeleteAction` to the form
let BlogFormOptions = {
  actions: [ DeleteAction ],
  fields: [
    {
      label: 'Title',
      name: 'frontmatter.title',
      description: 'Enter the title of the post here',
      component: 'text',
    },
    {
      label: 'Description',
      name: 'frontmatter.description',
      description: 'Enter the post description',
      component: 'textarea',
    },
  ],
}

export default remarkForm(BlogTemplate, BlogForm)

You can import the DeleteAction from gatsby-tinacms-remark or gatsby-tinacms-json, depending on your filetype. Then on your form options definition, add the action and that’s it!

You can now access this delete-action via the three-dot icon near the save button. Test it out! But make sure you don't delete a file that you need or can easily restore it if you do 🧞‍♂️.

Happy Creating (and Deleting)! 👩‍🎤

Hopefully this tutorial gave you some insight into setting up two core bits of CMS functionality with Tina + Gatsby.

If you run into trouble or have any questions, head over to the Tina Forum for help. Stoked on TinaCMS? Please ⭐️ us on Github or Tweet us 🐦 to show-off your Tina projects.

Using TinaCMS with Next.js

Kendall Strautman — Mon, 02 Dec 2019 19:08:31 +0000

UPDATE 02-25-2022 - This post has been updated to reflect Tina, Next.js and how to get started!

This blog is a part of a series exploring the use of Next.js + Tina. In Part I, we learned how to create a simple markdown-based blog with Next. In this post, we’ll add content editing capacity by configuring the site with TinaCMS.

Next.js Recap ▲

Next.js is a React “metaframework” (a framework built on a framework) for developing web applications, built by the team at Vercel. Read Part I to get familiar with Next.js basics.

Tina Overview 🦙

Tina is a Git-backed headless content management system that enables developers and content creators to collaborate seamlessly. With Tina, developers can create a custom visual editing experience that is perfectly tailored to their site.

The best way to get a feel for how Tina works is to use it. We hope that by the end of this tutorial, you’ll not only learn how to use Tina, but also how Tina rethinks the way a CMS should work.

Let’s Get Started

This tutorial will show you how to install and configure Tina for editing content on a simple markdown-based blog that was created in last week’s post. If you want to dig into how the base blog was made, read Part I of this series.

Jump ahead to see the final repo here. Or check out the Tina documentation here

Set up Locally 🏡

Feel free to follow along and fit these guidelines to your own site or blog, or you can use the starter we created in the previous tutorial. In your terminal, navigate to where you would like this blog to live, then run:

# clone the repo
$ git clone https://github.com/perkinsjr/brevifolia-next-2022 next-tina-blog

# navigate to the directory
$ cd next-tina-blog

# install dependencies & init Tina
$ yarn install
$ npx @tinacms/cli@latest init

$ do you want us to override your _app.js? Yes

The npx @tinacms/cli@latest init command does a few things in your Next.js application:

Install all required dependencies for Tina
Define a basic schema that is easily extendable, in the .tina directory
Wrap your next.js application with Tina so that any page can be easily edited.
Create example content in the demo directory.
Edit the package.json to add scripts to launch tina (tina-dev, tina-build, tina-start)

A quick test

Now that you have a basic Tina setup you can launch your application using the following command:

yarn tina-dev

Once you have launched the application you have a couple of new URLS:

http://localhost:3000/demo/blog/HelloWorld
http://localhost:4001/altair/

The first URL brings you to a demo of TinaCMS, it will show you the power of Tina and also give you some informational links to check out. If you navigate to http://localhost:3000/demo/blog/HelloWorld, you won't be able to edit right away. First, you need to enter edit mode. To enter edit mode, navigate to http://localhost:3000/admin, select login. Then navigate back to http://localhost:3000/demo/blog/HelloWorld. Selecting the pencil in the top left allows you to edit the title and the body of the page right in the frontend. When you hit save, that will save your changes to the Markdown file.

Want to see your changes? Open up the file located at /content/posts/HelloWorld.md and the changes you've made will be there! This works by using our Content API which will go into greater depth during this guide.

The second URL http://localhost:4001/altair/ will launch a graphQL client that will allow you to interact and create queries which will be in this guide.

Defining the shape of our content

One key element of Tina is defining a schema that allows you to shape and interact with the content on the page. Opening up the project, you will see a folder called .tina which contains a schema.ts file. This file allows you to instruct Tina's Content API which content type to look for, how it should be labeled, and much more!

Before you look at your current project, let's discuss how the content is shaped. Our schema can be broken down into three concepts: collections, fields and references. Each one of them has its role:

Collections

The top-level key in the schema is an array of collections, a collection informs the API about where to save content. In our guide we are going to have a posts collection but you also could have an author and pages collections, for example.

Fields

Fields instruct the Content API of the type expected for example, text, as well as the queryable name and the name to display to your content team. Fields are an array of objects that are a child of collections. We use this to retrieve the content from the Markdown or JSON files, these fields should map to your frontmatter , and we also use this to create the UI elements for editing.

fields: [
    {
      type: "string",
      label: "Title",
      name: "title"
    },
    {
      type: "string",
      label: "Blog Post Body",
      name: "body",
      isBody: true,
    },
]

References

This is an important concept, when you reference another collection, you're effectively saying: "this document belongs to that document". A great example of using a reference is author as each post would have an author and you could have multiple authors, but you need to reference a particular author to the post.

{
  "label": "Author",
  "name": "author",
  "type": "reference",
  "collections": ["author"] // points to a collection with the name "author"
}

Before we move on you can read more about content modeling in our documentation

Creating your content Schema

The blog provided from another blog post comes with four example blog posts that you are going to use to shape your content in your schema. You can find on any of the blog posts in the posts directory, let us look at the front matter of the bali.md.

---
author: Siddhartha Mukherjee
date: '2019-07-10T07:00:00.000Z'
hero_image: /alfons-taekema-bali.jpg
title: 'Bali —body, mind & soul'
---

The term **bristlecone pine** covers three ...

As you can see, you have a few fields that you want to be able to edit as well as the body of the blog post.

Making changes to the Schema

Open up the Tina schema.ts file located at /.tina/schema.ts To begin with underneath the object we provided, you need to replace the current collection with the content you want:

{
  label: "Blog Posts",
  name: "post",
-  path: "content/posts"
+  path: 'posts',
  fields: [
    {
      type: "string",
      label: "Title",
      name: "title"
    },
    {
      type: "string",
      label: "Blog Post Body",
      name: "body",
      isBody: true,
    },
  ]
}

You have only replaced a single line so far, which is to update the path to the correct location of the Blog content.

Now you need to handle each field for your posts frontmatter, below is the finished file:

import { defineSchema } from '@tinacms/cli'

export default defineSchema({
  collections: [
    {
      label: 'Blog Posts',
      name: 'post',
      path: '_posts',
      fields: [
        {
          type: 'string',
          label: 'Title',
          name: 'title',
        },
        {
          type: 'string',
          label: 'Author',
          name: 'author',
        },
        {
          type: 'datetime',
          label: 'Date',
          name: 'date',
        },
        {
          type: 'string',
          label: 'Image',
          name: 'hero_image',
        },
        {
          type: 'string',
          label: 'Body',
          name: 'body',
          isBody: true,
        },
      ],
    },
  ],
})

There are a couple of things you might notice. First, you have a type called datetime, this works by providing a date picker for you to use, and will format the date and time.

Second, there's a string field called body with isBody set to true. By setting isBody to true you're stating that this field is responsible for the main body of the markdown file. There can only be one field with the isBody: true property.

Next steps

Your Markdown files are now backed by a well-defined schema, this paves the way for us to query file content with GraphQL. You will notice that nothing has changed when navigating around the Next.js blog starter, this is because you need to update the starter to use your GraphQL layer instead of directly accessing the Markdown files. In the next section you will handle converting the frontend to use TinaCMS.

Currently, the Next Blog Starter grabs content from the file system. But since Tina comes with a GraphQL API on top of the filesystem, you’re going to query that instead. Using the GraphQL API will allow you to use the power of TinaCMS, you will be able to retrieve the content and also edit and save the content directly.

Creating the getStaticPaths query

The getStaticPaths query is going to need to know where all of your markdown files are located, with your current schema you have the option to use getPostList which will provide a list of all posts in your posts folder. Make sure your local server is running and navigate to http://localhost:4001/altair and select the Docs button. The Docs button gives you the ability to see all the queries possible and the variables returned:

So based upon the getPostList you will want to query the sys which is the filesystem and retrieve the filename, which will return all the filenames without the extension.

query {
  getPostList {
    edges {
      node {
        sys {
          basename
        }
      }
    }
  }
}

If you run this query in the GraphQL client you will see the following returned:

{
  "data": {
    "getPostList": {
      "edges": [
        {
          "node": {
            "sys": {
              "basename": "bali.md"
            }
          }
        },
        {
          "node": {
            "sys": {
              "basename": "iceland.md"
            }
          }
        },
        {
          "node": {
            "sys": {
              "basename": "joshua-tree.md"
            }
          }
        },
        {
          "node": {
            "sys": {
              "basename": "mauritius.md"
            }
          }
        }
      ]
    }
  }
}

Adding this query to your Blog.

The query above can be used to create your dynamic paths, this happens inside of the [slug].js file. When you open the file you will see a function called getStaticPaths at the bottom of the file.

export async function getStaticPaths() {

....

Remove all the code inside of this function and you can update it to use your own code. The first step is to add an import to the top of the file to be able interact with your graphql layer. While you are there you can remove glob, as you will no longer need it.

//other imports
.....
+ import { staticRequest } from "tinacms";
- const glob = require('glob')

"What does staticRequest do?"

It's just a helper function which supplies a query to your locally-running GraphQL server, which is started on port 4001. You can just as easily use fetch or an http client of your choice.

Inside of the getStaticPaths function you can construct your request to our content-api. When making a request Tina expects a query or mutation and then variables to be passed to the query, here is an example:

staticRequest({
  query: '...', // our query
  variables: {...}, // any variables used by our query
}),

You can use the getPostList query from earlier to build your dynamic routes:

export async function getStaticPaths() {
  const postsListData = await staticRequest({
    query: `
      query {
        getPostList {
          edges {
            node {
            sys {
              filename
              }
            }
          }
      }
    }
    `,
    variables: {},
  })
  return {
    paths: postsListData.getPostList.edges.map(edge => ({
      params: { slug: edge.node.sys.filename },
    })),
    fallback: false,
  }
}

Quick break down of `getStaticPaths`

The getStaticPaths code takes the graphql query you created, because it does not require any variables you can send down an empty object. In the return functionality, you map through each item in the postsListData.getPostList and create a slug for each one.

You now need to create one more query, this query will fill in all the data and give you the ability to make all your blog posts editable.

Go ahead and test that your blog posts are still readable by navigating to one, for example http://localhost:3000/blog/bali

Creating the `getStaticProps` query

The getStaticProps query is going to deliver all the content to the blog, which is how it works currently. When you use the GraphQL API Tina will both deliver the content and give the content team the ability to edit it right in the browser.

You need to query the following items from your content api:

author
date
hero_image
title

Creating your Query

Using your local graphql client you can query the getPostDocument using the path to the blog post in question, below is the skeleton of what you need to fill out.

query BlogPostQuery($relativePath: String!) {
  getPostDocument(relativePath: $relativePath) {
    # data: {}  this is data you want to retrieve from your posts.
  }
}

If you haven't used graphql before, you will notice a strange $relativePath followed by String!. This is a variable and the String! means that it must be a string and is required.

You can now fill in the relevant fields you need to query. Inside the data object add in the fields author , date , hero_image, title. You also want to retrieve the body of your blog posts, so you can add new content. You should have a query that looks like the following:

query BlogPostQuery($relativePath: String!) {
  getPostDocument(relativePath: $relativePath) {
    data {
      title
      date
      hero_image
      author
      body
    }
  }
}

If you would like to test this out, you can add the following to the variables section at the bottom {"relativePath": "bali.md"}

Using contextual-editing

You need to set up contextual-editing on your blog so that you can edit the content using our sidebar, similar to the demo at the beginning. First, you need to import useTina hook at the top of the page.

//... all your imports
import { useTina } from 'tinacms/dist/edit-state'

What is useTina?

useTina is a hook that can be used to make a piece of Tina content contextually editable. It is code-split, so that in production, this hook will simply pass through its data value. In edit-mode, it registers an editable form in the sidebar, and contextually updates its value as the user types.

You can now use your query that you created as a variable, this variable will be used both in your getStaticProps and in your useTina hook.

const query = `query BlogPostQuery($relativePath: String!) {
  getPostDocument(relativePath: $relativePath) {
    data {
      title
      date
      hero_image
      author
      body
    }
  }
}`

Replacing your getStaticProps

To replace your getStaticProps you will be using the staticRequest in a similar way to what you used in our getStaticPaths code.

The first thing to do is remove all the code you no longer need, this includes the content, and data variables and the markdownBody, frontmatter from your props.

export async function getStaticProps({ ...ctx }) {
  const { slug } = ctx.params
- const content = await import(`../../posts/${slug}.md`)
  const config = await import(`../../data/config.json`)
- const data = matter(content.default)

  return {
    props: {
       siteTitle: config.title,
-      frontmatter: data.data,
-     markdownBody: data.content,
    },
  }
}

Now you have removed that from your code, you can use our staticRequest to retrieve the data. The only difference this time is you actually need a variable to pass along named relativePath, which is the slug. You will also need to send the variables along as a prop so you can use this in our useTina hook.

export async function getStaticProps({ ...ctx }) {
  const { slug } = ctx.params
  const config = await import(`../../data/config.json`)
  const data = await staticRequest({
    query,
    variables = {
      relativePath : slug,
    },
  })
  return {
    props: {
      data,
      variables,
      siteTitle: config.title,
    },
  }
}

Updating the client for `useTina`

Now that you are returning only two props from getStaticProps you need to update your client code to use them. Remove the destructured elements and pass in props to your client.

export default function BlogTemplate(props) {

Now you can use the useTina hook to handle contextual editing. The useTina hook expects the query, variables and data. Which you can pass in from your props.

const { data } = useTina({
    query,
    variables: props.variables,
    data: props.data,
  })

This now means you have the ability to edit your content using Tina, but before you do that you need to update all of your elements to use your new Tina powered data.

- if (!frontmatter) return <></>
  return (
-    <Layout siteTitle={siteTitle}>
+    <Layout siteTitle={props.siteTitle}>
      <article className={styles.blog}>
        <figure className={styles.blog__hero}>
          <Image
            width="1920"
            height="1080"
-            src={frontmatter.hero_image}
+            src={data.getPostDocument.data.hero_image}
-            alt={`blog_hero_${frontmatter.title}`}
+            alt={`blog_hero_${data.getPostDocument.data.title}`}
          />
        </figure>
        <div className={styles.blog__info}>
-          <h1>{frontmatter.title}</h1>
+          <h1>{data.getPostDocument.data.title}</h1> 
-          <h3>{reformatDate(frontmatter.date)}</h3>
+          <h3>{reformatDate(data.getPostDocument.data.date)}</h3>
        </div>
        <div className={styles.blog__body}>
-          <ReactMarkdown children={markdownBody} />
+          <ReactMarkdown children={data.getPostDocument.data.body} />
        </div>
-        <h2 className={styles.blog__footer}>Written By: {frontmatter.author}</h2>
+        <h2 className={styles.blog__footer}>Written By: {data.getPostDocument.data.author}</h2>
      </article>
    </Layout>
  )
}

Test & Edit Content ✨

If all went well, your blog posts will now be editable by Tina. Let's see it in action!

Start up the dev server by running yarn tina-dev, and open up a blog post in the browser. Go ahead and make edits, and then check the source file in a text editor. If you keep the browser and code editor open side-by-side, you should be able to watch the changes reflect in real time in both places!

You had a problem though, your body is a tiny input box that doesn't support Markdown! You should fix this.

Adding Markdown Support

To add markdown support you need to do two things.

Tell Tina how to use a different component.
Dynamically load the markdown component.

Update Tina Schema

Open up your schema.ts located in the .tina folder. The great thing about Tina is you can extend the UI field for your exact needs, to do this you use ui object and tell Tina the component you'd like to use.

    ui:   {
            component: COMPONENT_NAME
          }

You want to use the markdown component so you can override your body and it should look like this:

{
  type: 'string',
  label: 'Body',
  name: 'body',
  isBody: true,
  ui: {
    component: 'markdown'
      }
},

Updating `_app.js`

Before opening up your _app.js file, you need to install the markdown plugin from Tina.

yarn add react-tinacms-editor

Open up your _app.js file, this is where you are going to use the cmsCallback prop for the TinaCMS component which allows you to extend the default functionality, add plugins, handle document creation, and more

cmsCallback={cms => {

Here you are passing the cms and now you can import our component you installed to add to the plugins.

import('react-tinacms-editor').then((field)=>{
                                cms.plugins.add(field.MarkdownFieldPlugin)
                                })

Your TinaCMS should now look like this:

<TinaCMS
            apiURL={apiURL}
            cmsCallback={cms => {
                              import('react-tinacms-editor').then((field)=>{
                                cms.plugins.add(field.MarkdownFieldPlugin)
                                })
                          }}
          >

Testing

Go ahead and launch your blog and you should be able to see a new markdown editor that allows you to pass in data. Well done! With some config and calling a few hooks, you can now edit all our blog posts with Tina. Checkout the final repo, you might consider doing the following

Where can you keep up to date with Tina?

You know that you will want to be part of this creative, innovative, supportive community of developers (and even some editors and designers) who are experimenting and implementing Tina daily.

Tina Community Discord

Tina has a community Discord that is full of Jamstack lovers and Tina enthusiasts. When you join you will find a place:

To get help with issues
Find the latest Tina news and sneak previews
Share your project with Tina community, and talk about your experience
Chat about the Jamstack

Tina Twitter

Our Twitter account (@tina_cms) announces the latest features, improvements, and sneak peeks to Tina. We would also be psyched if you tagged us in projects you have built.

Creating a Markdown Blog with Next.js

Kendall Strautman — Mon, 18 Nov 2019 20:49:25 +0000

02.08.22: This post has been updated to use Next 12 and it's latest features.

Next.js is a React "metaframework" (a framework built on a framework) for developing web applications. Next.js has become a popular choice for web developers due to its bootstrapped React environment (similar to create-react-app) and its simple, file-based routing for writing backend code.

Next.js is simple and flexible. Compared to a full-fledged static site generator, there are less prescriptive guide rails placed on developers in the implementation of an app or site. Due to this flexibility, this article shares just one perspective to approach building a simple, Markdown-based blog. Take what’s helpful, disregard the rest.

If you'd like to skip ahead and reference final versions of the starter, feel free to checkout the finished implementation.

Clone the starter

Let’s get started. I have provided a bare bones starter to use as a starting point for this tutorial. You can clone the project or check it out on github for reference.

// clone the repo from your terminal
$ git clone https://github.com/perkinsjr/nextjs-starter-boilerplate my-nextjs-blog

// install the dependencies
$ cd my-nextjs-blog
$ yarn install

// start up the dev server
$ yarn dev

After you clone the project and start the dev server, navigate to http://localhost:3000/ in your browser to see what you're working with.

As you can see, it's pretty simple at the moment. If you look at the project in your code editor, you will see the following directory structure:

components/
data/
pages/
styles/

Project Structure

Let’s look at the pages/index.js file:

const Index = props => {
  return (
    <Layout
      pathname="/"
      siteTitle={props.title}
      siteDescription={props.description}
    >
      <section>
        <BlogList />
      </section>
    </Layout>
  )
}

export default Index

export async function getStaticProps() {
  const configData = await import(`../data/config.json`)
  return {
    props: {
      title: "configData.title,"
      description: "configData.description,"
    },
  }
}

You’ll see that you now have a Layout component wrapping a <section> with a BlogList component — these are all the pieces that render our little starter so far.

Data Handling

Next.js pre-renders every page, meaning it generates HTML for pages in advance. As of Next.js 9.3, there are two ways to pre-render pages: static generation or server-side-rendering (SSR). Next.js is unique in that you can use either approach depending on the project.

For this blog, you will implement static generation, this means HTML pages for each route will be generated at build time. Static generation allows pages to be cached by a CDN, improving performance.

getStaticProps

In the initial exampleindex.js, notice the use of getStaticProps below the component. This function allows you to fetch data and return it as props to your page component. The page will be rendered at build time with the props from the return object in getStaticProps.

This is your bread and butter for retrieving page-level data in Next. You can use getStaticProps to fetch data from an external api, or as seen in this example, you can get a hold of local data sources.

Note: this method only works for components defined in the pages/ directory, i.e., page components. You cannot use this method on child components, but you can pass down the data received to these child components, as you see being done with Layout in the example above.

Layout is being passed props such as the site title and description. If you look at the data in data/config.json, you’ll see the values these props are referencing. Go ahead and change the site title to your project name, then watch it update in the header.

Layout & Styling

To zoom out a little, the purpose of the Layout component is to provide the visual skeleton for every page of the site. It typically will contain some sort of nav or header that shows up on most or all pages, along with a footer element. In your case you just have a header that contains the site title.

Within Layout, there is a Meta component that contains all global styles along with anything needed to be put in the head of the site for SEO or accessibility purposes. Note that the use of a Layout component isn’t unique to Next.js; you’ll see it commonly used in Gatsby sites as well.

One thing you may notice in the Layout component is the use of component level CSS. Next.js works out of the box with component level css. It’s super intuitive to use. All of the styles are scoped to the component, this means you don't have to worry about accidentally overriding a style somewhere else.

Note that global styles and fonts are handled in the globals.css found in the styles directory, so if you want to change fonts, or add more global styles you can add it here.

Adding the Posts Directory

Now that you’re familiar with the structure of the project and Next.js fundamentals, let’s start adding the pieces and parts to get the Markdown blog up and running.

First, add a new folder in the root of your project called posts. You can add all your Markdown blog posts here. If you don’t already have content ready, just add a few dummy blog posts. I like to use Unsplash for sample photos and Cupcake, Hipsum, or Sagan Ipsum are my preferred text generators — keeps things interesting.

Here’s an example filler blog post with some commonly used frontmatter values.

---
title: A trip to Iceland
author: 'Watson & Crick '
date: '2019-07-10T16:04:44.000Z'
hero_image: /norris-niman-iceland.jpg
---
Brain is the seed of intelligence something incredible is waiting to be known.

Also, create a public folder in the root. This is where you will keep images.

Processing Markdown Files

Next, you need to install a few packages that will process your Markdown files.

$ yarn add raw-loader gray-matter react-markdown

Raw Loader will process your Markdown files. Gray Matter will parse your yaml frontmatter values. And React Markdown will parse and render the body of your Markdown files.

Add Next.js Config

Now that you’ve installed some packages needed to handle Markdown, you need to configure the use of the raw-loader by creating a next.config.js file at the root of the project. In this file you will handle any custom configuration for webpack, routing, build & runtime config, export options, and a whole lot more. In your use case, you will simply be adding a webpack rule to use raw-loader for processing all Markdown files.

//next.config.js
module.exports = {
  webpack: function(config) {
    config.module.rules.push({
      test: /\.md$/,
      use: 'raw-loader',
    })
    return config
  },
}

Pages & Dynamic Routing

So you’re set up to use Markdown files in your project. Let’s start coding a blog template page that will render the content from these Markdown files in posts.

For some background knowledge, the pages directory is special in Next.js. Each .js file in this directory will respond to a matching HTTP request. For example, when the home page ('/') is requested, the component exported from pages/index.js will be rendered. If you want your site to have a page at /about, simply create a file named pages/about.js.

This is awesome for static pages, but you’d like to have a single template from which all blog posts will be built, sourcing the different data from each Markdown file. This means you need some sort of dynamic routing, such that unique blog posts utilizing the same template have ‘pretty’ urls and their own individual pages.

Dynamic routes in Next.js are identified by square brackets [] in the filename. Within these brackets you can pass a query parameter to the page component. For example, let’s create a new folder within pages called blog, then add a new file within that blog folder [slug].js, you can use whatever is passed as this slug parameter to dynamically access data. So if you visit http://localhost:3000/blog/julius-caesar, whatever is returned from the [slug].js page component will render, and will have access to that ‘slug’ query parameter, i.e. ‘julius-caesar’.

Get Markdown Data For the Blog Template

With dynamic routing, you can make use of this slug parameter by passing in the filename of the blog post and then getting the data from the corresponding Markdown file via getStaticProps.

import matter from 'gray-matter'
import ReactMarkdown from 'react-markdown'
import Layout from '../../components/Layout'

export default function BlogTemplate(props) {
  // Render data from `getStaticProps`
  return (
    <Layout siteTitle={props.siteTitle}>
      <article>
        <h1>{props.frontmatter.title}</h1>
        <div>
          <ReactMarkdown source={props.markdownBody} />
        </div>
      </article>
    </Layout>
  )
}

export async function getStaticProps({ ...ctx }) {
  const { slug } = ctx.params
  const content = await import(`../../posts/${slug}.md`)
  const config = await import(`../../data/config.json`)
  const data = matter(content.default)

  return {
    props: {
      siteTitle: config.title,
      frontmatter: data.data,
      markdownBody: data.content,
    },
  }
}

export async function getStaticPaths() {
  //get all .md files in the posts dir
  const blogs = glob.sync('posts/**/*.md')

  //remove path and extension to leave filename only
  const blogSlugs = blogs.map(file =>
    file
      .split('/')[1]
      .replace(/ /g, '-')
      .slice(0, -3)
      .trim()
  )

  // create paths with `slug` param
  const paths = blogSlugs.map(slug => `/blog/${slug}`)

  return {
    paths,
    fallback: false,
  }
}

Notice in this example that we’re making use of gray-matter and ReactMarkdown to properly handle the YAML frontmatter and Markdown body.

A zoomed out look at how this is working: when you navigate to a dynamic route, .e.g. http://localhost:3000/blog/julius-caesar, the BlogTemplate component in pages/blog/[slug].js is passed the params object { slug: ‘julius-caesar’ }. When the getStaticProps function is called, that params object is passed in through the context. You get a hold of that slug value and then go search for a file within the posts directory that contains the same filename. Once you get the data from that file, you parse the frontmatter from the Markdown body and return the data. That data is passed down as props to the BlogTemplate component which can then render that data as it needs.

getStaticPaths

At this point, you may be more familiar with getStaticProps, but this function should look new — getStaticPaths. Since this template uses dynamic routes, you need to define a list of paths for each blog, so all the pages will be rendered statically at build time.

In the return object from getStaticPaths, two keys are required: paths and fallback. paths should return an array of pathnames and any params used in the page name. For example the 'param' used in /blog/[slug].js is 'slug'. You should only need to use getStaticPaths for dynamic routing.

The fallback property allows you to control the behavior if a path is not returned from getStaticPaths. You should set this to false so that unreturned paths will show a 404 page.

Before the release of Next.js 9.3, this path generation for static export could be handled via exportPathMap.

Checkout the [slug].js file in the final version of my starter blog to get another idea of how that blog data could be rendered and styles applied.

Get Data For the Blog Index

Let’s finish this simple blog off by adding in the proper data to the BlogList component for the Index page. Since you can only use getStaticProps on page components, you will get a hold of all the blog data in the Index component and then pass it down as a prop for BlogList to render.

// pages/index.js
export async function getStaticProps() {
  const siteConfig = await import(`../data/config.json`)
  //get posts & context from folder
  const posts = (context => {
    const keys = context.keys()
    const values = keys.map(context)

    const data = keys.map((key, index) => {
      // Create slug from filename
      const slug = key
        .replace(/^.*[\\\/]/, '')
        .split('.')
        .slice(0, -1)
        .join('.')
      const value = values[index]
      // Parse yaml metadata & markdownbody in document
      const document = matter(value.default)
      return {
        frontmatter: document.data,
        markdownBody: document.content,
        slug,
      }
    })
    return data
  })(require.context('../posts', true, /\.md$/))

  return {
    props: {
      allBlogs: posts,
      title: siteConfig.default.title,
      description: siteConfig.default.description,
    },
  }
}

This can be slightly complex to look at, but let’s take it one step at a time. Feel free to reference this blog for the original code. It uses a function provided by Webpack, require.context(), that allows you to create your own ‘context’ based on three parameters:

The directory to match within.
A boolean flag to include or exclude subdirectories.
A regular expression to match files against.

require.context(directory, (useSubdirectories = false), (regExp = /^\.\//))

Creating a ‘context’ allows us to create a space where you can pick out all the files matching a regular expression from a particular directory, and manipulate them into manageable formats that are provided back to the component as props to be rendered.

Now that you have all of the blog data, pass it as a prop to the BlogList component.

const Index = props => {
  return (
    <Layout
      pathname="/"
      siteTitle={props.title}
      siteDescription={props.description}
    >
      <section>
        <BlogList allBlogs={props.allBlogs} />
      </section>
    </Layout>
  )
}

export default Index

Then you are free to loop through the blogs and render the list within your BlogList component as you need. Feel free to check out the BlogList component in my starter to see how that data could be handled.

Next Steps

Checkout the final repo!

After setting up your blog or portfolio site, you’ll most likely need a content management system to make editing and updating your posts or data easier. Stay tuned for my next blog on setting up this starter with TinaCMS. In the meantime, you can check out our documentation , or fork the finished Next+Tina blog to start playing with TinaCMS right away.

Where can you keep up to date with Tina?

You know that you want to be part of this creative, innovative, supportive community of developers (and even some editors and designers) who are experimenting and implementing Tina daily.

Tina Community Discord

Tina has a community Discord that is full of Jamstack lovers and Tina enthusiasts. When you join you will find a place:

To get help with issues
Find the latest Tina news and sneak previews
Share your project with Tina community, and talk about your experience
Chat about the Jamstack

Tina Twitter

Our Twitter account (@tina_cms) announces the latest features, improvements, and sneak peeks to Tina. We would also be psyched if you tagged us in projects you have built.

DEV Community: Kendall Strautman

Index Signatures in Typescript

Custom Field Plugins in TinaCMS

Field Plugin vs. Field Component

Getting Started 👏

1. Add the Field Plugin to the CMS

Field Plugin Interface

2. Use the custom field in a form

Short and sweet, as promised 🍰

How to Make a Custom Field Component with TinaCMS

Why would you create a custom field?

Two Methods — Let’s start simple

Creating a custom inline field

Custom Range Slider 🎨

1. Create the input field component

👽 Take a closer look — Props:

Where should the custom field live?

2. Add the value to the source data

3. Add the custom field to a Tina Form

4. Dynamically set the CSS filter

Next Steps

Takeaways 🕺🏻

How to Add and Delete Files with TinaCMS

Tina Overview — sidebar, forms, plugins

Creating New Files

The Steps 🚶‍♀️

Where to add the plugin

Step 1: Set-up a content-creator plugin

Formatting the path to the new file

2. Register the plugin with the sidebar

3. Customize The Create Form

4. Configure Defaults

Deleting Files

Happy Creating (and Deleting)! 👩‍🎤

Using TinaCMS with Next.js

Next.js Recap ▲

Tina Overview 🦙

Let’s Get Started

Set up Locally 🏡

A quick test

Defining the shape of our content

Collections

Fields

References

Creating your content Schema

Making changes to the Schema

Next steps

Creating the getStaticPaths query

Adding this query to your Blog.

Quick break down of getStaticPaths

Creating the getStaticProps query

Creating your Query

Using contextual-editing

Replacing your getStaticProps

Updating the client for useTina

Test & Edit Content ✨

Adding Markdown Support

Update Tina Schema

Updating _app.js

Testing

Where can you keep up to date with Tina?

Tina Community Discord

Tina Twitter

Creating a Markdown Blog with Next.js

Clone the starter

Project Structure

Data Handling

getStaticProps

Layout & Styling

Adding the Posts Directory

Processing Markdown Files

Add Next.js Config

Pages & Dynamic Routing

Get Markdown Data For the Blog Template

getStaticPaths

Get Data For the Blog Index

Next Steps

Where can you keep up to date with Tina?

Tina Community Discord

Tina Twitter

Quick break down of `getStaticPaths`

Creating the `getStaticProps` query

Updating the client for `useTina`

Updating `_app.js`