DEV Community: Stefan Kudla

Add a headless CMS to Astro in 3 easy steps

Stefan Kudla — Tue, 20 Sep 2022 14:48:52 +0000

Astro is a lightweight web framework capable of shipping highly performant websites with minimal (or non-existent) JavaScript bundles. In this guide, we’re going to create our content with Cosmic and retrieve it in our Astro project, allowing for quick and easy content creation and collaboration. The end result will be a clean and composable website that aces the lighthouse scores all across the board.

TL;DR

Install the Simple Astro Blog Cosmic template.

Download the Simple Astro Blog source code.

Step 1: Configure your Astro project

To create a new Astro project, run npm create astro@latest. Astro provides a convenient CLI tool to set up some boilerplate code and get your project configured quickly. You can choose from a few different templates, but in our case, we’re keeping it simple with the “Just the Basics” option configuring a nice organized directory, a few Astro components to reference, and an Astro config file.

If you are using Cosmic in this guide, make sure you install the Cosmic NPM package:

# npm
npm install cosmicjs
# pnpm
pnpm add cosmicjs
# yarn
yarn add cosmicjs

Next, we will create two items in our project directory. First, create a lib folder in the src folder, and then create a cosmic.js file. After you’ve created this file, create a .env in the root of your directory. Here, we will store our environment variables from the Cosmic Bucket we’re about to set up, and in our cosmic.js file we will import the environment variables and create our API calls to retrieve our data.

Once you’ve created these two items, put them aside for now, as we go on to creating our Content Model in Cosmic.

Step 1.5 (Optional): Adding Astro Integrations

Astro provides some useful integrations, allowing you to quickly configure your favorite UI libraries, SSR adapters, and other tools like Astro Image and Tailwind CSS. For this guide, we encourage using both the Astro Image and Tailwind CSS integrations as they will improve website performance and developer experience.

Using the Astro CLI, we can run the commands npx astro add image and npx astro add tailwind, and Astro will install each individual package and update the astro.config.mjs file to support the integration.

Step 2: Configure a Cosmic Bucket

What is a headless CMS?

With a headless CMS, content is created using a dashboard and then delivered using an API. The content layer is separated from the presentation layer, making content flexible, reusable, and scalable. If you’d like to learn more about what a headless CMS is, we created this concise article explaining it.

Create an account

If you haven’t already, create a Cosmic account. Then navigate to the dashboard to create a new project. We’re going to start from scratch here, but you choose from a wide variety of templates by selecting “Start with a template” and clicking “Select Template” on the desired template. Name your project and Bucket Environment, then click “Save Bucket.”

Creating an Object

Let’s create a simple Object, click “Add Object Type” and then you will see that we can now setup our first Object. We’re going to call this Object “Posts”, which will contain multiple blog posts, so go ahead and select “Multiple” then under “Singular Name” type in “Post.”

Our default fields will contain the Slug field and the Content field, so you can leave these as they are.

Content Model

The Content Model is where we design the structure of our content. We can use different Metafields like strings, numbers, and even media (images). From this structure, we can craft our API calls to retrieve this specific data and render it onto our application.

Our Object will consist of:

An Excerpt (text)
A Cover Image (media)

Once you’ve created these Metafields, click “Save Object Type.”

Let’s create our first Post! Navigate to “Posts” in the sidebar and click “Add Post.” Fill in the Title, Excerpt, and Content with some sample text. Then, upload an image for the Cover Image and select “Publish.”

Now that we’ve got our first published Object, we’re ready to tie it all together and get this data into our Astro application.

Step 3: Retrieve data from the Cosmic API

Before we leave the Cosmic dashboard, we need to grab a couple of things. On the sidebar, click on Settings>API Acess. To make this easier, I’m going to rename the Bucket Slug to something like my-astro-blog then click “Save Settings”.

Now we’re going to take the Bucket Slug and Read Key values and place them into our .env file in our Astro app.

# .env
PUBLIC_COSMIC_BUCKET_SLUG=my-astro-blog
PUBLIC_COSMIC_READ_KEY=<your_read_key_here>

Once set, let’s go into the cosmic.js file we created in Step 1. We will import the Cosmic module, instantiate an api variable and import our environment variables. Refer to these docs for setting environment variables in Astro.

// src/lib/cosmic.js
import Cosmic from "cosmicjs";
const api = Cosmic();

const bucket = api.bucket({
  slug: import.meta.env.PUBLIC_COSMIC_BUCKET_SLUG,
  read_key: import.meta.env.PUBLIC_COSMIC_READ_KEY,
});

Now that we’re all set up, let’s write our API call to get the Post we made in our dashboard.

// src/lib/cosmic.js
export async function getAllPosts() {
  const data = await bucket.objects
    .find({
      type: "posts",
    })
    .props("title,slug,content,metadata")
  return data.objects;
}

Using Cosmic’s chaining methods, we can find the specific type of Object in our API, which is “posts” (the slug of the Object itself), and set the props to all of the parameters we set up when we created our Object earlier. In our case, we want to retrieve the title, slug, content, and the Cover Image, which lives inside of the metadata.

Remember that the default parameters are accessible at a higher level than the metadata, and the metadata itself comes from the custom metafields you create within an Object. Grabbing the Cover Image would look like this: metadata.cover_image.imgix_url.

Rendering the data

Now we can pull in the API call onto one of our Astro pages. By calling the getAllPosts function in the “helmet” of our Astro page or component, we can access all of the content we create in Cosmic.

// src/pages/index.astro
import { getAllPosts } from "../lib/cosmic"
const data = await getAllPosts()

To render out a list of the posts we make, we can create a minimal Card component like this:

// src/components/Card.Astro
---
const { href, title, body } = Astro.props
---
<li class="bg-white rounded-md shadow-md hover:shadow-xl transition">
  <a href={`/blog/${href}`}>
    <div class="flex flex-col h-full gap-y-2 p-6">
      <h2 class="font-semibold text-xl pr-4 pt-2">
        {title}
      </h2>
      <p>
        {body}
      </p>
    </div>
  </a>
</li>

Note that this is an Astro component. We can pass props to it by defining a de-structured object to Astro.props. This functionality is done within the dashes at the top of the component, or the “helmet.”

Going back to our index.astro page, let’s pass the data from Cosmic and render the card.

// src/pages/index.astro
---
import { getAllPosts } from "../lib/cosmic"
import Card from "../components/Card.astro";
const data = await getAllPosts()
---

<section>
    <ul class="grid md:grid-cols-2 gap-8">
      {
        data.map((post) => (
          <Card
            title={post.title}
            href={post.slug}
            body={post.metadata.excerpt}
          />
        ))
      }
    </ul>
  </section>

You’ll notice that we are passing the slug of our Cosmic post into the href prop. We can generate dynamic routes easily with Astro. We do this using getStaticPaths, which will generate dynamic page routes at build time.

// src/pages/blolg/[slug].astro
---
import { getAllPosts } from "../../lib/cosmic";
import { Image } from "@astrojs/image/components";

export async function getStaticPaths() {
  const data = (await getAllPosts()) || [];

  return data.map((post) => {
    return {
      params: { slug: post.slug },
      props: { post },
    };
  });
}

const { post } = Astro.props;
---

<article>
  <section class="border-b pb-8">
    <h1 class="text-4xl font-bold">{post.title}</h1>
    <div class="my-8"></div>
  </section>
  <Image
    src={post.metadata.cover_image.imgix_url}
    format="webp"
    width={1200}
    aspectRatio={16 / 9}
    quality={50}
    alt=""
    class={"rounded-md shadow-lg my-12"}
  />
  <p>{post.content}</p>
</article>

Using getStaticPaths, we are generating the path for each “Post” in Cosmic using it’s slug. This happens at build time and uses the data stored in params. We then pass the data for each “Post” through to the props and further set the { post } object to Astro.props. We can re-use our HTML template below the helmet for each blog post we render.

