DEV Community: Tina

Markdown Bot - An AI friend who improves your content

scottgallant — Fri, 21 Jul 2023 17:19:30 +0000

With TinaCMS, all your content changes are committed directly to Git. This enables your team to create a variety of workflows for reviewing and merging content updates. By leaning on GitHub, you can integrate CI/CD into your content workflow.

To illustrate the potential of this combination, we're excited to introduce Markdown Bot, an AI friend who improves your content by making suggestions to your Pull Requests.

Want to skip the reading and jump straight to the code? Check out the open source repo.

A Useful Aid, Not a Replacement

AI can be a valuable tool for assisting with writing and editing content. We've designed this bot not to replace content editors, but rather to augment their capabilities. The bot offers content suggestions directly in your pull requests. If you find the suggestions helpful, you can commit them with a click. If not, they're just as easily dismissed.

Markdown Bot Works On Your PRs

There are many AI writing tools out there but if you use them with markdown content it often involved copying and pasting from AI outputs. We wanted something that could interact with our Content in GitHub. That's why we developed a GitHub bot that allows us to receive these suggestions right within a GitHub pull request.

Working with the GitHub Bot

After you've integrated the bot into your repository, you can command it to make suggestions by commenting ai fix: <path to file>. A custom prompt can be added by using prompt: <Custom Prompt> underneath. The bot will then offer commit suggestions in the form of a pull request review.

To get started check out the open source repo.

Looking Ahead: AI and Git-based Content

Our GitHub bot works hand in hand with TinaCMS to enhance the content creation process. No longer do you need to manually copy and paste suggestions. The bot brings suggestions right to your pull requests for a smooth, efficient experience.

We can envision some impressive custom workflows being built with AI and Git-based content. For instance, you could build off of this bot to:

Trigger the AI bot with custom events, such as opening a PR.
Utilize analytics to suggest recommendations based on your top/bottom performing pages.
Integrate this bot with your feedback widget, to open PRs based on user feedback.
Catch insensitive, inconsiderate writing with tools like alex

These are just a few of the many possibilities we see for integrating AI with Git-based content. We're excited about the potential here and look forward to seeing the creative workflows that the community will build.

A/B testing with Next.js Middleware and TinaCMS

James Perkins — Fri, 03 Jun 2022 12:56:16 +0000

A/B testing can be an incredibly useful tool on any site. It allows you to increase user engagement, reduce bounce rates, increase conversion rate and effectively create content.

Tina opens up the ability to A/B test, allowing marketing teams to test content without the need for the development team once it has been implemented.

Introduction

We are going to break this tutorial into two sections:

Setting up A/B Tests with NextJS's middleware.
Configuring our A/B Tests with Tina, so that our editors can spin up dynamic A/B Tests.

Creating our Tina application

This blog post is going to use the Tailwind Starter. Using the create-tina-app command, choose "Tailwind Starter" as the starter template:

# create our Tina application

npx create-tina-app@latest a-b-testing

✔ Which package manager would you like to use? › Yarn
✔ What starter code would you like to use? › Tailwind Starter
Downloading files from repo tinacms/tina-cloud-starter. This might take a moment.
Installing packages. This might take a couple of minutes.

## Move into the directory and make sure everything is updated.

cd a-b-testing
yarn upgrade
yarn dev

