Flotiq & Astro

本頁內容尚未翻譯。

Flotiq is a headless CMS designed for various frontends, such as static sites, mobile, and web applications. Developers and content creators manage and deliver content through REST and GraphQL-based APIs.

Integrating with Astro

This guide will use the Flotiq headless CMS API with an Astro project to display content on your website.

Prerequisites

To get started, you will need:

An Astro project - You can create a new project using the npm create astro@latest command.
A Flotiq account - If you don’t have an account, sign up for free.
Flotiq read-only API key - Find out how to obtain your key.

Setting up the Environment variables

Add the read-only API key from your Flotiq account to the .env file in the root of your Astro project:

FLOTIQ_API_KEY=__YOUR_FLOTIQ_API_KEY__

Defining a Content Type in Flotiq

First, you need to define an example Content Type Definition in Flotiq to store data.

Log in to your Flotiq account and create a custom Content Type Definition with the following example Blog Post configuration:

Label: Blog Post
API Name: blogpost
Fields:
- Title: text, required
- Slug: text, required
- Content: rich text, required

Then, create one or more example Content Objects using this Blog Post type.

Installing the Flotiq TypeScript SDK

To connect your project with Flotiq, install the Flotiq SDK using the package manager of your choice:

npm install flotiq-api-ts

pnpm add flotiq-api-ts

yarn add flotiq-api-ts

Next, configure the SDK using your credentials. Create a new file named flotiq.ts inside the src/lib directory of your project:

import { FlotiqApi } from "flotiq-api-ts";

export const flotiq = new FlotiqApi(import.meta.env.FLOTIQ_API_KEY);

This configuration can now be used throughout your project.

Fetching and Displaying Data from Flotiq

Fetch the Blog Post data on an Astro page using your content’s custom API BlogpostAPI:
src/pages/index.astro
```
---
import { flotiq } from "../lib/flotiq";

const posts = await flotiq.BlogpostAPI.list();
---
```

Display the content in your Astro template. You will have access to the title, slug, and content of your posts as well as other internal post data:

---
import { flotiq } from "../lib/flotiq";

const posts = await flotiq.BlogpostAPI.list();
---
<html lang="en">
  <head>
    <title>Astro</title>
  </head>
  <body>
    {posts.data?.map((post) => (
      <section>
        <a href={`/posts/${post.slug}`}>
          <h2>{post.title}</h2>
        </a>
        <div>{post.internal?.createdAt}</div>
        <div set:html={post.content}/>
      </section>
    ))}
  </body>
</html>

Start the dev server and visit your page preview at http://localhost:4321 to see the list of your blog posts. Each post will link to a page that does not yet exist. These will be created in the next step.

Generating Individual Pages

Astro supports both prerendering all your pages ahead of time, or creating routes on demand when they are requested. Follow the instructions for either static site generation or on-demand rendering to build the page routes for your blog posts.

Static Site Generation

In static site generation (SSG) mode, use the getStaticPaths() method to fetch all possible blog post paths from Flotiq.

Create a new file [slug].astro in the /src/pages/posts/ directory. Fetch all blog posts and return them within the getStaticPaths() method:

---
import type { Blogpost } from "flotiq-api-ts";
import { flotiq } from "../../lib/flotiq";

export async function getStaticPaths() {
  const posts = await flotiq.BlogpostAPI.list();
  return posts.data?.map((post) => ({
    params: { slug: post.slug },
    props: post
  })) || []
}
---

Add the templating to display an individual post:

---
import type { Blogpost } from "flotiq-api-ts";
import { flotiq } from "../../lib/flotiq";

export async function getStaticPaths() {
  const posts = await flotiq.BlogpostAPI.list();
  return posts.data?.map((post) => ({
    params: { slug: post.slug },
    props: post
  })) || []
}
const post: Blogpost = Astro.props;
---
<html lang="en">
  <title>{post.title}</title>
  <body>
    <h1>{post.title}</h1>
    <div set:html={post.content}/>
  </body>
</html>

Visit http://localhost:4321 and click on a linked blog post in your list. You will now be able to navigate to the individual post’s page.

On-demand Rendering

If you are using SSR mode, you will need to fetch a single post based on its slug.

Create a new file [slug].astro in the /src/pages/posts/ directory. Fetch the post by its slug field, including logic to display a 404 page when the route is not found:

---
import type { Blogpost } from "flotiq-api-ts";
import { flotiq } from "../../lib/flotiq";

const { slug } = Astro.params;
let post: Blogpost;

const blogpostList = await flotiq.BlogpostAPI.list({
  filters: JSON.stringify({
    slug: {
      type: 'equals',
      filter: slug,
    }
  }),
  limit: 1
});

if (blogpostList.data?.[0]) {
  post = blogpostList.data[0]
} else {
  return Astro.redirect('/404');
}
---

Add the templating to display an individual post:

---
import type { Blogpost } from "flotiq-api-ts";
import { flotiq } from "../../lib/flotiq";

const { slug } = Astro.params;
let post: Blogpost;

const blogpostList = await flotiq.BlogpostAPI.list({
  filters: JSON.stringify({
    slug: {
      type: 'equals',
      filter: slug,
    }
  }),
  limit: 1
});

if (blogpostList.data?.[0]) {
  post = blogpostList.data[0]
} else {
  return Astro.redirect('/404');
}
---
<html lang="en">
  <title>{post.title}</title>
  <body>
    <h1>{post.title}</h1>
    <div set:html={post.content}/>
  </body>
</html>

Visit http://localhost:4321 and click on a linked blog post in your list. You will now be able to navigate to the individual post’s page.

Refreshing the SDK After Content Type Changes

When using the Flotiq TypeScript SDK (flotiq-api-ts), all your data types are accurately mapped into the Astro project.

If you make changes to the structure of your content types (such as adding a new field or modifying an existing one), you’ll need to refresh the SDK to ensure that your project reflects the latest model updates.

To do this, run the rebuild command for your package manager:

npm rebuild flotiq-api-ts

pnpm rebuild flotiq-api-ts

yarn rebuild flotiq-api-ts
// for yarn v1 (Classic):
// yarn add flotiq-api-ts

This will update the SDK, aligning object types, fields, and API methods with your current data model.

Publishing Your Site

To deploy your website, visit Astro’s deployment guides and follow the instructions for your preferred hosting provider.

Redeploy on Flotiq Changes

To update your published site, configure Flotiq to send a webhook your hosting provider to trigger a rebuild whenever your content changes.

In Flotiq, you can define which Content Type and events it should trigger on, and configure it accordingly. See the Flotiq Webhooks documentation for more details.