/nextjs13-2022-11-18

Primary LanguageTypeScript

Agility CMS & Next.js Starter

This is sample Next.js starter site that uses Agility CMS and aims to be a foundation for building fully static sites using Next.js and Agility CMS.

Live Website Demo

New to Agility CMS? Sign up for a FREE account

📢 UPDATED FOR NEXT.JS 13 📢

  • We have updated this starter for Next.js 13. It is using a pre-release version of the @agility/nextjs npm package specialized for the new version.

One Step Create and Deploy to Vercel

Click below to create this project in Agility CMS and deploy it automatically to Vercel.

Deploy with Vercel

About This Starter

  • Uses our @agility/nextjs package to make getting started with Agility CMS and Next.js easy
  • Support for Next.js 13 and React 18
  • Connected to a sample Agility CMS Instance for sample content & pages
  • Uses the getStaticProps function from Next.js to allow for full SSG (Static Site Generation)
  • Supports next/image for image optimization using the <AgilityImage /> component or the next.js <Image /> component.
  • Supports full Page Management
  • Supports Preview Mode
  • Supports the @next/font package
  • Uses the revalidate and fallback properties to enable ISR (Incremental Static Regeneration) builds
  • Provides a functional structure that dynamically routes each page based on the request, loads a Page Templates dynamically, and also dynamically loads and renders appropriate Agility CMS Page Modules (as React components)
  • Supports component level data fetching.

Tailwind CSS

This starter uses Tailwind CSS, a simple and lightweight utility-first CSS framework packed with classes that can be composed to build any design, directly in your markup.

It also comes equipped with Autoprefixer, a plugin which use the data based on current browser popularity and property support to apply CSS prefixes for you.

TypeScript

This starter is written in TypeScript, with ESLint.

Getting Started

To start using the Agility CMS & Next.js Starter, sign up for a FREE account and create a new Instance using the Blog Template.

  1. Clone this repository
  2. Run npm install or yarn install
  3. Rename the .env.local.example file to .env.local
  4. Retrieve your GUID, API Keys (Preview/Fetch), and Security Key from Agility CMS by going to Settings > API Keys.

How to Retrieve your GUID and API Keys from Agility

Running the Site Locally

Development Mode

When running your site in development mode, you will see the latest content in real-time from the CMS.

yarn

  1. yarn install
  2. yarn dev

This will launch the site in development mode, using your preview API key to pull in the latest content from Agility.

npm

  1. npm install
  2. npm run dev

Production Mode

When running your site in production mode, you will see the published content from Agility.

yarn

  1. yarn build
  2. yarn start

npm

  1. npm run build
  2. npm run start

Accessing Content

Content get's passed to your Agility Page Modules as props, but you can also use the REST API or GraphQL to access content.

Some common calls to the SDK include: getContentItem, getContentList, and getSitemap.

getSitemap Parameters

  • channelName, string, required - The contentID of the requested item in this locale.
  • languageCode, string, required - The reference name of the Sitemap in Agility to return.

getContentItem Parameters

  • contentID, integer, required - The contentID of the requested item in this locale.
  • languageCode, string, required - The locale code you want to retrieve content for.
  • contentLinkDepth - The maximum level to expand linked content from this item
  • expandAllContentLinks, boolean - Whether or not to expand entire linked content references, includings lists and items that are rendered in the CMS as Grid or Link.

getContentList Parameters

  • referenceName, string, required - The unique reference name of the content list you wish to retrieve in the current locale. Reference names must be ALL lowercase.
  • languageCode, string, required - The locale code you want to retrieve content for.
  • contentLinkDepth - The maximum level to expand linked content from this item (REST API).
  • expandAllContentLinks, boolean - Whether or not to expand entire linked content references, includings lists and items that are rendered in the CMS as Grid or Link.

Deploying Your Site

The easiest way to deploy a Next.js website to production is to use Vercel from the creators of Next.js. Vercel is an all-in-one platform with Global CDN supporting static & Jamstack deployment and Serverless Functions.

Deploy with Vercel

By clicking the button above, you can get this starter repo deployed to Vercel with a Preview Environment within minutes! It will prompt you to enter your AGILITY_GUID, AGILITY_API_FETCH_KEY, AGILITY_API_PREVIEW_KEY and your AGILITY_SECURITY_KEY.

Notes

How to Register Page Modules

  1. To create a new Page Module, create a new React component within the /components/agility-pageModules directory.
  2. All of the Page Modules that are being used within the site need to be imported into the index file within the /components/agility-pageModules directory and added to the allModules array:
import RichTextArea from "./RichTextArea";
import FeaturedPost from "./FeaturedPost";
import PostsListing from "./PostsListing";
import PostDetails from "./PostDetails";
import Heading from "./Heading";
import TextBlockWithImage from "./TextBlockWithImage";

const allModules = [
  { name: "TextBlockWithImage", module: TextBlockWithImage },
  { name: "Heading", module: Heading },
  { name: "FeaturedPost", module: FeaturedPost },
  { name: "PostsListing", module: PostsListing },
  { name: "PostDetails", module: PostDetails },
  { name: "RichTextArea", module: RichTextArea },
];

How to Register Page Templates

  1. To create a new Page Template, create a new React component within the /components/agility-pageTemplates directory.
  2. All of the Page Template that are being used within the site need to be imported into the index file within the /components/agility-pageTemplates directory and added to the allTemplates array:
import MainTemplate from "./MainTemplate";

const allTemplates = [
  { name: "MainTemplate", template: MainTemplate }
];

How to Properly Link to an Internal Page

To link to internal pages, use the next/link component.

import Link from 'next/link';

<Link href="/posts">
  <a>{item.fields.title}</a>
</Link>

How to Preview Content

Since this is a static site, how can editors preview content in real-time as they are making edits within Agility CMS? Vercel supports Previews out of the box! Simply paste the address of your site deployed on Vercel into your Agility Sitemap Configuration (Settings > Sitemaps), and use it as your Preview Deployment.

Resources

Agility CMS

Next.js

Vercel

Tailwind CSS

Community

Feedback and Questions

If you have feedback or questions about this starter, please use the Github Issues on this repo, join our Community Slack Channel or create a post on the Agility Developer Community.