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-cliYarn:
yarn add --dev tina-graphql-gateway-cliUsage
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
updateAuthorDocumentYou 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.mdNow 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.mdNow 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