With your site running, you should be able to access it at [http://localhost:3000](http://localhost:3000)

Planning our tests

The home page of the starter should look like this:

This page is already setup nicely for an A/B test, its page layout ([slug].tsx) renders dynamic pages by accepting a variable slug.

Let's start by creating an alternate version of the homepage called home-b. You can do so in Tina at http://localhost:3000/admin#/collections/page/new

Once that's done, go to: http://localhost:3000/home-b to confirm that your new /home-b page has been created.

Setting up our A/B tests

Utlimately, we want our site to dynamically swap out certain pages for alternate page-variants, but we will first need a place to reference these active A/b tests.

Let's create the following file at content/ab-test/index.json:

{
  "tests": [
    {
      "testId": "home",
      "href": "/",
      "variants": [
        {
          "testId": "b",
          "href": "/home-b"
        }
      ]
    }
  ]
}

We'll use this file later to tell our site that we have an A/B test on our homepage, using /home-b as a variant.

In the next step, we'll setup some NextJS middleware to dynamically use this page variant.

Delivering dynamic pages with NextJS middleware

NextJS's middleware allows you to run code before the request is completed. We will leverage NextJS's middleware to conditionally swap out a page for its page-variant.

You can learn more about NextJS's middleware here.

Start by creating the pages/_middleware.ts file, with the following code

//pages/_middleware.ts

import { NextRequest, NextResponse } from 'next/server'
import abTestDB from '../content/ab-test/index.json'
import { getBucket } from '../utils/getBucket'

// Check for AB tests on a given page
export function middleware(req: NextRequest) {
  // find the experiment that matches the request's url
  const matchingExperiment = abTestDB.tests.find(
    test => test.href == req.nextUrl.pathname
  )

  if (!matchingExperiment) {
    // no matching A/B experiment found, so use the original page slug
    return NextResponse.next()
  }

  const COOKIE_NAME = `bucket-${matchingExperiment.testId}`
  const bucket = getBucket(matchingExperiment, req.cookies[COOKIE_NAME])

  const updatedUrl = req.nextUrl.clone()
  updatedUrl.pathname = bucket.url

  // Update the request URL to our bucket URL (if its changed)
  const res =
    req.nextUrl.pathname == bucket.url
      ? NextResponse.next()
      : NextResponse.rewrite(updatedUrl)

  // Add the bucket to cookies if it's not already there
  if (!req.cookies[COOKIE_NAME]) {
    res.cookie(COOKIE_NAME, bucket.id)
  }

  return res
}

There's a little bit going on in the above snippet, but basically:

We check if there's an active experiment for our request's URL
If there is, we call getBucket to see which version of the page we should deliver
We update the user's cookies so that they consistently get delivered the same page for their given bucket.

You'll notice that the above code references a getBucket function. We will need to create that, which will conditionally put us in a bucket for each page's A/B test.

// /utils/getBucket.ts

export const getBucket = (matchingABTest: any, bucketCookie?: string) => {
  // if we already have been assigned a bucket, use that
  // otherwise, call getAssignedBucketId to put us in a bucket
  const bucketId =
    bucketCookie ||
    getAssignedBucketId([
      matchingABTest.testId,
      ...matchingABTest.variants.map(t => t.testId),
    ])

  // check if our bucket matches a variant
  const matchingVariant = matchingABTest.variants.find(
    t => t.testId == bucketId
  )

  if (matchingVariant) {
    // we matched a page variant
    return {
      url: matchingVariant.href,
      id: bucketId,
    }
  } else {
    //invalid bucket, or we're matched with the default AB test
    return {
      url: matchingABTest.href,
      id: matchingABTest.testId,
    }
  }
}

function getAssignedBucketId(buckets: readonly string[]) {
  // Get a random number between 0 and 1
  let n = cryptoRandom() * 100
  // Get the percentage of each bucket
  const percentage = 100 / buckets.length
  // Loop through the buckets and see if the random number falls
  // within the range of the bucket
  return (
    buckets.find(() => {
      n -= percentage
      return n <= 0
    }) ?? buckets[0]
  )
}

function cryptoRandom() {
  return crypto.getRandomValues(new Uint32Array(1))[0] / (0xffffffff + 1)
}

The above code snippet does the following:

Checks if we're already in a bucket, and if not, it calls getAssignedBucketId to randomly put us in a bucket.
Returns the matching A/B test info for our given bucket.

That should be all for our middleware! Now, you should be able to visit the homepage at http://localhost:3000, and you will have a 50-50 chance of being served the contents of home.md, or home-b.md. You can reset your bucket by clearing your browser's cookies.

Using Tina to create A/B Tests

At this point, our editors can edit the contents of both home.md & home-b.md, however we'd like our editors to be empowered to setup new A/B tests.

Let's make our content/ab-test/index.json file from earlier editable, by creating a Tina collection for it.

Open up your schema.ts and underneath the Pages collection, create a new collection like this:

/// ...,
    {
      label: "AB Test",
      name: "abtest",
      path: "content/ab-test",
      format: "json",
    }

We now need to add the fields we want our content team to be able to edit, so that would be the ID, the page to run the test against, and the variants we want to run. We also want to be able to run tests on any number of pages so we will be using a list of objects for the tests field.

If you want to learn more about all the different field types and how to use them, check them out in our Content Modeling documentation.

    {
      label: "AB Test",
      name: "abtest",
      path: "content/ab-test",
      format: "json",
      fields: [
        {
          type: "object",
          label: "tests",
          name: "tests",
          list: true,
          ui: {
            itemProps: (item) => {
              return { label: item.testId || "New A/B Test" };
            },
          },
          fields: [
            { type: "string", label: "Id", name: "testId" },
            {
              type: "string",
              label: "Page",
              name: "href",
              description:
                "This is the root page that will be conditionally swapped out",
            },
            {
              type: "object",
              name: "variants",
              label: "Variants",
              list: true,
              ui: {
                itemProps: (item) => {
                  return { label: item.testId || "New variant" };
                },
              },
              fields: [
                { type: "string", label: "Id", name: "testId" },
                {
                  type: "string",
                  label: "Page",
                  name: "href",
                  description:
                    "This is the variant page that will be conditionally used instead of the original",
                },
              ],
            },
          ],
        },
      ],
    }

You may notice the ui prop. We are using this to give a more descriptive label to the list items. You can read about this in our extending Tina documentation.

We also need to update our RouteMappingPlugin in .tina/schema.ts to ensure that our collection is only editable with the basic editor.

      const RouteMapping = new RouteMappingPlugin((collection, document) => {
        if (collection.name == 'abtest') {
          return undefined
        }
        // ...

Now, restart your dev server, and go to: [http://localhost:3000/admin#/collections/abtest/index](http://localhost:3000/admin#/collections/abtest/index). Your editors should be able to wire up their own A/B tests!

The process for editors to create new A/B tests would be as follows:

Editor creates a new page in the CMS
Editor wires up the page as a page-variant in the "A/B Tests" collection

And that's it! We hope this empowers your team to start testing out different page variants to start optimizing your content!

How to keep up to date with Tina?

The best way to keep up with Tina is to subscribe to our newsletter. We send out updates every two weeks. Updates include new features, what we have been working on, blog posts you may have missed, and more!

You can subscribe by following this link and entering your email: https://tina.io/community/

Tina Community Discord

Tina has a community Discord 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 the 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.

Automating Pull Requests

James Perkins — Thu, 14 Apr 2022 14:33:19 +0000

When working on a git-backed site, you don’t normally want to work directly on your main branch. Ideally, you want to be able to finish your post or site update, check if it looks good, and schedule the release. In this post, we are going to cover two different options to automate your PRs to make scheduling content easier.

PR Scheduler

PR Scheduler is a GitHub integration that can be installed directly within your GitHub repositories. It was built by Tom Kadwill with the goal to make it easy to schedule pull requests. PR Scheduler lets developers schedule PRs to be merged at a specific time. Instead of having to write your own GitHub action, you can write a comment in your pull request and the application will take care of it for you.

How to install

Open PR Scheduler's GitHub App page.
Click the 'Install' button
Select whether to install PR Scheduler on all repositories or only specific repositories. Then click 'Install'.

How to schedule a pull request

Now, the PR Scheduler can now be used to schedule any of your pull requests. To initiate,do the following:

Open the pull request that you want to schedule.
Add a new comment with DD/MM/YYYTHH:MM for example @prscheduler 05/04/2022T14:00
PR Scheduler will respond back telling you it's ready.

That's it! Now when that time comes, your PR will be merged. If you make a mistake with the time or date, just run the same command and it will reschedule.

Github Actions

Github Actions are a powerful and flexible way to allow you to run all sorts of DevOps workflows without needing separate tooling. Github Actions uses YAML to define workflows. This makes a great option for scheduling your pull requests where you want to have maximum control.

Creating your GitHub Action

Create a file in your project called .github/workflows/scheduler.yml. We will use this to create our action.

There are quite a few options for Github Actions. I have used merge-schedule-action in multiple personal projects, it has create customization and is easy to use. This action takes a few different arguments and uses the date to schedule your PR:

name: Merge Schedule
on:
  pull_request:
    types:
      - opened
      - edited
      - synchronize
  schedule:
    # Check every hour.
    - cron: 0 * * * *

jobs:
  merge_schedule:
    runs-on: ubuntu-latest
    steps:
      - uses: gr2m/merge-schedule-action@v1
        with:
          merge_method: merge
          #  Time zone to use. Default is UTC.
          time_zone: "America/New_York"
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

So let us break down what is happening. We have given this job a name of Merge Schedule. It will only trigger on pull requests that are opened, edited, or synchronized. Every hour we run a job called merge_schedule, thanks to the cronjob 0 * * * *

The steps inside of the jobs section are the most important, it tells GitHub what to do when the schedule runs. First, the job needs to use gr2m/merge-schedule-action@v1 and tell it the merge method to use. I have set it to merge but you could use squash if you prefer. The time_zone is t set to UTC by default, but can be any time zone you need.

The GITHUB_TOKEN doesn’t need to be set, since GitHub will retrieve a GITHUB_TOKEN to use for the account.

If you want to read more about triggering GitHub actions check out there documentation https://docs.github.com/en/github-ae@latest/actions/using-workflows/events-that-trigger-workflows

How to run the action

Now that we have created the action, when you create a pull request, you need to add /schedule YYYY-MM-DD to your pull request description. This Github Action will run on the schedule defined in the cron statement and check for PRs where the date matches and then deploy the code. If you need precise deployments you can use /schedule 2019-12-31T00:00:00.000Z.

How to keep up to date with Tina?

The best way to keep up with Tina is to subscribe to our newsletter, we send out updates every two weeks. Updates include new features, what we have been working on, blog posts you may have missed, and so much more!

You can subscribe by following this link and entering your email: https://tina.io/community/

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.

Read-only tokens - Query Requests anytime

James Perkins — Tue, 05 Apr 2022 13:56:09 +0000

Read-only tokens allow you to query data from your project at any point in your application, whether that is on the server or on the client. Prior to Read-only tokens everything Tina did was through getStaticProps or getStaticPaths. This, for the most part, would handle most cases when using a headless CMS with an SSG. However as we move towards the 1.0 release of TinaCMS we want to be able to support more frameworks including React, Remix, and Gatsby.

Some use cases for Read-only tokens

Below are some use cases for Read-only tokens

Server Side Rendering
Client Side fetching
Runtime server logic

How to use Read-only tokens?

Before you start with Read-only tokens you will need to make sure the repository you are using has the data layer enabled. This is required for the read-only tokens to work and also be performant.

Create a token from the dashboard

Navigate to Tina Cloud and click on the project you wish to add a token to, click on the "tokens" tab

Next, click "New Token" and fill out the fields required. The token name is how you can identify the token and "Git branches" is the list of branches separated by commas that the token has access to.

Finally, click "Create Token".

Ready for requests

At this point you are now ready to make requests using the Read-only token. I have put together some examples of different use cases, they include SSR, CSR, SSG with fallback which should satisfy most use cases with Tina.

SSR - Server Side Rendering content

In most cases your content will be statically generated at build time, but on occasion you might need to use SSR in your Tina-powered app. It could be a page that isn’t powered by Tina but you are using our graphQL layer to power your whole application.

const query = `
    getPostDocument(example.md) {
      data {
        title
        body
      }
  }
  `;

export async function getServerSideProps(context) {
    let data
    const res = await fetch(
      'https://content.tinajs.io/content/<CLIENT_ID>/github/<BRANCH>',
      {
        method: 'POST',
        body: JSON.stringify({ query, variables }),
        headers: {
          'X-API-KEY': 'API_KEY',
          'Content-Type': 'application/json',
        },
      }
    );
    const jsonData = await res.json();
    data = jsonData.data;
  return {
    props: {
        data,
        query,
        variables,                      
}, // will be passed to the page component as props
  }
}

Every time a user returns to this page, they will receive a freshly served page with the latest content from Tina.

CSR - Client Side Rendering

Client side rendering can be a great way to keep content on the page up to date, every-time someone visits a page. Tina content can be retrieved using your favorite http client such as fetch or axios.

import { useState, useEffect } from "react";
import { useTina } from "tinacms/dist/edit-state";
// This is a query you want.
const query = `
query ContentQuery($relativePath: String!) {
  get<CollectionName>Document(relativePath: $relativePath) {
    data {
      body
      title
    }
  }
}
`;

// Variables used in the GraphQL query;
const variables = {
  relativePath: "HelloWorld.md",
};

function BlogPostPage() {
  const [initalData, setData] = useState(null);
  const [isLoading, setLoading] = useState(false);

  useEffect(() => {
    setLoading(true);
    fetch(
      "https://content.tinajs.io/content/<ClientId>/github/<Branch>",
      {
        method: "POST",
        body: JSON.stringify({ query, variables }),
        headers: {
          "X-API-KEY": "<ReadOnlyToken>",
          "Content-Type": "application/json",
        },
      }
    )
      .then((res) => res.json())
      .then((data) => {
        console.log({ data });
        setData(data);
        setLoading(false);
      })
      .catch((e) => {
        console.error(e);
      });
  }, [query, JSON.stringify(variables)]);

  const { data } = useTina({ query, variables, data: initalData });

  if (isLoading) return <p>Loading...</p>;
  if (!data) return <p>No data</p>;

  return <div>{JSON.stringify(data)}</div>;
}
export default BlogPostPage;

As you can see for this example we are using useEffect to fetch the data from Tina using our read-only token. The URL you see is powered by your clientId and GitHub branch of choice. We then set the data to use useTina and present the data through the UI.

SSG with Fallback

Up until now most Tina users use fallback: blocking for creating new pages with Tina.

This comes with issues:

You no longer have fallback pages by default (404 pages), any navigation will be served even if it’s a blank page.
You need a way to handle when there is data, no data or no page.

With Read-only tokens this has a lot less developer friction and a better user experience, we can break the getStaticsProps code into three paths.

Data is returned (this is the code you’ve had before)
Data is not returned, so fetch it using read-only tokens. If it’s there, return it.
Data is not returned, data is not returned using read-only tokens, so return a fallback page.

import { staticRequest } from 'tinacms';

const query = `query getPost($relativePath: String!) {
    getPostDocument(relativePath: $relativePath) {
      data {
        title
        body
      }
    }
  }
  `;

export const getStaticProps = async (ctx) => {
  const variables = {
    relativePath: ctx.params.slug + ".md",
  };
  let data;
  let error;
  error = false;

  try {
    // use the local client at build time
    data = await staticRequest({
      query,
      variables,
    });
  } catch (error) {
    // swallow errors related to document creation
  }
  // if there isn't data set the error flag
  if (!data) {
    error = true;
  }
  if (error) {
    // use read-only tokens to get live data
    const res = await fetch(
      'https://content.tinajs.io/content/<CLIENT_ID>/github/<BRANCH>',
      {
        method: 'POST',
        body: JSON.stringify({ query, variables }),
        headers: {
          'X-API-KEY': 'API_KEY',
          'Content-Type': 'application/json',
        },
      }
    );
    const jsonData = await res.json();
    data = jsonData.data;
    // if there is no data set the notFound true (This returns 404
    if (!data) {
      return {
        notFound: true,
      };
    }
  }

  return {
    props: {
      data,
      query,
      variables,
    },
  };
};

The code above does a lot of different things, so let us break it down into the sections stated previously:

The original request which produces data, will return data, query and variables.
If there is no data returned, we set the error flag to true. If the error flag is true, we attempt to use read-only tokens to retrieve your data and return it to be displayed to the user, or to the content editor.
If there is no data returned and the read-only token returns no data, we return notFound: true (this is a special flag for Next.js). This flag will return your 404 error page as well as 404 in the status code.

How to keep up to date with Tina?

You can subscribe by following this link and entering your email: https://tina.io/community/

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.

Tina Data Layer: Performant Editing

James Perkins — Wed, 30 Mar 2022 13:19:54 +0000

Tina has worked on the premise of direct interaction with Tina's GraphQL API and GitHub’s API. While this is a perfectly acceptable option, it does reduce performance slightly due to the nature of sending and retrieving data as “new” each time.

The Tina team recently introduced a new optional data layer that sits between Tina and GitHub. In the future, this will be our default offering once it is out of the experimental stage. Our data layer buffers the requests between Tina and GitHub, increasing performance while editing your content. This blog post is going to explain how it works, what it does and what we have planned for the future!

How to enable the Data Layer on your project

We made enabling and using the Data Layer with minimal development required. In fact you can enable the data layer by passing --experimentalData as a command line flag. The easiest way to make sure this happens is by editing your package.json script.

"scripts": {
    "dev": "yarn tinacms server:start -c \"next dev\"",
    "build": "yarn tinacms server:start -c \"next build\"",
    "start": "yarn tinacms server:start -c \"next start\" --experimentalData",
  },

Once the flag is added and the CLI has been run, Tina will update the generated schema letting Tina know you want to use the Data Layer.

Once you have generated the Schema, you will need to commit the changes to GitHub for it to start working on the project.

What does the Data Layer do to increase Performance?

Once the Data Layer is enabled on your project, we will automatically synchronize a copy of your repository with our secure cloud database. After Tina has run the initial indexing of your repository, Tina will automatically index new or updated content. This is done behind the scenes and you won’t notice that we are doing this, except the increase in performance when editing.

When we might do a full re-index

In some cases we might have to fully re-index your project. This usually happens when the schema of your project has changed. For example:

Changes to .tina\schema.ts
Changes to the path to .tina

Some things to note

This is still an experimental feature and the following things should be considered before enabling it on your project:

1. The indexing process isn’t exposed to the end user, which means it is possible that queries made during the indexing process could return incomplete results.

2. GitHub has a API request limitation of 5000 requests per repository per hour. If you have an extremely large project you could hit this rate limit. If you have a repository with more than 1500 items, please do not activate this feature.

The future

The team at Tina has plans for the following highly requested features as the Data Layer matures out of its experimental phase. In fact we have already begun working on some of the features mentioned below, so stay tuned!

More complex and advanced queries

The Data Layer opens up our GraphQL layer to be even more powerful, in the future Tina plans to offer:

This means you will be able to reduce some of your calls if you don’t need a full data set. A good example of this would be where you only need 3 blog posts for a features section. In the current Tina integration, you need to retrieve all of the posts and filter them down after the fact. In the future you won’t need to do this.

Referential Integrity

With the introduction of the Data Layer it allows us to now be able to offer referential integrity. This will stop a content writer from accidentally making changes to content that could break other content or an entire site. The biggest benefit to a content user will be the ability to rename files or even delete content without breaking any existing references.

From CMS To Contextual Editing

James Perkins — Thu, 20 Jan 2022 16:38:09 +0000

Tina allows you as a developer to create an amazing editing experience. By default the editing experience is a more traditional CMS, where you login to a specific URL and you edit your content without being able to see the content till after you finish your changes. But, if you are looking for a more transparent real-time editing experience, Tina has a superpower, called Contextual Editing. Just as it sounds, you get instant feedback on the page as well as being able to preview the changes before publishing live to your site.

Getting our project started

For this blog post we are going to use Tina’s example which is located in the Next.js official examples and allows us to use create-next-app.This example is based upon Next.js blog starter which is a markdown blog.

You can find the source code in the Next.js examples directory, https://github.com/vercel/next.js/tree/canary/examples/cms-tina.

## Create our new Tina site

npx create-next-app --example cms-tina tina-contextual-editing

## Move into our app.

cd tina-contextual-editing

## Open with your favorite editor

If you want to learn how this example was created check out the blog post that covers getting started with Tina.

What does the Tina code do?

Before you add any code to this example, I want to cover how Tina is integrated and how it works.

`.tina` folder

You will find a .tina folder in the root of the project, this is the heart and brain of Tina in any project.

`schema.ts`

The schema file contains two important pieces of code defineSchema and defineConfig. The defineSchema allows you to define the shape of your content. If you have used a more traditional CMS before you may have done this via a GUI. However, given how Tina is tightly coupled with Git and we treat the filesystem as the “source of truth”, we take the approach of “content-modeling as code”.

If you look at the current defined schema, you will see that each one of the fields is related to the front matter contained within any of the posts in the _posts folder.

Moving on to the defineConfig, the defineConfig tells your project where the content is requested from, what branch to use, and any configuration to TinaCMS itself.

`components`

The components folder inside the .tina holds both our TinaProvider and DynamicTinaProvider; these two components wrap your application with the power of Tina. We will be heading back here later for some updates.

`_generated__`

This folder holds all the auto generated files from Tina, if you open this up you will see files that contain queries, fragments and types. You won’t need to make changes here but it’s good to know what you might find in there.

Before we add contextual editing, go ahead and launch the application using yarn tina-dev and navigate to http://localhost:3000/. You will notice that it is a static blog. Feel free to navigate around and get a feel for the blog.

Now if you navigate to http://localhost:3000/admin you will be presented with a screen to login, if you login you will land on the CMS dashboard. Selecting a collection on the left will bring you to a screen with all the current files in that space. Then selecting a file will allow you to edit it as you see fit.

Adding Contextual Editing.

Now you have an understanding of both how the CMS works, and how the code behind is laid out we can start working on adding contextual editing to our project. What do we need to do to make contextual editing work?

Update getStaticPaths and getStaticProps to use Tina’s graphql layer
Update the page to use useTina and power the project props
Update the TinaCMS configuration

Creating the getStaticPaths query

The getStaticPaths query is going to need to know where all of our markdown files are located. With our current schema you have the option to use getPostsList, which will provide a list of all posts in our _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 getPostsList we will want to query the sys which is the filesystem and retrieve the filename, which will return all the filenames without the extension.

query {
  getPostsList {
    edges {
      node {
        sys {
          basename
        }
      }
    }
  }
}

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

{
  "data": {
    "getPostsList": {
      "edges": [
        {
          "node": {
            "sys": {
              "filename": "dynamic-routing"
            }
          }
        },
        {
          "node": {
            "sys": {
              "filename": "hello-world"
            }
          }
        },
        {
          "node": {
            "sys": {
              "filename": "preview"
            }
          }
        }
      ]
    }
  }
}

Adding this query to our Blog.

The NextJS starter blog is served on the dynamic route /pages/posts/[slug].js. 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 we can update it to use our own code. The first step is to add an import to the top of the file to be able interact with our graphql, and remove the getPostBySlug and getAllPosts imports we won’t be using:

//other imports
.....
- import { getPostBySlug, getAllPosts } from '../../lib/api'
+ import { staticRequest } from "tinacms";

Inside of the getStaticPaths function we can construct our request to our content-api. When making a request we expect a query or mutation and then variables if needed to be passed to the query, here is an example:

staticRequest({ query: '...', // our query }),

“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.

We can use the getPostsList query from earlier to build our dynamic routes:

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

Quick break down of getStaticPaths

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

Creating getStaticProps query

Creating the query

The getStaticProps query is going to deliver all the content to the blog, which is how it works currently with the code provided by Next.js. When we use the GraphQL API we will both deliver the content and give the content team the ability to edit it right in the browser.

We need to query the following things from our content api:

Title
Excerpt
Date
Cover Image
OG Image data
Author Data
Body content

Creating our Query

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

query BlogPostQuery($relativePath: String!) {
  getPostsDocument(relativePath: $relativePath) {
    # data from our posts.
  }
}

We can now fill in the relevant fields we need to query, take special note of both author and ogImage which are grouped so they get queried as:

author {
  name
  picture
}
ogImage {
  url
}

Once you have filled in all the fields you should have a query that looks like the following:

query BlogPostQuery($relativePath: String!) {
  getPostsDocument(relativePath: $relativePath) {
    data {
      title
      excerpt
      date
      coverImage
      author {
        name
        picture
      }
      ogImage {
        url
      }
      body
    }
  }
}

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

Adding our query to our blog

Remove all the code inside of the getStaticProps function and we can update it to use our own code. Since these pages are dynamic, we’ll want to use the values we returned from getStaticPaths in our query. We’ll destructure params to obtain the slug, using it as a relativePath. As you’ll recall the “Blog Posts” collection stores files in a folder called _posts, so we want to make a request for the relative path of our content. Meaning for the file located at _posts/hello-world.md, we only need to supply the relative portion of hello-world.md.

export const getStaticProps = async ({ params }) => {
  const { slug } = params
  // Ex. `slug` is `hello-world`
  const variables = { relativePath: `${slug}.md` }
  // ...
}

We’ll also want to call staticRequest to load our data for our specific page. You’ll also notice that we will return the query & variables from getStaticProps. We’ll be using these values within the TinaCMS frontend.

import { staticRequest } from 'tinacms'

So the full query should look like this:

export const getStaticProps = async ({ params }) => {
  const { slug } = params
  const variables = { relativePath: `${slug}.md` }
  const data = await staticRequest({
    query: query,
    variables: variables,
  })

  return {
    props: {
      data,
      variables,
    },
  }
}

You may have noticed that our query isn’t there but we are referencing it. This is because we want to be able to reuse the query for our useTina hook. At the top of our file, after the imports you can add the query:

const query = `query BlogPostQuery($relativePath: String!) {
  getPostsDocument(relativePath: $relativePath) {
    data {
      title
      excerpt
      date
      coverImage
      author {
        name
        picture
      }
      ogImage {
        url
      }
      body
    }
  }
}`

Adding `useTina` hook

The useTina hook is used to make a piece of Tina content editable. It is code-split so in production, this hook will pass through the data value. When you are in edit mode, it registers an editable form in the sidebar.

Adding imports

The first thing that needs to be done is import useTina, useEffect and useState. We can also remove a few imports that we will no longer be using.

import {useState, useEffect} from 'react'
import {useTina} from 'tinacms/dist/edit-state'

Changing our props and adding UseTina

We are going to update our props from ({ post, morePosts, preview }) to (props). We are going to pass the props into our useTina hook. Now that has been updated with the props coming in we can use useTina .


- export default function Post({ post, morePosts, preview }) {
+ export default function Post( props ) {


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

As you can see, we are reusing our query from before and passing the variables, and data to useTina. This now means we can power our site using contextual editing. Congratulations your site now has superpowers!

Update our elements to use Tina data

Now we have access to our Tina powered data we can go through and update all of our elements to use Tina. You can replace each of the post. with data.getPostsDocument.data. and then replace the !post?.slug with !props.variables.relativePath when you are finished your return code should look like:

const router = useRouter()
-  if (!router.isFallback && !post?.slug) {
+  if (!router.isFallback && !props.variables.relativePath) {
    return <ErrorPage statusCode={404} />
  }
  return (
-   <Layout preview={preview}>
+   <Layout preview={false}>
      <Container>
        <Header />
        {router.isFallback ? (
          <PostTitle>Loading…</PostTitle>
        ) : (
          <>
            <article className="mb-32">
              <Head>
                <title>
-                  {post.title} | Next.js Blog Example with {CMS_NAME}
+                  {data.getPostsDocument.data.title} | Next.js Blog Example with {CMS_NAME}
                </title>
-                <meta property="og:image" content={post.ogImage.url} />
+                <meta property="og:image" content={data.getPostsDocument.data.ogImage.url} />
              </Head>
              <PostHeader
-                title={post.title}
-                coverImage={post.coverImage}
-                date={post.date}
-                author={post.author}
+                title={data.getPostsDocument.data.title}
+                coverImage={data.getPostsDocument.data.coverImage}
+                date={data.getPostsDocument.data.date}
+                author={data.getPostsDocument.data.author}
              />
-             <PostBody content={post.content} />              
+             <PostBody content={data.getPostsDocument.data.body} />
            </article>
          </>
        )}
      </Container>
    </Layout>

  )

The final piece of Contextual Editing.

One piece of code that the original was doing was taking the markdown and turning it into HTML, inside of the getStaticPriops. We currently aren’t doing that with our body and just returning the string. Due to the nature of contextual editing, we need to make sure that we are always passing the latest content through the markdownToHtml function provided by the team at Next.js. This is where useState and useEffect come in, first create a content variable that is track by a state:

Note you could use another markdown to html package that would not require this, but in this example we want to reuse as much of the original code as possible to show how you could integrate with minimal code replacement.

const [content, setContent] = useState('')

Then in useEffect we are going to parse our body to the markdownToHtml code provided by the Next.js team and set it to content.

useEffect(() => {
      const parseMarkdown = async () => {
        setContent(await markdownToHtml(data.getPostsDocument.data.body))
      } 
      parseMarkdown()
     }, [data.getPostsDocument.data.body])

Now all we need to do is update our post body content from data.getPostsDocument.data.body to content . If you go ahead and test your application now, you can now edit on the page!

Next steps

Now that you have contextual editing here are a few things you can explore with Tina

How to keep up to date with Tina?

You can subscribe by following this link and entering your email: https://tina.io/community/

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.

New Year, New CMS?

James Perkins — Thu, 06 Jan 2022 15:29:21 +0000

Here we are, the new year is upon us, and if you are like us, you have set some New Year’s resolutions for yourself. We are big fans of the fresh start and self-improvement that comes along with this time of year. Have you set any resolutions, maybe building or rebuilding your own personal site, starting a new business, or giving your portfolio a new lick of pain?. That means that you will need a CMS to handle all the content that drives your site and we think Tina can fill the role in some unique ways.

Why Tina?

Git Backed

Traditionally when you sign up for a CMS, your content is locked into the vendor. This means if you decide that the CMS is not for you, you have to find a way to export that data and import it into your new CMS. That is not what Tina is about, we don’t want to hold you or your content hostage. In fact, Tina doesn’t store any of your data, it is stored in a GitHub repository that you own. Yep, that is right, you own and control it all. In addition to feeling secure that you own your own content, there are many practical advantages to this approach such as:

Easy to track when and what changed in your project
CI / CD support
No vendor lock in

Contextual Editing

Tina is different from a traditional headless CMS, where you enter your data into a form with no context of how it will behave or look on your site. You then have to kick off a build and navigate to your site to see the changes.
When you use Tina, the content is edited using a sidebar on your site, you get to see the changes in real time as you make them. This allows you to see exactly what you are editing or creating and how it will look and behave. No more saves, previews, refreshes after every few edits. Once you are happy with the changes, you can hit save and Tina will commit it directly to your GitHub repository and the rebuild process will begin.

Native MDX Support

Tina can support MDX out of the box, this means you can create reusable components and Tina can provide an easy way for anyone editing or creating content to add them to the page, no matter how experienced they are.

Other headless CMSs require the users who are creating the content to remember the Component names, use the correct syntax when using them, as well as transform the data using mdx-remote or something similar. This is fine for an experienced developer but if you want to bring on guests who have zero experience it is a steep learning curve. Seriously, ask your editor friends about this, see the rage and/or fear in their eyes.

We include a button that will allow anyone to click, select the user-friendly named component, and add it to the page. They can then dynamically edit that component with the correct text, images, or styles that you defined.
Tina also doesn’t require you to transform the MDX or hydrate your components, making it easier to integrate then traditional CMS.

Three ways to get started in under five minutes

Tina Quickstart

Our Tina QuickStart flow is a web based way to get started with Tina, it allows you to choose from one of our starters (Tina Barebones, Tina Documentation Starter, Tina Cloud Starter) and deploy directly to Vercel.

This approach allows you to see how Tina works in a production deployment almost immediately . This is great for getting to know what Tina can do, how Tina works,and show it to others such as your content team.

`npx create-tina-app`

create-tina-app allows you to work locally with one of our starters, this allows you to see how all the code behind the scenes is working before you decide that Tina is right for you.

To use the create-tina-app you will need Node 14+ .This doesn't require you to already have an application and will create a new project and directory and allow you to start developing locally.

Tina CLI

Tina CLI (npx @tincms/cli@latest init) allows you to add Tina to an existing Next.js application. When using the CLI we will take care of the important pieces including:

Adding all the Tina dependencies
Setting up a .tina folder with a basic schema
Creating a demo directory with an example Tina powered page
Creating an admin route
Ensuring Tina best practices are used

Using the Tina CLI allows you to add Tina and selectively integrate it into your existing Next.js application. This allows you to keep your established site and slowly bring the power of Tina to your editors and content team. Though once you use it, we are not sure how slowly you will want to move.

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.

Tina now Supports MDX

James Perkins — Tue, 26 Oct 2021 17:34:02 +0000

The team at Tina is dedicated to revolutionizing the CMS space. We were the first to offer contextual editing in real-time which enabled teams to be more productive. Now we are introducing the world’s first UI editor for MDX. This empowers content teams to add components to a page with a single click.

You can see our starter repository on our GitHub or select Documentation Starter when going through our quickstart flow.

Why MDX?

MDX provides the ability to write JSX into Markdown files, which gives developers the ability to create content that is dynamic, interactive, and customizable. The problem with MDX, by nature, is you need to have some technical understanding to be able to both use and create content using MDX. This is where we have empowered non-technical members of your team to leverage reusable components with a single click. This means that content teams can move quickly and developers can focus on other projects.

How to start using MDX?

We have made the developer experience a breeze, you can check out our documentation or check out the steps to start using MDX :

Update to the latest version Tina

You will need to update tinacms and @tinacms/cli to the latest versions to use the MDX features.

Create your components you want your content team to use.

Create a component as you normally would and use props for any part you would like to be editable, below is an example of a callout component:

...
export default function Callout({callout}) {
return(  
        <CalloutWrapper type={backgroundColor[callout.type]} >
          <CalloutLabel >{label[callout.type] || callout.type}</CalloutLabel>
          <CalloutText textColor={textColor[callout.type] || textColor.default}>{callout?.text}</CalloutText>
        </CalloutWrapper>
)}

Add the fields for your components to your schema.ts

...
{
          type: "rich-text",
          label: "Body",
          name: "body",
          templates: [
            {
              name: "Callout",
              label: "Callout",
              fields:[
                {
                  name: "type",
                  label: "Type",
                  type: "string",
                  options: ["default", "warning", "error"],
                },
                {
                  name: "text",
                  label: "Text",
                  type: "string",
                },
              ]
            },
        ],
          isBody: true,
},
...

Add the components to your Tina powered pages.

//imports
import { TinaMarkdown } from "tinacms/dist/rich-text";
import Callout from "../../blocks/callout-block";

const components = {
  Callout: (props) => {
    return <Callout callout={props} />;
  },
};

// Code removed for simplification
<TinaMarkdown components={components}>
          {props.data.getDocsDocument.data.body}
</TinaMarkdown>

Ready to get started?

You can see our starter repository on our GitHub or select Documentation Starter when going through our quickstart flow.

Tina Cloud is Now in Public Beta

James Perkins — Wed, 18 Aug 2021 15:19:35 +0000

We are pleased to announce that Tina Cloud is in beta, and all of the core functionality is in place for your team to have a great content editing experience on Next.js sites! If you are excited as we are you can get started by signing up. But first, I'd love for you to stick around and hear about the team's vision, lessons learned, and what we have added. If you are new to Tina, check this quick demo.

Tina Cloud public Beta is a big milestone! All the core functionality is in place for teams to edit content on their Next.js sites. We’re just scratching the surface of what’s possible when you add an amazing content editing experience to content stored in your Git repository. Our goal is to fasten 10 times the experience for both developers and content editors — Scott Gallant, Founder and CEO

Lessons Learned

We learned a lot during the alpha stage, which allowed us to drive the product forward.

It took users a lot longer than we expected to make their first commit using Tina. At the beginning on average, it was over 8 hours. This signaled to us that even our starter took too long to set up.
You had a lot of questions after using our starter, mostly surrounding content modeling, and our documentation didn't answer them.
Tina could be used in Production on large sites, and both developers and content writers loved it.
Creating a Discord allowed us to give and receive real-time feedback, which allowed us to add features, fix bugs, and get people unstuck quickly.

What's New?

We believe that our product combines a fantastic developer and content creator experience into a single product. The update from alpha to beta is so large that I wanted to write a short paragraph about each part. Below is a list of each update, feel free to click on it to take you to the long-form update:

Better Documentation
A new initialize command in the CLI
Improving and adding guides
Improving our Tina Starter
Media Manager
Caching improvements
Creating @tinacms/toolkit
Vercel Integration
Dashboard Overhaul
Changes to content modeling

Get a website running with Tina Cloud in no time! Quick Start Guide

Getting Started with Tina

We wanted to speed up getting Tina up and running, whether this was a newly bootstrapped Next.js application or your Production application. We introduced several things to improve this:

Better documentation
A tina init command
New and improved guides

Better Documentation

The documentation at Tina has been something that we wanted to improve as much as possible, we found people were unsure of Tina's concepts because we did not clearly explain them in the documentation. We spent time crafting documentation that gives a developer of any experience a better understanding of each part of Tina, how they work together and how to accomplish specific tasks.

We also moved and created new navigation menus to better convey the intent of a piece of documentation, for example, if you were looking for the Next.js APIs we have a section for that.

A New Initialize Command in the CLI

Tina init is my favorite addition to the Tina experience. A single command can bootstrap Tina on a Next.js application and do all the heavy lifting for you. The team spent quite a bit of time working on this, and refining it, to get it just right. The command npx @tinacms/cli init command currently does the following:

Install all dependencies to your application
Add the Tina commands to your package.json (tina-dev, tina-build, tina-start)
Wrap your app.js / app.tsx in our TinaEditProvider
Create demo data that you can test Tina out with.
Create an admin route to allow people to edit, and a way to exit.
Create a schema file ready for you to shape your content

This allows you to move quickly and experience Tina without having to write any code. Then when you are ready you can easily extend it to use parts of your existing site.

Improving and Adding Guides

When we introduced Tina, we had a single guide that got you up and running with our Tina Cloud Starter. This was a great way for users to experience Tina but we found that people were missing some key concepts of Tina.

I went back to the drawing board and created a new guide that takes the Next.js Starter Blog and adds Tina and Tina Cloud to it while explaining each concept as we went. This feels like a perfect way to show off Tina, learn how to use Tina, with something that many users are familiar with.

We also removed old guides that no longer promote Tina's best practices and moved some of our other guides into our experimental section. Experimental to us means that we can't guarantee that there won't be bugs or issues with the packages used.

Improving our Tina Starter

The Tina Starter was built originally to show "the power of Tina" while it did that, we didn't feel that it showed a real-world example. So we went back to the drawing board and created our new Tina Starter, which includes a landing page, blog, and about pages. You can edit and rearrange the content and we styled it with TailwindCSS to give it some extra shine! Below is an example of just some of the work you can do:

Media Manager

Media manager was one of the most important features that we needed for Tina Cloud. Our Cloudinary Media manager allows you to change images, upload new images, and delete ones you no longer need without ever leaving the Tina editing experience.

I wrote a blog post announcing it and how to implement it into your application.

Caching Improvements

Speed and performance have been something we have been actively working on. We introduced some improvements behind the scenes to improve the way we retrieve the data for your site. Tina is carefully built with performance in mind and is now faster!

Creating `@tinacms/toolkit`

TinaCMS was built with small modular packages, this meant that we relied heavily on React context. The dependency mismatches from over-modularizing our toolkit, led to many bugs related to missing context.

Our open-source team created @tinacms/toolkit which incorporates the essentials of Tina all in one place. This simplifies everything for you as a user and Tina as a product.

You can read about all the updates and why decided to make the changes in our pinned GitHub issue.

Vercel Integration

We wanted to reduce the friction to almost zero when testing TinaCMS, so we worked on adding Vercel integration. This means if you sign up for an account, you can one-click and deploy in minutes and start playing around with TinaCMS and Tina Cloud, using our Starter. In the future we will be adding the ability to deploy any application in Tina Cloud to Vercel!

Dashboard Overhaul

When using Tina Cloud in alpha our dashboard UX wasn't a first-class experience and at times could be confusing. We completely overhauled the dashboard, making it easier and quicker to add an application to the Cloud, invite users, and find important information such as site URL(s) or Client ID.

If you did use the alpha you will need to sign up again as we made large changes to the way we handle user signup in our backend.

Changes to Content Modeling

Content Modeling is the core of how you interact with TinaCMS and also retrieve your content. We decided to make an important change and be more primitive based in nature.

This allows for simplistic queries that don't require disambiguation, we believe this will allow you as a developer to craft queries with ease.

If you used the alpha of Tina you might want to read this article the team put together to explain all of the changes and how to migrate.

Give Us Feedback!

The whole team is truly excited to enter the beta phase and hope you will check it out and give us honest feedback. We want to hear about your projects or, let us know how Tina Cloud can help your team make progress.

To keep up to date with Tina goings-on make sure to follow @tina_cms and @james_r_perkins on Twitter. Want to chat with the team? Join the Discord

Stay tuned for further improvements, features, community-built projects and more!

Tina Cloud is in public alpha

James Perkins — Wed, 02 Jun 2021 16:03:55 +0000

The team at Tina is pleased to announce that Tina Cloud is officially in public Alpha.

Everyone is encouraged to register a free account on our headless GitHub-backed CMS and start committing. We have been working incredibly hard behind the scenes to get our vision in the hands of developers and content teams.

Tina Cloud brings the power of Tina's open-source content editor with a GraphQL API that allows you to interact with your Markdown files stored in your repository. Also, with Tina Cloud, you can allow any team member to edit content — even if they don’t have a GitHub account.

When we launched TinaCMS, it was mainly an open-source Javascript UI for editing your site, visually.

At that time, TinaCMS was a 3-month-old, open-source project and we relied on developers to roll their own solution for user management, authentication, roles, content storage, and more. But we quickly learned that developers need more out-of-the-box to get their teams successful. With Tina Cloud, we're staying true to our vision of Git-backed content management, but with a batteries-included experience.

What to Expect with the Tina Cloud Alpha?

Tina cloud is still being actively developed, and is in a place we believe you can have a great experience with it. You may run into issues we didn't encounter yet or be required to update to the latest version because we have improved our API.

Tina cloud isn't complete yet, some key features are currently being shaped up:

Media Management Solution
Multi-branch workflows
Read-only tokens for our GraphQL API. That means it's only used when you are editing content.

What tech stack should be used with Tina Cloud

Next.js: Next.js is a perfect match for Tina and is the default choice for our team.
GitHub: GitHub is required as it is the only Git provider we support on Tina Cloud currently. Let us know if you want us to support other Git providers.
Static, file-based builds: When you go to build our Tina Cloud product collects your filesystem content, in the future, you will be able to fetch data from our Cloud API during build times.

How can I get started?

The first thing to do is to signup for Tina Cloud, once you're in, we have a few ways for you to get started and get up and running in minutes.

Tina Cloud Starter: A basic implementation of Tina Cloud aimed at getting your up and running in a few minutes.
Tina Cloud Next.js blog starter - A guide to add Tina Cloud on top of the default Next.js blog starter and work directly through our CMS.

You can also check out the video to get started with Tina Cloud in under 10 minutes, it gives you an overview of our Tina Cloud starter and gives you some tips on how to run Tina Cloud locally.

Where can I give feedback or get help?

We have a few channels open for you to reach out, provide feedback or get help with any challenges you may have.

Dig into the new Tina Cloud documentation that covers implementations.
Join our Discord.
Email us if would like to schedule a call with our team and share more about your context.
Get support through your Tina Cloud dashboard (there's a chat widget at the bottom of the screen on the left side).

What about pricing?

We are still deciding out what we believe will be fair pricing for people who decided to use Tina Cloud. During the Alpha, Tina Cloud is at no cost for small teams and we will contact you if we believe your use case may eventually fit within our post-beta paid plans.

Please reach out

The whole team is truly excited to enter a public Alpha phase and hope you will check it out and give us honest feedback. We wanna hear about your projects, let us know how Tina Cloud can help your team make progress.

To keep up to date with Tina goings-on make sure to follow @tina_cms and @james_r_perkins on Twitter.

Stay tuned for further improvements, features, community-built projects and more!

Supercharging file-based content with GraphQL

Jeff See — Thu, 29 Apr 2021 15:58:10 +0000

Today we want to introduce you to the Tina GraphQL gateway that brings reliability to Git-based content management. It's an essential piece to provide a robust structured content, while your content remains fully portable.

Overcoming the limitations of the filesystem

Using the filesystem for website content has been a mainstay of the web development ecosystem for years. The ability to ship your entire website in one fell swoop and roll anything back with thanks to Git has made this a popular and efficient way to get things done with confidence.

On the other hand, the open nature of using files for content can lead to headaches. Content Management Systems (CMS) have always provided confidence in another way — knowing that your content's shape won't change out from underneath you. The scary (and powerful) thing about using the filesystem is that there's no layer to ensure that you're getting the content that you expect. It's a trade-off that has many valid use-cases, but just as many foot guns.

Let's take an example

We're going to use the Next.js blog starter to demonstrate some of the problems with file-based content and how we hope to solve them. If you'd like to follow along you can fork this repository and start with the branch called start. To skip ahead to the final solution check out the add-tina-gql branch.

Our content structure

This app sources its content from Markdown files in a folder called _posts:

- _posts
  - dynamic-routing.md
  - hello-world.md
  - preview.md
- pages
  - index.js # lists the blog posts
  - posts
    - [slug].js # dynamically shows the appropriate blog post

On the home page we get each post from the _posts directory and sort them by date before showing them with our getAllPosts function:

export function getAllPosts(fields = []) {
  const slugs = getPostSlugs()
  const posts = slugs
    .map(slug => getPostBySlug(slug, fields))
    // sort posts by date in descending order
    .sort((post1, post2) => (post1.date > post2.date ? -1 : 1))
  return posts
}

And the result:

Demo: ➡️ Start following along

File-based content is simple

What we have so far is great, since our changes are stored in Git we know that if we made a mistake we will be able to easily roll it back to a previous version. But as the complexity of our content increases things become less straightforward.

To demonstrate that, let's first look at how our content is structured. The "Dynamic Routing and Static Generation" blog post looks like this:

---
title: 'Dynamic Routing and Static Generation'
excerpt: 'Lorem  ...'
coverImage: '/assets/blog/dynamic-routing/cover.jpg'
date: '2020-03-16T05:35:07.322Z'
author:
  name: JJ Kasper
  picture: '/assets/blog/authors/jj.jpeg'
ogImage:
  url: '/assets/blog/dynamic-routing/cover.jpg'
---

Lorem ipsum dolor sit amet ...

Let's expand on this structure by adding the ability to filter which blog posts show up on the home page. To do that we add a new boolean value to each post called featured.

---
title: 'Dynamic Routing and Static Generation'
excerpt: 'Lorem  ...'
coverImage: '/assets/blog/dynamic-routing/cover.jpg'
date: '2020-03-16T05:35:07.322Z'
author:
  name: JJ Kasper
  picture: '/assets/blog/authors/jj.jpeg'
ogImage:
  url: '/assets/blog/dynamic-routing/cover.jpg'
featured: true
---

Lorem ipsum dolor sit amet ...

Now we can update our getAllPosts function accordingly:

export function getAllPosts(fields = []) {
  const slugs = getPostSlugs();
  const posts = slugs
    .map((slug) => getPostBySlug(slug, fields))
    // sort posts by date in descending order
   .sort((post1, post2) => (post1.date > post2.date ? -1 : 1))
+  .filter((post) => post.featured);
  return posts
}

Let's add a new post to test this out, this one won't be featured:

---
title: 'Why Tina is Great'
excerpt: 'Lorem  ...'
coverImage: '/assets/blog/dynamic-routing/cover.jpg'
date: '2021-04-25T05:35:07.322Z'
author:
  name: JJ Kasper
  picture: '/assets/blog/authors/jj.jpeg'
ogImage:
  url: '/assets/blog/dynamic-routing/cover.jpg'
featured: 'false'
---

Lorem ipsum dolor sit amet ...

Woops, look who's showing up on our home page:

Can you spot the issue? We accidentally set featured to "false" instead of false! We made it a string, not a boolean.

Demo: 👀 Spot our mistakes.

If we had been using a CMS this probably wouldn't have happened. Most of them require that the shape of your content is well-defined. While these kinds of issues are painful, there's a lot more that CMSs do for us that we don't get from the filesystem — you may have noticed something else about the shape of our content that doesn't feel quite right…

Relationships: it's complicated

Let's look at the data from our new blog post again:

---
title: "Why Tina is Great"
excerpt: "Lorem  ..."
coverImage: "/assets/blog/dynamic-routing/cover.jpg"
date: "2021-04-25T05:35:07.322Z"
author:
  name: JJ Kasper
  picture: "/assets/blog/authors/jj.jpeg"
ogImage:
  url: "/assets/blog/dynamic-routing/cover.jpg"
featured: "false"
---

Lorem ipsum dolor sit amet…

The author content is the same over in the "Dynamic Routing and Static Generation" post. If JJ wanted to change his picture he will need to update it on every post he's written. Sounds like something a CMS would solve with a content relationship, JJ should ideally be an author who has many posts. To solve this with our file-based content we could split the author data into its own file and place a reference to that author's filename in the post structure:

author: _authors/jj.md

But now we have to update our data-fetching logic so that whenever it comes across the author field in a post it knows to make an additional request for that data. This is pretty cumbersome, and again — as complexity grows this type of logic quickly becomes untenable. With a CMS SDK or GraphQL API we'd be able to do this sort of thing easily, and we'd have confidence that a document can't be deleted if it's being referenced from another document.

Demo: Check out the diff to see how we're awkwardly making use of a separate author file.

Content Management Systems: Reliable? Yes. Portable? No.

Headless CMSs are a great way to maintain full control over your frontend code while offloading issues like those mentioned above to a more robust content layer. But when you hand your content over to a CMS you lose the power of Git that comes built-in with file-based content.

With a CMS, when you make a change to the shape of your content you also need to coordinate that new shape with your code, and you need to make sure that all of your existing content has been updated accordingly.

Most CMSs have come up with various ways to help with this: separate sandbox environments, preview APIs, and migration SDK scripts — all of which carry their own set of headaches. None of this is necessary with file-based content, everything moves and changes together. So what if we could bring the robust features of a headless CMS to your local filesystem? What might that look like?

Meet Tina Content API

Today we're introducing a tool that marries the power of a headless CMS with the convenience and portability of file-based content. The Tina Content API is a GraphQL service that sources content from your local filesystem. It will soon be available via Tina Cloud, which connects to your GitHub repository to offer an identical, cloud-based, headless API.

Tina Cloud is currently open to a limited set of Next.js projects, sign up for early access to get into the private beta.

To get a sense for how this works, let's make some tweaks to the blog demo.

First let's install Tina CLI:

yarn add tina-graphql-gateway-cli

Now let's add a schema so the API knows exactly what kind of shape to build for your content:

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

// `.tina/schema.ts`
import { defineSchema } from 'tina-graphql-gateway-cli'

export default defineSchema({
  collections: [
    {
      label: 'Posts',
      name: 'posts',
      /*
       * Indicates where to save this kind of content (eg. the "_posts" folder)
       */
      path: '_posts',
      templates: [
        {
          label: 'Simple',
          name: 'simple_post',
          fields: [
            {
              type: 'text',
              label: 'Title',
              name: 'title',
            },
            {
              type: 'text',
              label: 'Excerpt',
              name: 'excerpt',
            },
            {
              type: 'text',
              label: 'Cover Image',
              name: 'coverImage',
            },
            {
              type: 'text',
              label: 'Date',
              name: 'date',
            },
            {
              // We indicate the author is a "reference"
              // to another document
              type: 'reference',
              name: 'author',
              label: 'Author',
              collection: 'author',
            },
            {
              type: 'group',
              name: 'ogImage',
              label: 'Open Graph Image',
              fields: [
                {
                  type: 'text',
                  label: 'URL',
                  name: 'url',
                },
              ],
            },
            {
              type: 'toggle',
              label: 'Featured',
              name: 'featured',
            },
          ],
        },
      ],
    },
    {
      name: 'authors',
      label: 'Authors',
      path: '_authors',
      templates: [
        {
          label: 'Author',
          name: 'author',
          fields: [
            {
              type: 'text',
              label: 'Name',
              name: 'name',
            },

            {
              name: 'picture',
              label: 'Picture',
              type: 'text',
            },
          ],
        },
      ],
    },
  ],
})

Notice that we're referencing the authors section from the post.author field

Next we replace the dev command to start the GraphQL server in tandem with our Next.js app:

  "scripts": {
    "dev": "yarn tina-gql server:start -c \"next dev\"",
    ...
  },

Demo: Here's the changes we've made so far. Check out the add-tina-graphql branch to pick up from this point.

Run the dev command, you can see that we now have a local GraphQL server listening on port 4001 along with some information about auto-generated configuration files:

Started Filesystem GraphQL server on port: 4001
Generating Tina config
Tina config ======> /.tina/__generated__/config
Typescript types => /.tina/__generated__/types.ts
GraphQL types ====> /.tina/__generated__/schema.gql
ready - started server on 0.0.0.0:3000, url: http://localhost:3000

Let's test it out:

💡Tip: if you have a GraphQL client like Altair you can explore the API by pointing it to http://localhost:4001/graphql

# Point your request to http://localhost:4001/graphql
{
  getPostsList {
    data {
      ... on SimplePost_Doc_Data {
        title
      }
    }
  }
}

And here is the result:

{
  "errors": [
    {
      "message": "Unexpected value of type string for boolean value",
      "path": ["getPostsList"]
    }
  ],
  ...
}

This error is coming from our old friend featured: "false". This is exactly the kind of assurance you'd get from a CMS, but without any of the overhead. After fixing the issue, we get what we expected:

{
  "data": {
    "getPostsList": [
      {
        "data": {
          "title": "Dynamic Routing and Static Generation"
        }
      },
      ... # truncated
    ]
  }
}

We can use GraphQL to replace all of our bespoke filesystem data-fetching logic and rest assured that the data we get back will be exactly what we expect it to be.

query BlogPostQuery($relativePath: String!) {
  getPostsDocument(relativePath: $relativePath) {
    data {
      ... on SimplePost_Doc_Data {
        title
        excerpt
        date
        coverImage
        author {
          data {
            ... on Author_Doc_Data {
              name
              picture
            }
          }
        }
        ogImage {
          url
        }
        featured
        _body
      }
    }
  }
}

Demo: View the changes we made to add Tina GraphQL

To be continued

Being able to work locally with GraphQL is a first step to help us bring the capabilities of a full-fledged CMS to the filesystem. Tina Cloud will offer the same great experience through a hosted headless API. In the coming weeks we'll continue sharing more about how this API works with TinaCMS to bring visual content management to your website with minimal overhead.

Take a look at the demo we just went through, see if you can expand on it and share your progress with us!

2021 Q1 TinaCMS Roundup

Frank Taillandier — Thu, 15 Apr 2021 12:13:13 +0000

We are regularly improving Tina to provide an effective developer experience and a unique visual content editing experience. Latest additions are the result of listening to the feedback of the community as well as scratching our own itch.

Let’s take a closer look at some of the most impactful recent changes in Tina core library.

Radio Group Field 🆕

Editors are now able to pick from a list of options, the radio group field comes in two flavors: radio and button, they are displayed horizontally by default, you can opt-in for the vertical variant.

Search and filter blocks 🆕

When your page template offers more than 10 components to pick from, editors can type and filter from the blocks menu list.

Duplicate blocks 🆕

A small, yet big, win for inline editing, you can now duplicate a block with a single click.

Rethinking Inline Editing 🤔

We started reevaluating our approach to how Tina does inline editing. We refactored the code to take advantage of events and references to provide a new API. This work is far from done and is currently only available through a feature flag, as this will be subject to more changes.

We’ll share our views in an upcoming post on what the future of inline editing will look like in Tina from a developer perspective.

Related to this change, we decided to remove drag-and-drop of inline blocks for now. There were some cases where it was creating issues but we might revisit this feature later when we have better inline editing. Now, you can move blocks around a page with up and down block controls, which shouldn't require too many clicks in most cases.

You'll soon be able to resize the sidebar as you see fit.
This makes the writing experience much more enjoyable when you write long format in the WYSIWYG editor. ↔️

Next.js and Tailwind Demo 👀

Our default demo is based on Next.js and Tailwind CSS. It currently showcases how you can set up Tina to provide: theme colors, component variants, dark mode, responsive blocks, etc. In the near future, we’ll dedicate a post on how we built this demo, so you will be able to dig in further and learn from it. For now, feel free to play around and let us know if you have any feedback.

Contentful plugin 🔌

Our homepage makes it very clear that Tina can potentially work with any backend, we already released a guide to work with Strapi. We did also experiment with Contentful and published a plugin for Tina to work with content fetched from their Content API. If you’re working with Contentful, feel free to test the plugin and leave us feedback.

Community 💜

New Core Team Members

Jeff, Chris, and Jack joined the core team. We’re very happy to welcome them to help us unleash the potential Tina has to offer.

Some stats 📈

Our community activities are now tracked in Orbit 💜, in order to help us better build better relationships with you. Warm thanks to Nicolas from the Orbit team for helping out setting things up.

Orbit makes it easy to reflect on the community’s activity, you can easily see when you got on the front page of Hacker News 😊.

Shout out to our most active community members for 2021 Q1: Joe Innes, Matthew Francis Brunetti, Austin Condiff, Hirvin Faria and Chadd Poggenpoel. 👏👏👏👏👏

Our open source project has reached some new milestones:

Tina has been starred by more than 6K people on GitHub 🌟
tinacms core package has been downloaded more than 250K times 📦

🙏 Thanks for your interest, we’re just getting started!

One more thing... ⏳

In order to enhance the Tina ecosystem, our team is currently working on a new open source tool to ease the way you can do structured content management while keeping control of your content in your Git repository.

Subscribe to our blog feed or newsletter to be the first to know about all our new and exciting developments.

DEV Community: Tina

Markdown Bot - An AI friend who improves your content

A Useful Aid, Not a Replacement

Markdown Bot Works On Your PRs

Working with the GitHub Bot

Looking Ahead: AI and Git-based Content

A/B testing with Next.js Middleware and TinaCMS

Introduction

Creating our Tina application

Planning our tests

Setting up our A/B tests

Delivering dynamic pages with NextJS middleware

Using Tina to create A/B Tests

How to keep up to date with Tina?

Tina Community Discord

Tina Twitter

Automating Pull Requests

PR Scheduler

How to install

How to schedule a pull request

Github Actions

Creating your GitHub Action

How to run the action

How to keep up to date with Tina?

Tina Community Discord

Tina Twitter

Read-only tokens - Query Requests anytime

Some use cases for Read-only tokens

How to use Read-only tokens?

Create a token from the dashboard

Ready for requests

SSR - Server Side Rendering content

CSR - Client Side Rendering

SSG with Fallback

How to keep up to date with Tina?

Tina Community Discord

Tina Twitter

Tina Data Layer: Performant Editing

How to enable the Data Layer on your project

What does the Data Layer do to increase Performance?

When we might do a full re-index

Some things to note

The future

More complex and advanced queries

Referential Integrity

From CMS To Contextual Editing

Getting our project started

What does the Tina code do?

.tina folder

schema.ts

components

_generated__

Adding Contextual Editing.

Creating the getStaticPaths query

Creating getStaticProps query

Creating the query

Adding useTina hook

Adding imports

Changing our props and adding UseTina

Update our elements to use Tina data

The final piece of Contextual Editing.

Next steps

How to keep up to date with Tina?

Tina Community Discord

Tina Twitter

New Year, New CMS?

Why Tina?

Git Backed

Contextual Editing

Native MDX Support

Three ways to get started in under five minutes

Tina Quickstart

npx create-tina-app

Tina CLI

Where can you keep up to date with Tina?

Tina Community Discord

Tina Twitter

Tina now Supports MDX

Why MDX?

How to start using MDX?

`.tina` folder

`schema.ts`

`components`

`_generated__`

Adding `useTina` hook

`npx create-tina-app`

Creating `@tinacms/toolkit`