After running a mobile Lighthouse report for the application, we have achieved 100s all across the board with little effort.

Conclusion

We hope you found this guide helpful to learn how Astro provides ease of use in development, easy integration with a headless CMS, and the capability to achieve high-performing Lighthouse scores out of the box. For more info on Astro and headless CMS, you can read about it here. You can check out the template used in this guide here. You can tune into our podcast, Build Time, where we cover topics like headless CMS, Next.js, React, and many many more.

Building React Components from headless CMS markdown

Stefan Kudla — Wed, 24 Aug 2022 21:15:16 +0000

Markdown has become a staple in my workflow as a developer and content creator. It’s quick to write, flexible with its features, and has easy-to-remember syntax.

Using React Markdown, we’re going to create Custom React Components (in a Next.js application) using parsed markdown retrieved from a headless CMS. By doing so, we will be able to quite easily utilize cutting-edge features like Next Image in the body of our Markdown. This way, we can take dynamic content and shape it the way we want, improving performance, accessibility, and overall user experience.

This article features the Next.js Developer Portfolio Template I built with Cosmic. You can follow along by visiting the App Template Page and importing the template into your own Cosmic Bucket (create an account if you’d like to follow along this way and haven’t already made one). Or, view the source code if you’d rather follow along with your own application.

A brief overview of React Markdown

React Markdown is a React Component to render markdown which lets you create and render custom components instead of standard HTML components. It is safe by default (no dangerouslySetInnerHTML) and allows you to use a wide array of plugins from remarkjs to enhance your markdown.

To further understand this component, let’s reference the diagram above step-by-step.

The markdown content is parsed and turned into a markdown syntax tree
The markdown syntax tree is transformed to an HTML syntax tree through remark
The HTML syntax tree is transformed through rehype, and rendered to React components.

Installing the packages

To use react-markdown, we only need the package itself.

pnpm add react-markdown
## or
npm install react-markdown
## or
yarn add react-markdown

To retrieve our data from Cosmic, we can install the Cosmic NPM module.

pnpm add cosmicjs
## or
npm install cosmicjs
## or
yarn add cosmicjs

Getting our Markdown content from a headless CMS

In this example, we’re retrieving markdown content from a Cosmic Object that is going to be the body of text for an article. Within the pages directory of our Next.js application, make sure you have a [slug].jsx file created within a folder called posts, articles , or whatever you please.

We can import the cosmicjs package, set the environment variables, then write two functions that will get data from our Cosmic dashboard.

const Cosmic = require('cosmicjs')
const api = Cosmic()

const bucket = api.bucket({
  slug: process.env.COSMIC_BUCKET_SLUG,
  read_key: process.env.COSMIC_READ_KEY,
})

export async function getAllPostsWithSlug() {
  const params = {
    query: { type: 'posts' },
    props: 'title,slug,metadata,created_at',
  }
  const data = await bucket.getObjects(params)
  return data.objects
}

export async function getPostAndMorePosts(slug, preview) {
  const singleObjectParams = {
    query: { slug: slug },
    ...(preview && { status: 'any' }),
    props: 'slug,title,metadata,created_at',
  }
  const moreObjectParams = {
    query: { type: 'posts' },
    ...(preview && { status: 'any' }),
    limit: 3,
    props: 'title,slug,metadata,created_at',
  }

  try {
    const data = await bucket.getObjects(singleObjectParams)
    const moreObjects = await bucket.getObjects(moreObjectParams)
    const morePosts = moreObjects.objects
      ?.filter(({ slug: object_slug }) => object_slug !== slug)
      .slice(0, 2)
    return {
      post: data?.objects[0],
      morePosts,
    }
  } catch (error) {
    if (is404(error)) return
    throw error
  }
}

Within our [slug].jsx file, we can call getStaticProps() and getStaticPaths() , pull in data, then pass it through to our Post component.

// pages/posts/[slug].jsx

const Post = ({ post }) => {
  return (
    <>
      <article>
        <PostBody content={post.metadata.content} />
      </article>
    </>
  )
}
export default Post

export async function getStaticProps({ params, preview = null }) {
  const data = await getPostAndMorePosts(params.slug, preview)

  return {
    props: {
      preview,
      post: {
        ...data.post,
      },
      morePosts: data.morePosts || [],
    },
  }
}

export async function getStaticPaths() {
  const allPosts = (await getAllPostsWithSlug()) || []
  return {
    paths: allPosts.map(post => `/posts/${post.slug}`),
    fallback: true,
  }
}

Now that we’ve got the page itself set up, let’s dive into our PostBody component, where we will be using react-markdown to render our content.

Implementing React Markdown

Within our PostBody we can import and use the ReactMarkdown Component. We simply import the package and wrap our content in the ReactMarkdown component.

import ReactMarkdown from 'react-markdown'

const PostBody = ({ content }) => {
  return (
    <div className="max-w-2xl mx-auto">
      <ReactMarkdown>
        {content}
      </ReactMarkdown>
    </div>
  )
}
export default PostBody

Creating custom components

Furthermore, we can create custom components. To do this, we will create a components object above our PostBody component and pass it through to the ReactMarkdown component.

When creating the custom components, the key will be the HTML equivalent for the content we write in markdown. The parameter will be what you want to render as an HTML element, and will have access to the props of that element. For example, the a element will give us access to href and children and the img tag src and alt.

The JSX you write within these functions will return the provided element. You could write something like h1: h1 => {return (<h2>{h1.children}</h2>)} and you will render h2 elements for every h1 written in markdown.

import ReactMarkdown from 'react-markdown'

const components = {
  a: a => {
    return (
      <a href={a.href} rel="noopener noreferrer" target="_blank">
        {a.children}
      </a>
    )
  },
}

const PostBody = ({ content }) => {
  return (
    <div className="max-w-2xl mx-auto">
      <ReactMarkdown
        components={components}
      >
        {content}
      </ReactMarkdown>
    </div>
  )
}
export default PostBody

My favorite use case so far has been implementing Next Image for optimized image sizes and better page load times.

Without using Next Image, having lots of images in our markdown will require all of the images to be loading when the page is requested. This is slow and negatively impacts user experience and lighthouse scores.

When I refresh the page, all of the images will be loaded at once. Yikes!

Let’s improve this! Import Image from next/image, then create a custom img component inside of the components object. Remember, we have access to some standard props with these components, so we can simply grab the src and alt from the img. We pass them into our Image component written in our JSX, defining a set height and width, a lower quality to the file size, and a layout of responsive to serve scaled images according to screen size, ensuring that small devices don’t receive any unnecessarily large file sizes.

import ReactMarkdown from 'react-markdown'
import Image from 'next/image'

const components = {
  a: a => {
    return (
      <a href={a.href} rel="noopener noreferrer" target="_blank">
        {a.children}
      </a>
    )
  },
  img: img => {
    return (
      <Image
        src={img.src}
        alt={img.alt}
        width={400}
        height={300}
        quality={50}
        layout="responsive"
        objectFit="contain"
        objectPosition="center"
      />
    )
  },
}

const PostBody = ({ content }) => {
  return (
    <div className="max-w-2xl mx-auto">
      <ReactMarkdown
        components={components}
      >
        {content}
      </ReactMarkdown>
    </div>
  )
}
export default PostBody

Now that we’ve added the custom Image component, let’s reload the page and see the magic.

We are no longer requesting all of those images at once, and as we scroll down the page, the lazy loaded images start to appear in the network tab.

Having the flexibility to create custom React Components for markdown is essential and with react-markdown, we can achieve this in just a few lines of code. Boosting performance, increasing link security, and having overall increased capabilities for our markdown data are what we achieve here. Aside from the improvements within our application, this component is super easy to use and taps us into the unifiedjs (giving us superpowers!).

Come build some cool sh!t with us! You can tune into our new show Build Time, where we cover topics like headless CMS, Next.js, React, and many many more.

