tina-graphql-gateway-cli

The Tina Cloud CLI can be used to set up your project with Tina Cloud configuration, and run a local version of the Tina Cloud content-api (using your file system's content). For a real-world example of how this is being used checkout the Tina Cloud Starter.

Installation

The CLI can be installed as a dev dependency in your project.

Npm:

npm install --save-dev tina-graphql-gateway-cli

Yarn:

yarn add --dev tina-graphql-gateway-cli

Usage

Usage:  command [options]

Options:
  -V, --version           output the version number
  -h, --help              display help for command

Commands:
  server:start [options]  Start Filesystem Graphql Server
  schema:compile          Compile schema into static files for the server
  schema:types            Generate a GraphQL query for your site's schema, (and
                          optionally Typescript types)
  help [command]          display help for command

Getting started

The simplest way to get started is to add a .tina/schema.ts file

mkdir .tina && touch .tina/schema.ts

defineSchema

defineSchema tells the CMS how to build your content API.

// .tina/schema.ts
import { defineSchema } from "tina-graphql-gateway-cli";

export default defineSchema({
  collections: [
    {
      label: "Blog Posts",
      name: "post",
      path: "content/posts",
      templates: [
        {
          label: "Article",
          name: "article",
          fields: [
            {
              type: "text",
              label: "Title",
              name: "title",
            },
            {
              type: "reference",
              label: "Author",
              name: "author",
              collection: "authors",
            },
          ],
        },
      ],
    },
    {
      label: "Authors",
      name: "author",
      path: "content/authors",
      templates: [
        {
          label: "Author",
          name: "basicAuthor",
          fields: [
            {
              type: "text",
              label: "Name",
              name: "name",
            },
            {
              type: "text",
              label: "Avatar",
              name: "avatar",
            },
          ],
        },
      ],
    },
  ],
});

Be sure this is your default export from this file, we'll validate the schema and build out the GraphQL API with it.

Given the example above, we'd end up with the following GraphQL queries available in our GraphQL schema:

# global queries, these will be present regardless of the shape of your schema:
getDocument
getCollection
getCollections
# global mutations
addPendingDocument
updateDocument

# schema-specific queries.
getPostDocument
getPostList
getAuthorDocument
getAuthorList
# schema-specific mutations
updatePostDocument
updateAuthorDocument

You can find your generated schema at /.tina/__generated__/schema.gql for inspection.

collections

The top-level key in the schema is an array of collections, a collection informs the API about where to save content. You can see from the example that a posts document would be stored in content/posts, and it can be the shape of any template from the templates key.

templates

Templates are responsible for defining the shape of your content, you'll see in the schema for the starter that we use templates for collections as well as blocks. One important thing to note is that since a collection can have multiple templates, each file in your collection must store a _template key in it's frontmatter:

---
title: Vote For Pedro
author: content/authors/napolean.md
_template: article
---

When you use Tina's GraphQL forms, we know about all of the relationships in your content, this allows us to keep your content in-sync with your form state. Try changing the author in the sidebar, notice the author data changes to reflect your new author!

fields

For the most part, you can think of fields as the backend equivalent to Tina field plugins. You might notice that we're defining a type on each field, rather than a component. This is because the backend isn't concerned with components, only the shape of your content. By default we use the built-in Tina fields, to customize your component read the field customization instructions.

reference & reference-list

In addition to the core Tina fields, we also have reference and reference-list fields. These are important concepts, when you reference another collection, you're effectively saying: "this document belongs to that document". In the article template above, we're saying posts with an article template belong to authors. This is a powerful way to connect your content, and the tina-graphql-gateway client knows how to build forms to reflect these relationships.

When you query across multiple documents, you'll see a select field for the related content, and by changing those values you'll see your query data updated automatically.

Run the local GraphQL server

Let's add some content so we can test out the GraphQL server

Add an author

mkdir content && mkdir content/authors && touch content/authors/napolean.md

Now let's add some content to the author

---
name: Napolean
avatar: https://images.unsplash.com/photo-1606721977440-13e6c3a3505a?ixid=MXwxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHw%3D&ixlib=rb-1.2.1&auto=format&fit=crop&w=344&q=80
_template: basicAuthor
---

Add a post

mkdir content/posts && touch content/posts/voteForPedro.md

Now we add some content to the post

---
title: Vote For Pedro
author: content/authors/napolean.md
_template: article
---

When you use Tina's GraphQL forms, we know about all of the relationships in your content, this allows us to keep your content in-sync with your form state. Try changing the author in the sidebar, notice the author data changes to reflect your new author!

Start the server

yarn run tina-gql server:start

Query the content

With a GraphQL client, make the following request:

Tip: Use a GraphQL client like Altair when developing locally.

getPostsDocument(relativePath: "voteForPedro.md") {
  data {
    __typename
    ... on Article_Doc_Data {
      title
      author {
        data {
          ... on BasicAuthor_Doc_Data {
            name
            avatar
          }
        }
      }
      _body
    }
  }
}

To learn how to work with this data on a Tina-enabled site, check out the client documentation

This API is currently somewhat limited. Specifically there's no support for filtering and sorting "list" queries. We have plans to tackle that in upcoming cycles