Introduction

With Tina, your content is stored in Git along with your codebase. Tina provides a Content API in front of your repo-based content, so that you can interact with your files as if they're in a database.

You can:

• Query content for a given collection
• Apply filters, sorting, pagination, etc
• Query your content based on relational fields.

To interface with the API, you can use Tina's type-safe client for data-fetching, or manually write custom GraphQL queries and hit the API yourself.

Making requests with the Tina Client

The Tina client is the easiest way to fetch your site's content. The client can be configured the tina/config.<js|ts> in the defineConfig function.

Note: token, clientId and branch are not used in local-mode. To setup these values for production see this doc

// tina/config.{js,ts,tsx}
export default defineConfig({
  schema,
  token: '***',
  clientId: '***',
  branch: 'main',
});

When working locally, the client is built with the local url (http://localhost:4001/graphql). When in production mode, clientId, branch and token are used to query TinaCloud.

Tina client provides a type-safe query builder, that is auto-generated based on your site's schema:

import { client } from '../[pathToTina]/tina/__generated__/client';

const myPost = await client.queries.post({ relativePath: 'HelloWorld.md' });

console.log(myPost.data.title);

The above client.queries.post query is not built-in to Tina's API. This is an example of a query based on your defined schema, (where you have a "post" collection defined).

On a page that displays a list of posts, you can fetch the posts like so:

const postsResponse = await client.queries.postConnection();
const posts = postsResponse.data.postConnection.edges.map((post) => {
  return { slug: post.node._sys.filename };
});
// This would return an array like: [ { slug: 'HelloWorld.md'}, /*...*/ ]

For more information on manually writing queries for your specific schema, check out our "Writing Custom Queries" docs.

Handling New Pages with Static Site Generation (SSG)

If you're using SSG, creating a new page in TinaCMS means the content updates in TinaCloud and your Git repository instantly. However, your site (based off main or another branch) won't show this new page immediately, often resulting in a 404 error. This is because SSG sites pre-build all pages at deployment time; your server doesn't know about the new page until your site is rebuilt.

Solutions for New SSG Pages:

1. Trigger Rebuilds:
   • The simplest solution is to rebuild and redeploy your site. Most hosting platforms can automate this on Git commits. There will be a build-time delay before the new page is live.
2. Framework-Specific Fallbacks / Dynamic Routes:
   • Modern SSG frameworks (like Next.js, Nuxt.js, SvelteKit, Gatsby, Eleventy) offer ways to handle requests for pages not generated at build time.
     • Next.js: Use fallback: true or fallback: 'blocking' in getStaticPaths to generate pages on demand.
     • Other Frameworks: Look for features like "generate on demand," "incremental builds," or dynamic routing in your framework's documentation. These allow the framework to build the page when it's first requested or use client-side rendering.
3. Incremental Static Regeneration (ISR):
   • Supported by frameworks like Next.js, ISR allows pages to be generated or updated after the initial build, either on a timer or on the first request, without a full site rebuild.

Fetching Content Across Branches in TinaCMS

For server-rendered pages in TinaCMS, you can dynamically fetch content from the active editorial or preview branch by passing the active branch name stored in the x-branch cookie as a header when querying content.

To retrieve cookies in Next.js, refer to the Next.js cookies documentation.

Example Implementation

const data = await client.queries.post(
  {
    relativePath: `${params.filename?.join('/')}.md`,
  },
  {
    fetchOptions: {
      headers: {
        /* Retrieve the active branch from cookie */
        'x-branch': cookieStore.get('x-branch')?.value, 
      },
    },
  }
);

The Local Filesystem-based Content API

When developing locally, it's often beneficial to talk to the content on your local file-system, rather than talk to the hosted content API. Tina provides a CLI tool that lets you run the Content API locally next to your site. This allows all of your content to be made available through the same expressive GraphQL API during development.

If you setup Tina via @tinacms/cli init, or used one of our starters, this should be setup by default. (Read about the CLI here

Video Tutorial

For those who prefer to learn from video, you can check out a snippet on "Data Fetching" from our "TinaCMS Deep Dive" series.

Summary

• Tina provides a GraphQL API for querying your git-based content.
• Tina provides a client that allows you to make type-safe requests to the Content API.
• The client's "queries" property is generated based on your schema.
• A local version of the Content API can be used for local development.
• With SSG, new pages require a rebuild or framework-specific handling (like fallbacks or ISR) to avoid 404s.