Want to follow along with the build?&nbsp;<a href="https://www.cosmicjs.com/apps/nextjs-static-blog" rel="noopener noreferrer" target="_blank">Click here to grab the app or fork the project.</a>With so many choices for which technology to use when building a website, it can get overwhelming. You need to consider who is going to use it, what content to display and who will maintain it. A static website is a great choice when creating a blog,
band website or e-commerce store. Static websites are an ode to the past when websites were just plain-ol files on a server you accessed via URL. They provide benefits like being fast, having great SEO and not being dependent on a certain runtime like
PHP. This is in comparison to a server-rendered website like what you would have with Wordpress, Drupal or Ruby on Rails.Static websites are built using static assets. The next question becomes where to store (and manage) this content. If you are a solo webmaster, the content can be files in a Git repo. If you have clients or other developers who will want to manage the content, a CMS
(Content Management System) is what you need. A CMS is a service which stores your website content, for example blog posts and concert dates.<img src="https://imgix.cosmicjs.com/8c3df0e0-fa87-11ea-ac76-ed0a0ac0571c-CleanShot-2020-09-18-at-10.15.262x.png?w=1200&auto=format" style="width: 100%;" class="fr-fic fr-dib" alt="Cosmic CMS Dashboard Screenshot">With <a href="https://nextjs.org/docs/basic-features/pages#static-generation-recommended" rel="noopener noreferrer" target="_blank">Next.js SSG</a>, we are using the CMS in a <a href="https://www.cosmicjs.com/headless-cms" rel="noopener noreferrer" target="_blank">&quot;headless&quot; fashion</a>. After trying a bunch of Headless CMS offerings, one I&#39;ve stuck with is Cosmic. <a href="https://www.cosmicjs.com" rel="noopener noreferrer" target="_blank">Cosmic</a> is an intuitive, powerful, and simple-to-use service which lets us get up and running quickly. They provide <a href="https://www.cosmicjs.com/apps" rel="noopener noreferrer" target="_blank">many starter apps</a> that you can preview or fork. For example, I chose the Next.js Static Blog and had a production version of the website running in under 5 minutes.<h3>Choosing the Tech</h3><a href="https://nextjs.org/" rel="noopener noreferrer" target="_blank">Next.js</a> with GraphQL is my personal choice when it comes to Static site development. Next.js is a hybrid React framework which supports building static websites. It also lets you build <a href="https://nextjs.org/docs/basic-features/pages#server-side-rendering" rel="noopener noreferrer" target="_blank">server-side rendered pages</a> when the need arises. It handles routing, has a large community supporting it making it one of the best ways to build a React app in 2020. The other tech you may have heard also does this is <a href="https://www.gatsbyjs.com/" rel="noopener noreferrer" target="_blank">Gatsby.js</a>. Gatsby is more user-friendly but is more opinionated with its
technology choices (forced use of GraphQL versus it being a choice).We are choosing to use GraphQL over <a href="https://www.npmjs.com/package/cosmicjs" rel="noopener noreferrer" target="_blank">the Cosmic NPM module</a>. <a href="https://www.cosmicjs.com/blog/what-is-graphql" rel="noopener noreferrer" target="_blank">GraphQL</a> is a standardized way to get data from services and is a great choice when needing to get data from a CMS. As you create custom data types in Cosmic, you are able to query for it in the GraphQL API. One of the benefits of using GraphQL is that you are less dependent on a specific SDK.<h2>Tutorial</h2><blockquote>For reference, I forked the example Cosmic Next.js project <a href="https://github.com/vercel/next.js/tree/canary/examples/cms-cosmic" rel="noopener noreferrer" target="_blank">here</a>.</blockquote><h3>Creating the Cosmic Project</h3>After creating an account on Cosmic and going through the product tour, you will be shown the &ldquo;Create New Bucket&rdquo; screen.<img src="https://imgix.cosmicjs.com/4877f9e0-fa88-11ea-ac76-ed0a0ac0571c-CleanShot-2020-09-18-at-08.34.472x.png?w=1200&auto=format" style="width: 100%;" class="fr-fic fr-dib" alt="Screenshot of the Cosmic CMS App Search Page">Click &quot;Start with an App&quot; then search and select &quot;<a href="https://www.cosmicjs.com/apps/nextjs-static-blog" rel="noopener noreferrer" target="_blank">Next.js Static Blog</a>&quot; from the list of apps presented. This will do many of things.1. Create a Cosmic bucket2. Create sane data-types inside the bucket for use with a blog3. Fill the bucket with demo content<img src="https://imgix.cosmicjs.com/62326eb0-fa88-11ea-ac76-ed0a0ac0571c-CleanShot-2020-09-11-at-08.28.202x.png?w=1200&auto=format" style="width: 100%;" class="fr-fic fr-dib" alt="Screenshot of the Cosmic CMS Dashboard after creating a bucket">Here is what the created bucket looks like on your Cosmic dashboard <h3>Next.js local development</h3>The next thing we need to do is clone the Next.js code to our local environments. This will enable us to run the Next.js locally and pull content from the demo Cosmic bucket we created.<pre class="prism bash">git clone git@github.com:aleccool213/nextjs-cosmic-graphql-app.git</pre>You can also choose to create a GitHub repository for yourself using <a href="https://github.com/aleccool213/nextjs-cosmic-graphql-app/generate" rel="noopener noreferrer" target="_blank">the template</a>.Once inside the new directory, make sure you are using the correct Node.js version by using <a href="https://github.com/nvm-sh/nvm" rel="noopener noreferrer" target="_blank">NVM</a>.<pre class="prism bash">nvm use v12.18.3</pre>Install Yarn and install the project dependencies.<pre class="prism bash">brew install yarn &amp;&amp; yarn</pre>Run the app!<pre class="prism bash">yarn dev</pre><img src="https://imgix.cosmicjs.com/a740a7b0-fa88-11ea-ac76-ed0a0ac0571c-CleanShot-2020-09-11-at-08.46.142x.png?w=1200&auto=format" style="width: 100%;" class="fr-fic fr-dib" alt="Screenshot of the app running locally but encountering an error due to no environment variables being set">Almost there!<h3>Cosmic Environment Variables</h3>Before we are able to query the Cosmic GraphQL API, our app needs to know where it lives. Environment Variables are deployment specific values which contain sensitive things like API keys.There are three env vars we need to define to have the app work locally. Create a file named `.env.local` (don&#39;t worry it&#39;s ignored by Git), it should look like this:<pre class="prism bash">COSMIC_BUCKET_SLUG=demo-nextjs-static-blog
COSMIC_READ_KEY=77H1zN7bTktdsgekxyB9FTpOrlVNE3KUP0UTptn5EqA7T0J8Qt
# Preview secret can be anything you choose
COSMIC_PREVIEW_SECRET=iwvrzpakhaavqbihwlrv</pre>To get these values, head over to the Settings sidebar menu in your bucket, and click &quot;Basic Settings&quot;.Run the app again with `yarn dev`.<img src="https://imgix.cosmicjs.com/c16501e0-fa88-11ea-ac76-ed0a0ac0571c-CleanShot-2020-09-11-at-09.04.402x.png?w=1200&auto=format" style="width: 100%;" class="fr-fic fr-dib" alt="Screenshot of the example blog running on a local machine"><h3>Looking inside the box</h3>There are two things that we need to understand when it comes to Statically-Generated Next.js apps, pages and routes. <a href="https://nextjs.org/docs/basic-features/pages#scenario-1-your-page-content-depends-on-external-data" rel="noopener noreferrer" target="_blank">Pages are content which depend on external data</a>, and <a href="https://nextjs.org/docs/basic-features/pages#scenario-1-your-page-content-depends-on-external-data" rel="noopener noreferrer" target="_blank">routes are URL routes which depend on external data</a>.
Both have you defining special Next.js specific functions, `getStaticProps` and `getStaticPaths`.The file which contains the logic for generating page content based on the Cosmic GraphQL API is located at <a href="https://github.com/aleccool213/nextjs-cosmic-graphql-app/blob/661144a8eddebff19c709ec18ad8e1765f7600ec/pages/posts/%5Bslug%5D.js#L57" rel="noopener noreferrer" target="_blank">pages/posts/[slug].js</a>.<pre class="prism">export async function getStaticProps({ params, preview = null }) {
  // Get the data from the API
  const data = await getPostAndMorePosts(params.slug, preview);
  // Convert markdown content to HTML content
  const content = await markdownToHtml(data.post?.metadata?.content || &quot;&quot;);
  return {
    props: {
      preview,
      post: {
        ...data.post,
        content,
      },
      morePosts: data.morePosts || [],
    },
  };
}</pre> <pre class="prism">export async function getPostAndMorePosts(slug, preview) {
  // Query for the data through the Cosmic GraphQL API using Apollo Client
  ...
  const moreObjectsResults = await client.query({
    query: gql`
      query getPostQuery(
        $bucketSlug: String!
        $readKey: String!
        $status: status
      ) {
        getObjects(
          bucket_slug: $bucketSlug
          input: {
            read_key: $readKey
            type: &quot;posts&quot;
            status: $status
            limit: 3
          }
        ) {
          objects {
            _id
            slug
            title
            metadata
            created_at
          }
        }
      }
    `,
    variables: {
      bucketSlug: BUCKET_SLUG,
      readKey: READ_KEY,
      status,
    },
  });</pre> This is one example of a page using `getStaticProps`. <a href="https://github.com/aleccool213/nextjs-cosmic-graphql-app/blob/661144a8eddebff19c709ec18ad8e1765f7600ec/pages/index.js#L40" rel="noopener noreferrer" target="_blank">It is also used in the Index page</a>for
getting all the blog post titles and excerpts.`pages/posts/[slug].js` <a href="https://github.com/aleccool213/nextjs-cosmic-graphql-app/blob/661144a8eddebff19c709ec18ad8e1765f7600ec/pages/posts/%5Bslug%5D.js#L73" rel="noopener noreferrer" target="_blank">also contains `getStaticPaths`</a> which tells our Next.js app which routes to generate. <pre class="prism">export async function getStaticPaths() {
  // Get all post data (including content)
  const allPosts = (await getAllPostsWithSlug()) || [];
  return {
    // Tell Next.js all of the potential URL routes based on slugs
    paths: allPosts.map((post) =&gt; `/posts/${post.slug}`),
    fallback: true,
  };
}</pre> After understanding these two aspects, the blog is just a regular React app.<h2>Deploying</h2>Now that we have our website working locally, let&#39;s deploy it to <a href="https://vercel.com/" rel="noopener noreferrer" target="_blank">Vercel</a>. The first step is making sure you have the code in a Git repository.I recommend you have the code in GitHub. You can use the <a href="https://cli.github.com/" rel="noopener noreferrer" target="_blank">GitHub CLI</a> to create a repo in your current directory with `gh repo create`.We now need to sign up for Vercel and have it use the code from the GitHub repo. You can sign up for Vercel with your GitHub account <a href="https://vercel.com/signup" rel="noopener noreferrer" target="_blank">here</a>. You can import the code from GitHub
using the &quot;Import Project&quot; feature.<img src="https://imgix.cosmicjs.com/57b5b090-fa89-11ea-ac76-ed0a0ac0571c-CleanShot-2020-09-16-at-08.34.542x.png?w=1200&auto=format" style="width: 100%;" class="fr-fic fr-dib" alt="Screenshot of the Vercel project view with the Import Project button highlighted">When importing the project, make sure you define the environment variables,&nbsp;`COSMIC_BUCKET_SLUG`,&nbsp;`COSMIC_READ_KEY`, and&nbsp;`COSMIC_PREVIEW_SECRET`.When deployed, all pushes to your default Git branch will have Vercel deploy a new version of your website!<h2>Bonus</h2><h3>Previewing</h3><blockquote>The Next.js docs on preview mode are right <a href="https://nextjs.org/docs/advanced-features/preview-mode" rel="noopener noreferrer" target="_blank">here</a>.</blockquote>Local development and deploying the website to production will cover most of your use-cases. Another common workflow is saving a draft of changes on your CMS and then previewing those changes on your local machine. To do so, we will enable &quot;Preview&quot;
mode both on Cosmic and our Next.js app.First thing we will need to do is have Cosmic know that the Posts object type will be preview-able. On the Posts setting page, add the preview link.<pre>http://localhost:3000/api/preview?secret=iwvrzpakhaavqbihwlrv&amp;slug=[object_slug]</pre>When finished, click &quot;Save Object Type&quot;.Let&#39;s try editing a post and see it show up on our local machine. Try changing the title of &quot;Learn How to Pre-render Pages Using Static Generation with Next.js&quot; and click &quot;Save Draft&quot; instead of &quot;Publish&quot;.<img src="https://imgix.cosmicjs.com/87aff260-fa89-11ea-ac76-ed0a0ac0571c-CleanShot-2020-09-16-at-08.45.272x.png?w=1200&auto=format" style="width: 100%;" class="fr-fic fr-dib" alt="Screenshot of the Cosmic CMS Post data type editing page with Save Draft button highlighted">We now have unpublished changes. Run the app locally with&nbsp;`yarn dev`&nbsp;and then click &quot;Preview&quot; right under &quot;Save Draft&quot;.<img src="https://imgix.cosmicjs.com/97782b40-fa89-11ea-ac76-ed0a0ac0571c-CleanShot-2020-09-16-at-09.20.582x.png?w=1200&auto=format" style="width: 100%;" class="fr-fic fr-dib" alt="Screenshot of the example blog running on a local machine with the preview edits being shown"><h3>Webhooks</h3><blockquote>Note this feature requires a Cosmic paid plan</blockquote>The only way to deploy new content to our blog is to have a developer push to the default git branch. This action will trigger Vercel take the new code and push a new version of our website. We ideally want our content creators to have the same control.
Webhooks are a way we can do this.Let&#39;s set up a webhook which lets Vercel know when our posts in Cosmic have new updates. This will let us deploy new versions of the website without developers needing to do anything.Go to the Git integration settings page (https://vercel.com/[project]/settings/git-integration) in your Vercel project and create a new Deploy Hook named &quot;Cosmic Hook&quot;.<img src="https://imgix.cosmicjs.com/b5ffdf90-fa89-11ea-ac76-ed0a0ac0571c-CleanShot-2020-09-18-at-08.02.262x.png?w=1200&auto=format" style="width: 100%;" class="fr-fic fr-dib" alt="Screenshot of the Vercel webhook settings">What your settings should look like when the webhook is createdNow over in Cosmic settings, we can add this webhook. Let&#39;s add Cosmic notify Vercel when changes get published. You can see how we can do this for previews as well if we wanted to in the future.<img src="https://imgix.cosmicjs.com/bdb264b0-fa89-11ea-ac76-ed0a0ac0571c-CleanShot-2020-09-18-at-08.05.342x.png?w=1200&auto=format" style="width: 100%;" class="fr-fic fr-dib" alt="Screenshot of the Cosmic CMS webhooks settings">To test this go to the same post we tested Previews with and add some content to the end of the article and publish. You should see a deploy happen on Vercel with the new content deployed to the live version of your website!<h2>Conclusion</h2>Want to see what the final website looks like? <a href="https://nextjs-cosmic-graphql-app.vercel.app/" rel="noopener noreferrer" target="_blank">Click here to check it out</a>.

Blogs by Alec Brunelle

Start building today

Blogs by Alec Brunelle

.css-9vqfqm{display:inline-block;white-space:pre;}.css-sanqhm{opacity:0;}Start building today

Start building today