How to use Next.js Preview Mode with the Cosmic headless CMS

Stefan Kudla — Thu, 11 Aug 2022 16:06:29 +0000

Static web page generation is practical when fetching data from a headless CMS. However, when adding new content to our CMS after our site is built, we will want a way to preview draft content that is not yet ready to be published.

Using Next.js Preview Mode, we solve this issue by rendering pages at request time, allowing us to see unpublished content that was not present during static generation. Let’s explore how we can use Next.js Preview Mode with a headless CMS to preview draft content for ourselves and collaborators.

In this example, we’re using Cosmic as our headless CMS. You can check out the live demo and clone the Developer Portfolio template GitHub repository.

Setting our secret preview token and URL

To ensure only those with access can see our preview URLs, let’s create a string for our secret preview token. You can use this API key generator to get a base64 secret string, or just use a simple text string that you create.

Now we set the custom preview URL, which will be located at ‘pages/api/preview.js’ in our Next.js project.

  https://<YOUR-SITE>/api/preview?secret=<YOUR_SECRET_PREVIEW_TOKEN>&slug=[object_slug]

Setting this preview URL in Cosmic is easy. We can navigate to the settings of an Object Type, and set the Preview Link using the convention above. For testing during development, set to localhost, otherwise set it to your desired URL. Using Cosmic, set the slug parameter to [object_slug]. Cosmic will automatically convert this short code to the slug of a given Object.

Getting the preview post by slug

First, let’s create an async function to fetch the preview post data from our headless CMS using the Cosmic NPM module.

const Cosmic = require('cosmicjs')
const api = Cosmic()

const bucket = api.bucket({
  slug: YOUR_BUCKET_SLUG,
  read_key: YOUR_READ_KEY,
})
const is404 = error => /not found/i.test(error.message)

export async function getPreviewPostBySlug(slug) {
  const params = {
    query: { slug },
    status: 'any',
    props: 'slug',
  }

  try {
    const data = await bucket.getObjects(params)
    return data.objects[0]
  } catch (error) {
    // Don't throw if a slug doesn't exist
    if (is404(error)) return
    throw error
  }
}

By setting the status param to any, we fetch all unpublished Objects with a draft status as well as the latest draft of a published Object upon request.

Creating the preview API route

Now that we’ve configured the secret preview token in our CMS, we create an API route that checks that the token matches and then fetches the unpublished post we requested with the preview URL we set earlier (if it exists).

Once the token matches and if the slug we requested exists in our CMS, we enable Preview Mode and set the cookies with res.setPreviewData({}) using a Temporary Redirect to the location of our unpublished post.

export default async function preview(req, res) {
  // Check the secret and next parameters
  // This secret should only be known to this API route and the CMS
  if (
    req.query.secret !== process.env.COSMIC_PREVIEW_SECRET ||
    !req.query.slug
  ) {
    return res.status(401).json({ message: 'Invalid token' })
  }

  // Fetch the headless CMS to check if the provided `slug` exists
  const post = await getPreviewPostBySlug(req.query.slug)

  // If the slug doesn't exist prevent preview mode from being enabled
  if (!post) {
    return res.status(401).json({ message: 'Object not found' })
  }

  // Enable Preview Mode by setting the cookies
  res.setPreviewData({})

  // Redirect to the path from the fetched post
  // We don't redirect to req.query.slug as that might lead to open redirect vulnerabilities
  res.writeHead(307, { Location: `/posts/${post.slug}` })
  res.end()
}

Updating getStaticProps

Now that we have set the Preview Mode cookies with res.setPreviewData, getStaticProps will be called upon request.

On the page where we render our preview post, getStaticProps will accept an object as an argument, which will be the unpublished data we fetched from our headless CMS.

export async function getStaticProps({ params, preview = null }) {
  const data = await getPostAndMorePosts(params.slug, preview)
  return {
    props: {
      preview,
      post: {
        ...data.post,
      },
    },
  }
}

Using Preview Mode in Cosmic

Now that we’ve set up our API routes and functionality for preview mode, using it with Cosmic is as easy as clicking a button. Cosmic will take the preview URL we set up earlier and generate a query for each Object we create, automatically adding the Object slug to the end of it.

Exiting Preview Mode

We can create one more API route to exit Preview Mode. We are simply going to clear the preview cookies, and redirect to the home page.

export default async function exit(_, res) {
  // Exit the current user from "Preview Mode". This function accepts no args.
  res.clearPreviewData()

  // Redirect the user back to the index page.
  res.writeHead(307, { Location: '/' })
  res.end()
}

Since we are setting the cookies for the current session of our application, we can treat this data as a context for the entire app. In the live demo used in this tutorial, I’ve created a banner that displays when the application is in Preview Mode. In the banner, we then use a Next.js Link to route to the exit-preview API route, clearing the preview mode cookies and bringing the application back to the home page.

Whether you are wanting to share new content with your team, or simply want to see your own content before it goes live, using Next.js Preview Mode is a solid solution for doing so. Sharing content is as easy as providing the preview URL with your team, or clicking a button in Cosmic.

I hope you found this article useful. You can tune into our new show Build Time, where we cover everything from headless CMS, Next.js, React, and much more.

How to use Next.js Image with a headless CMS

Stefan Kudla — Tue, 02 Aug 2022 14:54:12 +0000

The Next Image component is one of the most useful and utilized features of Next.js. This component’s performance, ease of use, and flexibility contributes to the amazing developer experience that Next.js offers.

In this article we will explain how using Next.js Image with a headless CMS can automate optimizations for your website images across all devices and network speeds leading to faster website performance and a better experience for your website visitors.

Before we get into the code, let’s make ourselves familiar with the Next Image component and how we use it to load images from a headless CMS. You can also follow along with us over on YouTube, where we discuss this article in depth.

The Next Image component

The Next Image component provides cutting-edge features design for the modern web by optimizing the standard component in your code. It assigns the HTML srcset so that images are served responsively based on screen size. Smaller devices will be served a smaller image file with a lower resolution, and the image will scale up in resolution as the screen size increases. Next.js handles this automatically. Here’s what that looks like:

Input

<Image
  src={url}
  quality={60}
  alt={`Cover image for ${title}`}
  layout="fill"
  objectFit="cover"
  placeholder="blur"
  blurDataURL={`${url}?auto=format,compress&q=1&blur=500&w=2`}
  priority
/>

Output

<img alt="Cover image for Coding Your Design System with Tailwind CSS" sizes="100vw" srcset="/_next/image?url=https%3A%2F%2Fimgix.cosmicjs.com%2F87625240-0acb-11ed-b7be-d956591ad437-design-systems-tailwind.png&amp;w=640&amp;q=75 640w, /_next/image?url=https%3A%2F%2Fimgix.cosmicjs.com%2F87625240-0acb-11ed-b7be-d956591ad437-design-systems-tailwind.png&amp;w=750&amp;q=75 750w, /_next/image?url=https%3A%2F%2Fimgix.cosmicjs.com%2F87625240-0acb-11ed-b7be-d956591ad437-design-systems-tailwind.png&amp;w=828&amp;q=75 828w, /_next/image?url=https%3A%2F%2Fimgix.cosmicjs.com%2F87625240-0acb-11ed-b7be-d956591ad437-design-systems-tailwind.png&amp;w=1080&amp;q=75 1080w, /_next/image?url=https%3A%2F%2Fimgix.cosmicjs.com%2F87625240-0acb-11ed-b7be-d956591ad437-design-systems-tailwind.png&amp;w=1200&amp;q=75 1200w, /_next/image?url=https%3A%2F%2Fimgix.cosmicjs.com%2F87625240-0acb-11ed-b7be-d956591ad437-design-systems-tailwind.png&amp;w=1920&amp;q=75 1920w, /_next/image?url=https%3A%2F%2Fimgix.cosmicjs.com%2F87625240-0acb-11ed-b7be-d956591ad437-design-systems-tailwind.png&amp;w=2048&amp;q=75 2048w, /_next/image?url=https%3A%2F%2Fimgix.cosmicjs.com%2F87625240-0acb-11ed-b7be-d956591ad437-design-systems-tailwind.png&amp;w=3840&amp;q=75 3840w" src="/_next/image?url=https%3A%2F%2Fimgix.cosmicjs.com%2F87625240-0acb-11ed-b7be-d956591ad437-design-systems-tailwind.png&amp;w=3840&amp;q=75" decoding="async" data-nimg="fill" class="rounded-t-md transition-all grayscale-0 scale-100 blur-0" style="position: absolute; inset: 0px; box-sizing: border-box; padding: 0px; border: none; margin: auto; display: block; width: 0px; height: 0px; min-width: 100%; max-width: 100%; min-height: 100%; max-height: 100%; object-fit: cover; object-position: center center;">

