Astro x caisy

The final code of this demo is available at

• Github: https://github.com/caisy-io/caisy-example-astro

• Stackblitz: https://stackblitz.com/github/caisy-io/caisy-example-astro

In this example, we build on the blog article created in the Quick Start. If you haven't completed it yet, it is recommended to go through the first four steps of the Quick Start once more.

To proceed, the following query should retrieve the article data using the slug of the previously created article when running in your playground and setting the right slug in the variables.

query allBlogArticle($slug: String) {
  allBlogArticle(where: { slug: { eq: $slug } }) {
    edges {
      node {
        text {
          json
        }
        title
        slug
        id
      }
    }
  }
}

In this example, you will need your project ID and a valid API key.

To create a new SvelteKit project, run the following command:

npm create astro@latest caisy-example-astro

After the command, you will be asked a couple of questions which you should answer the following, depending on your preferences:

• Where would you like to create your new project? caisy-example-astro

• How would you like to set up your new project? an empty project

• Would you like to install npm dependencies? (recommended) yes

• Would you like to initialize a new git repository? (optional) yes

• How would you like to set up TypeScript? Strict
  

To start the development server run:

npm run dev

For this example, we use Astro in server mode. You can deploy Astro with server mode to platforms like Vercel or Netlify. If you want to create a static HTML build with Astro, you can use caisy as the data source. For static mode, you need to implement the getStaticPaths. The logic will be similar, but we continue here with their server mode for simplicity. So you need to update your Astro config file with the following:

import { defineConfig } from 'astro/config';

// https://astro.build/config
export default defineConfig({
    output: 'server'
});

To begin, you should only see a headline called "Astro" on the index page. We will add a link to our newly created blog on the landing page using the <a> tag.

<a href="/blog/my-first-article">a link to our first blog page</a>

If the development server is running, you should see a link on your index page. However, clicking the link will result in a 404 page. Let's fix this by creating a dynamic routed page that handles all of our blog pages.
To do this, create a file called [...slug].astro in the path src/routes/blog. In this file, you can add a simple "Hello World" placeholder like this:

<h1>Hello world</h1>

If you visit your site with the link on the index page, you will see your hardcoded "Hello World" headline. Let's make that text dynamic by fetching it from caisy in the next step.

You can install GraphQL-request by running the following command in your terminal or command prompt:

npm install graphql-request graphql --save

For proper interaction with the external API, the environment variables CAISY_API_KEY and CAISY_PROJECT_ID must be defined in a .env file.
If you need information on where to find this in your project, see:

The .env file may look like this:

CAISY_PROJECT_ID=54026eaa-a8fc-49f9-ac37-ebe5148c4926
CAISY_API_KEY=Q1Bi5yudIr4HxQEtVt2fmalZRyndjuDW

The query used is from the Quickstart example and can be tested in the Playground.

After using the GraphQL query from the playground in the page with GraphQL request you code might look like this:

---
import { gql, GraphQLClient } from 'graphql-request';

const params = Astro.params;

const client = new GraphQLClient(
	`https://cloud.caisy.io/api/e/v4/${import.meta.env.CAISY_PROJECT_ID}/graphql`,
	{
		headers: {
			'x-caisy-apikey': import.meta.env.CAISY_API_KEY
		}
	}
);

const gqlResponse = await client.request(
	gql`
		query allBlogArticle($slug: String) {
			allBlogArticle(where: { slug: { eq: $slug } }) {
				edges {
					node {
						text {
							json
						}
						title
						slug
						id
					}
				}
			}
		}
	`,
	{ slug: params.slug }
);

const post = gqlResponse?.allBlogArticle?.edges?.[0]?.node;
---
<h1>{post.title}</h1>

This code uses GraphQL to retrieve information about a specific blog article from an external API. It utilizes an API key and project ID for access and locates the article using a specific "slug."
It returns the title and text of the located article.

To render the rich text, we use the library @caisy/rich-text-astro-renderer, which can be installed with a package manager like this:

npm install @caisy/rich-text-astro-renderer --save

After installing, we use the json from our text field to pass it as node to the RichTextRenderer It can be used in the page's template file like this:

---
import RichTextRenderer from '@caisy/rich-text-astro-renderer';
import { gql, GraphQLClient } from 'graphql-request';

const params = Astro.params;

const client = new GraphQLClient(
	`https://cloud.caisy.io/api/e/v4/${import.meta.env.CAISY_PROJECT_ID}/graphql`,
	{
		headers: {
			'x-caisy-apikey': import.meta.env.CAISY_API_KEY
		}
	}
);
const gqlResponse = await client.request(
	gql`
		query allBlogArticle($slug: String) {
			allBlogArticle(where: { slug: { eq: $slug } }) {
				edges {
					node {
						text {
							json
						}
						title
						slug
						id
					}
				}
			}
		}
	`,
	{ slug: params.slug }
);

const post = gqlResponse?.allBlogArticle?.edges?.[0]?.node;
---
<h1>{post.title}</h1>
<RichTextRenderer node={post.text.json} />

If you navigate to the page, you should now see the headline and full rich text of the blog article displayed on the page.

With this, you have all you need to build a blog page with caisy and astro. For more complex queries and topics such as preview and localization, further reading may be necessary.