Out of the box, the Next Image component also lazily loads the images so that they become non-blocking elements. This gives our applications improved page loads and overall better Core Web Vitals. Already, we can see that Next Image handles a lot of the heavy lifting for the developer, and as you explore the component further, you will find even more useful features and use cases.

Images in a headless CMS

When using a CMS like Cosmic, we get some great features that help us store our images in one place, and at that, we can serve these images via the Cosmic API and global CDN. This means our images won’t live on just one server, but rather on a group of geographically distributed and interconnected servers. These servers will cache the images from a network location closest to the user to speed up page loads.

Why does any of this matter? User experience. As the modern web develops further and further, we find better solutions that decrease media file size, utilize non-blocking techniques, and get the content of your site to the user much quicker than ever before. This leads to higher consumer retention rates, better conversion rates, and a globally uniform experience for users.

Getting the data from our Cosmic Bucket

If you’d like to follow along with this particular use case, you can install the Developer Portfolio app template and clone the GitHub repository.

First, we must get the data from our Cosmic Bucket into our project using the Cosmic NPM package.

const Cosmic = require('cosmicjs')
const api = Cosmic()
const bucket = api.bucket({
  slug: process.env.COSMIC_BUCKET_SLUG,
  read_key: process.env.COSMIC_READ_KEY,
})
export async function getAllPosts() {
  const params = {
    query: { type: 'posts' }
    props: 'title,slug,metadata',
    sort: '-created_at',
  }
  const data = await bucket.getObjects(params)
  return data.objects
}

We create an asynchronous function to call the Cosmic API and get all of the ‘posts’ from our Cosmic Bucket by setting the query params to ‘type: “posts”’ (the name of our posts object in Cosmic).

Loading images remotely

Within the Cosmic dashboard, we can access the images we’ve uploaded to the Cosmic CDN simply by navigating to the media folder. From there, we have a few options such as grabbing the URL, the imgix URL, and adding metadata to the image, such as alt text.

For static images, we can always set the ‘src’ in our Image component to a specific URL. In your Cosmic dashboard, navigate to the ‘media’ folder, and on one of the images you’ve uploaded, click on the gear icon. Click on either the ‘URL’ or the ‘imgix URL’ selection, and copy and paste the link of the image.

In the code, it would look something like this:

<Image
  src={'https://imgix.cosmicjs.com/87625240-0acb-11ed-b7be-d956591ad437-design-systems-tailwind.png'}
  alt={'Cover image for my article'}
  layout="responsive"
  width={1200}
  height={640}
  priority
/>

Realistically, we may use a few static remote URLs for the Next Image component in a project, though most commonly we will use Static Imports (images stored locally within the directory of the project) or dynamic URLs from the headless CMS.

In our use case, we will be loading the images from blog posts. Cosmic makes it easy to do this as when you create a new object in Cosmic, you can configure the object Metafields to contain an image Metafield. As a result, creating a new article will give the user the ability to upload the image to the Cosmic CDN and attach it to the blog post all in one go.

Coding the solution

On our ‘[slug]’ pages, we can get the posts by their slug and query for the metadata. We’re using getStaticProps and getStaticPaths to get our dynamic posts.

// /src/posts/[slug].jsx
export async function getStaticProps({ params }) {
  const data = await getPostAndMorePosts(params.slug, preview)
  return {
    props: {
      post: {
        ...data.post,
        content,
      },
    },
  }
}

export async function getStaticPaths() {
  const allPosts = (await getAllPostsWithSlug()) || []
  return {
    paths: allPosts.map(post => `/posts/${post.slug}`),
    fallback: true,
  }
}

Now let’s pass the data into our Next Image component for our blog post header.

// /src/posts/[slug].jsx
import Image from 'next/image'

const Post = ({ post, preview }) => {
  const router = useRouter()
  if (!router.isFallback && !post?.slug) {
    return <PageNotFound />
  }
  return (
    <div className="relative w-full my-4 pb-[55%]">
       <Image
          src={post.metadata.cover_image.imgix_url}
          quality={60}
          alt={`Cover image for ${title}`}
          layout="fill"
          objectFit="cover"
          priority
       />
    </div>
  )
}
export default Post

Placeholders

To add a placeholder for our remote images, we can utilize imgix queries to request a low-resource version of the image. This image is very small, compressed, and blurred to ensure a very small file size. First we set the placeholder param to ‘blur’ and pass the special URL to the blurDataURL param.

<Image
  src={post.metadata.cover_image.imgix_url}
  quality={60}
  alt={`Cover image for ${title}`}
  layout="fill"
  objectFit="cover"
  placeholder="blur"
  blurDataURL={`${post.metadata.cover_image.imgix_url}?auto=format,compress&q=1&blur=500&w=2`}
  priority
/>

The result

Performance optimizations

With Cosmic, we can optimize our images within the dashboard by adding things like specified quality, dimensions, and compression before the images get requested. To do this, go to the Cover Image Metafield and click the Settings button. Then in the settings modal we can add some compression which will reduce the file size and improve the page load. Just like with the placeholder we used earlier, this will add imgix query params to the imgix URL.

The perfect solution

While there isn’t a perfect solution, the Next Image component does a lot of the work for us by providing features to enable us to fine-tune our images to achieve optimal image sizes and performance across all devices and network speeds ultimately leading to a better experience for our website visitors.

How I’m Using Cosmic to Optimize My Website

Stefan Kudla — Wed, 27 Jul 2022 20:06:59 +0000

Introduction

These days, front-end developers have so many amazing tools to build with. We have frameworks and libraries like Next.js and Svelte, which we use to get our apps production-ready, and we have content management systems like Sanity and Cosmic.

In this article, I'm going to tell you why and how I use Cosmic to ensure that my content stays all in one place, and also share some of my favorite features about this powerhouse tool.

Good tools provide features, great ones give you superpowers

As a developer, I'm constantly looking for ways to write less code, because less code means less potential for bugs. I am in favor of the idea that we can use tools to spend less time in our code editors. Cosmic allows me to do those things. I can import Cosmic into my website and once everything is set up, I can just manage my content via the Cosmic dashboard.

I think anyone can agree with me when I say it feels really nice to use a tool that feels intuitive and fresh. Great tools don't just provide you with features, they give you superpowers. Organization and time management is crucial in the work flow of a developer, and a great content management system helps you stay organized, ultimately allowing you to organize exactly how you would like to.

Organization

Let's talk about how important organization is when it comes to a CMS. While I'm the only one accessing the dashboard for my website, you've got to consider the fact that many websites have content teams. Cosmic shines in this aspect because collaboration is at the pinnacle of interest when it comes to its features.

Here is what my dashboard currently looks like:

As you can see, everything has it's own place. I have all of my objects at the top left which includes my posts, works (projects), the products I display on my about page, and both post and work categories for filtering. Below my objects is where my media lives. I'm able to compartmentalize my images into different folders to stay organized, and whenever I need to use one of them for an article, I can import them with ease.

Performance

My website is built with Next.js and Cosmic, and these are the lighthouse scores I'm getting for my home page:

Pairing these two technologies truly makes for a tasty combo. Next.js is building all of these articles statically at build time. I wish I had more to say about it, but it just goes to show that for the use cases of blogs and news sites, Cosmic really shines with a framework like Next.js.

Integration is quick and concise

When using a CMS, developer experience is crucial. I like to be able to get up and running as quickly as possible, and if there's something I don't know how to do, I need to be able to reference the documentation for that tool.

Cosmic has its own NPM module, so getting up and running with it is quite straight forward.

Although I'm using several functions to get data from my Cosmic Bucket, this is how straight forward it is for me to query for data from Cosmic and display my articles on a page.

Install Cosmic and get environment variables from .env file

pnpm i cosmicjs

Import Cosmic

const Cosmic = require('cosmicjs')
const api = Cosmic()

const BUCKET_SLUG = process.env.COSMIC_BUCKET_SLUG
const READ_KEY = process.env.COSMIC_READ_KEY

const bucket = api.bucket({
  slug: BUCKET_SLUG,
  read_key: READ_KEY,
})

Creating the async function to get my articles

export async function getAllPosts(preview, postType, postCount) {
  const params = {
    query: { type: postType },
    ...(preview && { status: 'any' }),
    props:
      'title,slug,metadata.category,metadata.excerpt,metadata.published_date,created_at,status',
    limit: postCount,
    sort: '-created_at',
  }
  const data = await bucket.getObjects(params)
  return data.objects
}

I can even set parameters to dynamically call these functions. In my case, I'm setting a limit for articles on the home page to three to showcase my recent posts, and since I have two different object types in my Bucket ("Posts" and "Works"), they can share the functionality but be called for each case.

export async function getStaticProps({ preview = null }) {
  const allPosts = (await getAllPosts(preview, 'posts')) || []
  const allPostCategories = (await getAllCategories('post-categories')) || []
  return {
    props: { allPosts, allPostCategories, preview },
  }
}

Bam! We've got all of those articles displayed on my posts page beautifully. Now we can start delegating them into our actual page component props and further them into any other components as props. It's magical.

Community is everything

It's no doubt that a company with a good connection to their users does better. This is especially true for a company offering a software based product. Upon exploring the Cosmic website, I quickly found a link to join the Cosmic Slack channel. I noticed that the community was smaller, though upon entering I could see that if anyone had questions, the companies CEO or someone from the development team would be quick to respond with answers. This is awesome, because as developers, there's nothing like getting help or even delivering feedback directly to those who are working on the product!

Although I did not have any questions or feedback as I first entered, I decided to introduce myself and just let the team at Cosmic know what I was working on. I was delighted to see a prompt response from them, assuring me that there was a good community behind Cosmic. This instantly made me feel better about using the Cosmic CMS knowing that I could get support or feedback whenever, also while knowing there was an active community to interact with!

Coming from WordPress

One of my biggest hurdles coming from WordPress was that importing all of my content would be an issue. I had around 15 articles that I had written in WordPress, though still wanted on my new site. Fortunately, Cosmic has a WordPress Importer extension. Unfortunately, it was not perfect. I noticed that a lot of my content was imported into the wrong Metafields in Cosmic and I had to manually update some things. While this is not the end of the world considering I had a small amount of articles to transfer over, I could see this being a big setback for larger imports.

Image hosting

While using Cosmic, I've noticed that I find myself hosting images on a Cosmic bucket. If you're already using Cosmic, this is a great solution for storing remote images. Whenever I need to I can just grab my desired images imgix URL (since Cosmic optimizes images on the imgix CDN). Paired alongside Next Image, one of my favorite features of Next.js, grabbing remote images is super easy and performant.

As you can see here, I have all of my images stored in the 'Media' folder, which is there by default. Of course, I could configure sub-folders in there with things like brand images, portraits, images for specific projects I'm working on, you name it. Or, I could even just make separate Buckets for different projects, as this helps me a lot when I'm consulting. Maybe you guessed it, but even the image of my images is hosted in my image hosting Bucket. Mind blown.

Oh the possibilities

As for now, I'm using Cosmic to improve my overall experience as a developer. When I'm in my dashboard, I'm in content-creator mode. When I'm in my code editor, I'm in developer mode. I personally don't enjoy managing my content within my codebase, but to each their own.

I highly recommend hopping aboard the Cosmic spaceship if you:

Want to write articles
Want easy image hosting/optimization
Like working with new tech that is consistently maintained
Enjoy using a product that is backed by a supportive community
Are interested in building with a headless CMS

You can create an account for free and get going with creating your first bucket. You can also join the Cosmic Slack channel if you'd like to interact with the growing community.

I'm more than grateful to have stumbled across this wonderful content management system. Through the process of re-building my website and using Cosmic to do so, I've become a better developer. I've been able to gain clarity on effectively using Next.js for Static Site Generation, Node.js to fetch API data, and Cosmic to manage the infrastructure of my content.

I've just released an article over on Cosmic about Creating a Developer Portfolio with Next.js and Cosmic. If you're looking to build your own developer portfolio and blog then I highly suggest you give it a read!

As always, happy coding and content-creating!

Coding Your Design System with Tailwind CSS

Stefan Kudla — Mon, 25 Jul 2022 20:19:51 +0000

Save yourself some time

As I'm primarily using Tailwind in my React projects, I couldn't tell you a better recipe for building a UI than using swanky Tailwind CSS styled JSX gumbo.

But let's be honest with ourselves here, we don't have to write as much Tailwind as we might be writing. I've been using Tailwind and React for no more than five months, so I'm just learning as I go.

I've found that configuring your project initially will save you a lot of time and stress down the line. Initializing things like Prettier, ESLint, and Postcss before building any part of your UI is the way to go.

Following a style guide

Recently, I was assigned a coding assessment (how exciting). The coding assessment was to look at a mockup image of a simple landing page and build it. A style-guide was also provided to be followed.

Here's the guide:

This guide was simple enough, and I realized at that moment the importance of implementing this style guide into my code.

Coding the style guide

Create a globals.css file in your directory. I often have mine set up in a 'src' file under styles (/src/styles/globals.css). Let's start coding.

First, we see the desired accent and text colors that are to be used. We will set those using CSS custom variables. I have these defined in the ':root' so that they can be accessed globally as well as in the globals.css file itself.

:root {
  --color-fore-reddish: #ee2d1c;
  --color-fore-blackish: #4c4c51;
  --color-fore-blueish: #88939e;
}

We can use these root variables in our JSX as well as our coded design system.

Before we create any custom classes for things like buttons and horizontals, let's define the styles for all of the native HTML elements.

@layer base {
  html {
    scroll-behavior: smooth;
  }
  body {
    padding: 0;
    margin: 0;
  }

  /* Base styles following our design system */
  h1 {
    @apply text-[48px] leading-[48px] text-white;
  }
  h2 {
    @apply text-[36px] leading-[36px] text-blackish;
  }
  h3 {
    @apply text-[22px] leading-[28px] text-reddish;
  }
  p {
    @apply text-[22px] leading-[28px] text-blackish;
  }
  a {
    @apply text-[22px] leading-[28px] text-blueish hover:text-blackish cursor-pointer transition;
  }
}

We're setting our @layer directive to define our base styles.With Tailwind CSS, there are three main "buckets" we can add a layer too.

@layer components - used for things styling entire components like "Nav" or "cta-btn".

@layer utilities - these are universal classes that are present everywhere throughout your code like "flex-col" "opac-half".

@layer base - the base layer of our styles, "h1", "h2", "p".

When writing the actual styles in our globals.css style sheet, we simply use '@apply' to start writing styles with Tailwind.

/* Input */
  h1 {
    @apply text-[48px] leading-[48px] text-white;
  }
  h2 {
    @apply text-[36px] leading-[36px] text-blackish;
  }

/* Output */
  h1 {
    font-size: 48px;
    line-height: 48px;
    color: rgb(255 255 255); 
  }
  h2 {
    font-size: 36px;
    line-height: 36px;
    color: rgb(76 76 81); 
  }

Now let's finish up coding this style guide by defining the component and utility classes.

@layer components {
  .cta-btn {
    @apply bg-reddish text-[22px] text-white py-3 px-8 rounded-full hover:opacity-70 transition whitespace-nowrap;
  }
}

@layer utilities {
  .accent-gradient {
    @apply bg-gradient-to-b from-[#ee2e1d] to-[#ffb1b5];
  }
  .horizontal {
    @apply border-b border-b-[#e8e8e8];
  }
  .horizontal-top {
    @apply border-t border-b-[#e8e8e8];
  }
}

Finding a good balance

Depending on how big your project is and how scalable it needs to be, finding the happy medium for coding your design system is crucial. While you want to set up your project with scalability in mind, you don't want to over engineer and take away from the on-demand benefits of Tailwind.

It is also important to consider how deep your design system (reference) goes and the complexity of your project. Maybe you have a fairly straight forward blog and you only need one or two layouts to achieve the desired design. You wouldn't really have an issue with setting up component and utility classes in your coded design system.

Then again, you probably wouldn't have a problem writing a few strings in Tailwind for your class names, though our goal is to reduce redundancy at the end of the day, and don't forget how painful it is having to sift through several components and repeatedly change the same styles.

As I'm on this journey to becoming a better programmer, designer, and writer each and every day, I'm constantly finding ways to be more efficient. Let's keep the conversation going over on LinkedIn and Twitter. You can also visit me over at stefankudla.com.

Happy coding and creating!

Creating a Developer Portfolio with Next.js and Cosmic

Stefan Kudla — Tue, 19 Jul 2022 14:07:23 +0000

As a developer, one of the most valuable things you can do is create your presence on the internet. Your portfolio is a great place to showcase your proudest projects to the community or potential employers.

Today, we’re going to build a beautiful developer portfolio, giving you a place to store your blog posts and projects. After completing this tutorial, you will understand how building with modern developer tools comes with great benefits. Faster page loads, optimized SEO, and an intuitive developer experience will ultimately enable you to provide better products for your colleagues and clients.

Tools we’ll be using

To build our developer portfolio, we’re going to use the following technologies:

Next.js - A React framework that makes it easy to spin up a full-stack application.
Cosmic - A Headless CMS enables the independence of the data (content) layer and gives us the ability to quickly manage template content. In this case, our blog and project posts.
Tailwind CSS - A performant utility-first CSS framework that can be composed directly in your markup.

Highlights

While the main objective of this portfolio is to be functional and showcase who you are as a developer, I wanted to ensure that we prioritized user experience and overall website performance.

Organized content management - With Cosmic, we can store all of our content in one place. Once we write the code for our user interface, we will not have to worry about storing content within our project. Cosmic handles all of this.
Next.js Image optimization - With the power of Next Image, we will ensure that our images won’t be slowing us down one bit. Storing local images of ourselves (if you prefer to include those) as well as the remote images we will query from our Cosmic bucket, we will make sure to utilize things like lazy loading, placeholder blur, and built-in image optimization from Next.js.
SEO and Accessibility best practices - As a web developer, it is crucial that you cater to good semantics to ensure that your site is accessible by anyone.

TL;DR

Install the template

View the live demo

Check out the code

Starting from a blank Next.js app

To get started with this template, let’s create a new Next.js application.

pnpx create-next-app@latest nextjs-developer-portfolio
# or
yarn create next-app nextjs-developer-portfolio
# or
npx create-next-app@latest nextjs-developer-portfolio

Then install the dependencies.

cd nextjs-developer-portfolio
pnpm install
# or
cd nextjs-developer-portfolio 
yarn
# or
cd nextjs-developer-portfolio 
npm install

Let’s fire up our application! After running the command below, you can open up http://localhost:3000 in your browser.

pnpm install
# or
yarn install
# or
npm install

Getting started with Cosmic

First things first, let’s create a free Cosmic account. Once created, we can go ahead and create a new project. Select “Start from scratch”, then you can name your project. Since this is our primary bucket where we will be building and deploying our project, I’m going to name the bucket environment “Production”. Go ahead and select “Save Bucket”.

Next, we can start adding objects to our Cosmic Bucket.

The Content Model

The Content Model is a blueprint for our object. It consists of data that can be as simple as one single text value or as complex as storing several data values. These could be strings, numbers, booleans, etc. The whole point of configuring this content model is so that every time we create a new blog post, all of the Metafields we created in our blueprint will be there for us to fill out.

To add our custom Metafields to the content model, we can click on the plus symbol and add a new Metafield. We will be then prompted to select from a list of Metafield Types.

Categories object

Let’s create our categories object. The only piece of data we will need for our categories object is going to be the title, so we do not have to add any Metafields.

Posts object

This is what our content model will look like for the posts object. The Metafields will be:

Category - Which we will link to our Post Categories object. Type: Single Object Relationship.
Cover Image - An image we can display at the top of our post. Type: Image / File.
Excerpt - A short sentence summarizing our post. Type: Plain Text Input.
Content - The text content that will go inside of our post. Type: Markdown.

Note that by default, when we create a new object it will have a content and slug field. We will be using the slug (which Cosmic generates for us) in our code to properly route our posts.

Before we dive into the code, go ahead and create a post with sample data so that we can test it later on.

Works object

We will also be making a “Works” object to showcase our best projects. Copy the blueprint for the “Posts” object, though add in two additional Metafields. These will be:

Repo URL - A link to the projects’ GitHub repository. Type: “Plain Text Input”.
Live URL - A link to the live website for your project. Type: “Plain Text Input”.

Installing the Cosmic NPM module

Let’s install the Cosmic dependency into our project and start writing the code that grabs the posts from our bucket.

cd nextjs-developer-portfolio
pnpm install cosmicjs
# or
npm install cosmicjs
# or
yard add cosmicjs

Setting your environment variables

We will need to create three environment variables inside of a .env file in the root of our project. The Bucket Slug and Read Key can be found in your dashboard in Settings > API Access. The preview key is something that you can define yourself, so go ahead and create your own preview secret key so that you can use it later on.

// nextjs-developer-portfolio/.env

COSMIC_BUCKET_SLUG=<your_bucket_slug>
COSMIC_READ_KEY=<your_read_key>
COSMIC_PREVIEW_SECRET=<your_preview_secret>

Getting our Posts

Now that we have our environment variables set, we are ready to access the Cosmic API and retrieve our data.

// nextjs-developer-portfolio/src/lib/cosmic.js

const Cosmic = require('cosmicjs')
const api = Cosmic()

const BUCKET_SLUG = process.env.COSMIC_BUCKET_SLUG
const READ_KEY = process.env.COSMIC_READ_KEY

const bucket = Cosmic().bucket({
  slug: BUCKET_SLUG,
  read_key: READ_KEY,
})

While getting our posts, we can also create a few parameters here. In our example, getting our "Posts" and "Works" will share the same function, though we will pass in an argument when we call the function declaring which object to get. We can do this for our categories as well by passing the title of our Cosmic object as an argument.

To get a better understanding of how we are getting our data from Cosmic, let’s break it down:

Query - sending valid JSON queries on Object and Media endpoints. You can view a full guide here.
Status - if not included, status defaults to published. You can include both published and draft content by setting status to any.
Props - used to declare only the data you need and limit the payload size.
Limit - the number of objects to return.
Sort - sort your content.

// nextjs-developer-portfolio/src/lib/cosmic.js

export async function getAllPosts(preview, postType, postCount) {
  const params = {
    query: { type: postType },
    ...(preview && { status: 'any' }),
    props:
      'title,slug,metadata.category,metadata.excerpt,metadata.published_date,created_at,status',
    limit: postCount,
    sort: '-created_at',
  }
  const data = await bucket.getObjects(params)
  return data.objects
}

Parsing the markdown

Since we will be writing our content in Markdown, we will need a way to serialize the markdown into HTML. To do this, we will install the dependencies remark and remark-html.

pnpm install remark remark-html
// or
yarn add remark remark-html
// or
npm install remark remark-html

Now that we’ve installed these packages, create a file in the lib folder of your project.

// nextjs-developer-portfolio/src/lib/markdownToHtml.js
import { remark } from 'remark'
import html from 'remark-html'

export default async function markdownToHtml(markdown) {
  const result = await remark().use(html).process(markdown)
  return result.toString()
}

Creating a list of posts

Now that we’ve done the basic setup of our Cosmic bucket, created a .env file with the required environment variables, created the functionality to get the data, and parsed our markdown, we can create a list of posts so that users can choose from them.

For our post lit, we will display the title and the excerpt from the post. This is what it will look like:

We can create a “PostList.jsx” component so that we can reuse our post list with ease on several parts of our site. When we render this component on one of our pages, we will pass the data of all the posts we receive from Cosmic to the “allPosts” parameter.

// nextjs-developer-portfolio/src/components/PostList.jsx

import Link from 'next/link'

const PostList = ({ allPosts, postType }) => {
  return (
    <>
      <ul className="grid grid-cols-1 md:grid-cols-2 gap-8">
        {allPosts.map(post => (
          <li
            className="flex flex-col bg-white dark:bg-gray-800 rounded p-8 shadow-sm"
            key={post.title}
          >
            <Link href={`/${postType}/${post.slug}`}>
              <a className="group flex flex-col justify-center gap-y-6">
                <div className="max-w-lg">
                  <h3 className="text-xl font-bold mb-1 group-hover:text-accent transition-colors">
                    {post.title}
                  </h3>
                  <p className="text-fore-subtle mb-3 lg:mb-0 lg:pr-6">
                    {post.metadata.excerpt}
                  </p>
                </div>
                <p className="flex items-center text-fore-subtle text-sm">
                  Read more
                </p>
              </a>
            </Link>
          </li>
        ))}
      </ul>
    </>
  )
}
export default PostList

Rendering the Post List

Now, let’s take that post list and render it on our “Posts” page. If you haven’t yet, create a folder in your “pages” folder within your directory called “posts”. Then, let’s create the index file for that page where our PostList will live.

With getStaticProps, we will call the functions we created earlier to get those posts from Cosmic. The awesome part about this is that when it comes to build time, these posts will be built statically and deployed to an edge CDN, making the pages available to users around the world within milliseconds.

We are also calling our function that gets the post categories so that we can then display them on the page and create the functionality to filter through the posts.

// nextjs-developer-portfolio/pages/posts/index.jsx

import { useState } from 'react'
import { getAllPosts, getAllCategories } from '@/lib/cosmic'
import PostList from '@/components/PostList'

const Posts = ({ allPosts, allPostCategories }) => {
  const [filterCategory, setFilterCategory] = useState('All')

  const filteredPosts = allPosts.filter(
    post => post.metadata.category.title === filterCategory
  )

  return (
    <>
      <h1 className="text-2xl md:text-3xl text-fore-primary font-bold">
        Posts
      </h1>
      <ul className="flex flex-wrap gap-y-2 sm:gap-y-0 gap-x-4 my-4">
        <li
          className={
            'All' === filterCategory
              ? 'cursor-pointer font-bold filter--active transition'
              : 'cursor-pointer text-fore-subtle transition'
          }
          onClick={() => setFilterCategory('All')}
          key={'All'}
        >
          All
        </li>
        {allPostCategories.map(category => (
          <li
            className={
              category.title === filterCategory
                ? 'cursor-pointer font-bold filter--active transition'
                : 'cursor-pointer text-fore-subtle transition hover:text-accent'
            }
            onClick={() => setFilterCategory(category.title)}
            key={category.title}
          >
            {category.title}
          </li>
        ))}
      </ul>
      <PostList
        allPosts={filterCategory === 'All' ? allPosts : filteredPosts}
        postType="posts"
      />
    </>
  )
}

export async function getStaticProps({ preview }) {
  const allPosts = (await getAllPosts(preview, 'posts')) || []
  const allPostCategories = (await getAllCategories('post-categories')) || []
  return {
    props: { allPosts, allPostCategories },
  }
}
export default Posts

Creating an individual post page

In the “posts” folder (pages/posts), let’s create a [slug].jsx file. This is where we can write the code for our individual posts.

The content for our post page will be composed of three components:

PostHeader - Containing our PostTitle, post metadata (date and category), and cover image.
PostTitle - The title of the post
PostContent - The styled HTML that we converted from Markdown.
markdown-styles.module.css - A stylesheet for our markdown

/* nextjs-developer-portfolio/src/components/markdown-styles.modules.css */

.markdown {
  @apply text-lg leading-relaxed;
}

.markdown p,
.markdown ul,
.markdown ol,
.markdown blockquote {
  @apply my-6 text-fore-secondary text-[16px] md:text-[18px];
}

.markdown h2 {
  @apply text-fore-primary text-2xl font-bold mt-12 mb-4 leading-snug;
}

.markdown h3 {
  @apply text-fore-primary text-xl font-bold mt-8 mb-4 leading-snug;
}

.markdown p a {
  @apply text-accent underline hover:text-opacity-70;
}

.markdown ul li {
  @apply list-disc list-inside mb-2 bg-back-subtle p-2 rounded text-[16px] md:text-[18px] font-semibold;
}

.markdown ol li {
  @apply list-decimal list-inside mb-2 bg-back-subtle p-2 rounded text-[16px] md:text-[18px] font-semibold;
}

.markdown img {
  @apply max-w-[xl] mx-auto my-12;
}

// nextjs-developer-portfolio/src/components/PostHeader.jsx
import Date from './Date'
import CoverImage from './CoverImage'
import PostTitle from './PostTitle'
import { ExternalLinkIcon } from '@/configs/icons'
import Image from 'next/image'
import avatar from '../../public/images/avatar_4.png'

const PostHeader = ({ post }) => {
  return (
    <>
      <PostTitle>{post.title}</PostTitle>
      <div className="flex items-center mb-8">
        <div className="flex items-center relative">
          <Image
            src={avatar}
            width={42}
            height={42}
            alt="Stefan Kudla"
            className="rounded-full"
            placeholder="blur"
          />
          <span className="ml-2 text-sm">
            Stefan Kudla |{' '}
            <Date dateString={post.created_at} formatStyle="LLLL dd, yyyy" /> |{' '}
            {post.metadata.category.title}
          </span>
        </div>
      </div>
      <CoverImage
        title={post.title}
        url={post.metadata.cover_image.imgix_url}
      />
      <div className="flex flex-row justify-between sm:items-center pb-8 border-b">
        <div className="sm:flex items-center gap-x-2">
{/* For our "Works" page that contains the "liveURL" and "gitHubURL" metafields. */}
          {post.metadata.live_url ? (
            <>
              <a
                href={post.metadata.live_url}
                target="_blank"
                rel="noreferrer"
                className="flex items-center text-accent hover:text-gray-500 text-sm md:ml-4 w-fit"
              >
                Live Site
                <span>
                  <ExternalLinkIcon />
                </span>
              </a>

              <a
                href={post.metadata.repo_url}
                target="_blank"
                rel="noreferrer"
                className="flex items-center text-accent hover:text-gray-500 text-sm"
              >
                Github Repo
                <span>
                  <ExternalLinkIcon />
                </span>
              </a>
            </>
          ) : undefined}
        </div>
      </div>
    </>
  )
}
export default PostHeader

// src/components/PostTitle.jsx
const PostTitle = ({ children }) => {
  return (
    <h1 className="text-fore-primary text-3xl sm:text-4xl md:text-5xl font-bold tracking-normal leading-tight md:leading-none mb-12 mt-4">
      {children}
    </h1>
  )
}
export default PostTitle

// src/components/PostContent.jsx
import markdownStyles from './markdown-styles.module.css'

const PostBody = ({ content }) => {
  return (
    <div className="max-w-2xl mx-auto">
      <div
        className={markdownStyles['markdown']}
        dangerouslySetInnerHTML={{ __html: content }}
      />
    </div>
  )
}
export default PostBody

The page itself:

// nextjs-developer-portfolio/src/pages/posts/[slug].jsx

import { useRouter } from 'next/router'
import PostBody from '@/components/PostBody'
import PostHeader from '@/components/PostHeader'
import { getAllPostsWithSlug, getPostAndMorePosts } from '@/lib/cosmic'
import PostTitle from '@/components/PostTitle'
import Head from 'next/head'
import markdownToHtml from '@/lib/markdownToHtml'
import AlertPreview from '@/components/AlertPreview'
import PageNotFound from '../404'
import Loader from '@/components/Loader'

const Post = ({ post }) => {
  const router = useRouter()
  if (!router.isFallback && !post?.slug) {
        // Checking if the page exists and redirecting to a 404 page if it doesn't.
    return <PageNotFound />
  }
  return (
    <>
      {router.isFallback ? (
        <PostTitle>
          <div className="flex justify-center items-center">
                        // If you have a custom loader, you can use it here, if not just fill in the text "Loading..."
            <Loader />
          </div>
        </PostTitle>
      ) : (
        <>
                    <article className="border-b border-back-subtle py-8 mb-8">
            {post.status === 'draft' && <AlertPreview />}
            <PostHeader post={post} />
            <PostBody content={post.content} />
          </article>
        </>
      )}
    </>
  )
}
export default Post
// Here is where we get all of the posts from Cosmic, and pass the data into the { post } prop.
export async function getStaticProps({ params, preview = null }) {
  const data = await getPostAndMorePosts(params.slug, preview)
// We're calling that function we wrote earlier in /lib/markdownToHtml.js to convert our Markdown to HTML and send it to our <PostBody> component.
  const content = await markdownToHtml(data.post?.metadata?.content || '')

  return {
    props: {
      preview,
      post: {
        ...data.post,
        content,
      },
      morePosts: data.morePosts || [],
    },
  }
}

export async function getStaticPaths() {
  const allPosts = (await getAllPostsWithSlug()) || []
  return {
    paths: allPosts.map(post => `/posts/${post.slug}`),
    fallback: true,
  }
}

Now that we’ve implemented the code into our [slug].jsx page, we can click on any of the posts from the Post List and view the content of our post.

Creating the Work list and Work page

Now that we have the structure for our post page and post index page, we can repeat this for our work page. We can create a “works” folder in our “pages” folder, followed by an index.jsx and [slug].jsx.

Copy the code from both the index.jsx and [slug].jsx in pages/posts, and simply change the instances of “post(s)” to “work(s)”.

export async function getStaticProps({ preview }) {
  const allWorks = (await getAllPosts(preview, 'works')) || []
  const allWorkCategories = (await getAllCategories('work-categories')) || []
  return {
    props: { allWorks, allWorkCategories },
  }
}

Using Preview Mode

With Next.js and Cosmic, we can view drafts of our posts before they are published. In Cosmic, create a post, and once you have filled out the Metafields, select “Save Draft” rather than “Publish”.

Before we can preview our post, let’s set our app up so that we can utilize this functionality.

Grab the COSMIC_PREVIEW_SECRET you created earlier. Then click on the settings icon on your object in Cosmic.

Scroll down to the “Preview Link” field. Replace the with your own COSMIC_PREVIEW_SECRET. What we are doing here is telling our application to go to this route if the post has a status of “draft”.

Note that our link is set to local host and preview mode will only work when we are running our local development server. Once your app is deployed, you can replace “http://localhost:3000” with your domain name.

Let’s go back to our cosmic.js file and create a function that gets the preview post from Cosmic.

// nextjs-developer-portfolio/src/lib/cosmic.js

export async function getPreviewPostBySlug(slug) {
  const params = {
    query: { slug },
    status: 'any',
    props: 'slug',
  }

  try {
    const data = await bucket.getObjects(params)
    return data.objects[0]
  } catch (error) {
    // Throw error if a slug doesn't exist
    if (is404(error)) return
    throw error
  }
}

Now let’s create two API routes in our project - one for the preview itself and the other for exiting the preview. Fortunately, Next.js handles API routes out of the box.

// nextjs-developer-portfolio/src/pages/api/preview.js

import { getPreviewPostBySlug } from '@/lib/cosmic'

export default async function preview(req, res) {
  // Check the secret and next parameters
  // This secret should only be known to this API route and the CMS
  if (
    req.query.secret !== process.env.COSMIC_PREVIEW_SECRET ||
    !req.query.slug
  ) {
    return res.status(401).json({ message: 'Invalid token' })
  }

  // Fetch the headless CMS to check if the provided `slug` exists
  const post = await getPreviewPostBySlug(req.query.slug)

  // If the slug doesn't exist prevent preview mode from being enabled
  if (!post) {
    return res.status(401).json({ message: 'Invalid slug' })
  }

  // Enable Preview Mode by setting the cookies
  res.setPreviewData({})

  // Redirect to the path from the fetched post
  // We don't redirect to req.query.slug as that might lead to open redirect vulnerabilities
  res.writeHead(307, { Location: `/posts/${post.slug}` })
  res.end()
}

// nextjs-developer-portfolio/src/pages/api/exit-preview.js

export default async function exit(_, res) {
  // Exit the current user from "Preview Mode". This function accepts no args.
  res.clearPreviewData()

  // Redirect the user back to the index page.
  res.writeHead(307, { Location: '/' })
  res.end()
}

Now we can go back to our post in Cosmic, and select the “preview” button and our application will open up the preview of our post.

Before we’re done with our preview mode, we need to create a component that alerts us if we are in preview mode, with a link to exit the preview mode. This link takes us to that “exit-preview.js” API route we created above.

// nextjs-developer-portfolio/src/components/AlertPreview.jsx

import Link from 'next/link'

const AlertPreview = () => {
  return (
    <div className="fixed z-20 top-12 left-0 text-fore-subtle bg-back-subtle px-8">
      <div className="py-2 text-center text-sm">
        <>
          This page is a draft.{' '}
          <Link href="/api/exit-preview">
            <a className="underline hover:text-cyan duration-200 transition-colors cursor-pointer">
              Click here
            </a>
          </Link>{' '}
          to exit preview mode.
        </>
      </div>
    </div>
  )
}
export default AlertPreview

Now that we have our banner made, all we need to do is import it into our [slug].jsx pages. By default, our Cosmic object comes with a “status” key value pair. If our post is not published, it has a status of “draft”.

// nextjs-developer-portfolio/src/pages/{posts&works}/[slug].jsx

import AlertPreview from '@/components/AlertPreview'

    ...<article className="border-b border-back-subtle py-8 mb-8">
          {post.status === 'draft' && <AlertPreview />}
          <PostHeader post={post} />
          <PostBody content={post.content} />
       </article>...

Deploying to Vercel

To deploy your project to Vercel, click here. This link will automatically clone the template into a new repository and build and deploy your new application (how cool!). All you have to do is provide the environment variables from earlier.

Conclusion

Now you have a fully functional developer portfolio that you can use to showcase your projects and share your blog posts with the tech community. I hope you enjoyed this tutorial, and if you have any feedback or questions, feel free to join us over at the Cosmic Slack Channel.

Stefan Kudla Software Developer

Stefan Kudla — Wed, 06 Apr 2022 20:17:17 +0000

Hi, my name is Stefan Kudla and I am a Software Developer. You can find me over at my personal website, usually chattering about Software or Coffee, or maybe even something of slight importance.

I am currently a freelancer with a focus on full stack web development, though am currently looking for full time positions.

My Socials: