Background

I'm a frontend developer with around 5 years of experience working with PHP and Javascript in WordPress to create custom themes from scratch.

Motivation

Over those five years I've never used the JAM stack before, not really. There's been some dabbling with Javascript and APIs, but it's mostly been about just getting on specific thing to work, and not creating anything... meaty.

In my career, I'm just starting to work with the JAM stack, and it's becoming a larger part of my daily job.

A lot of the articles I've read seem to assume a decent level of knowledge, or skirt around steps in the process which some might consider mundane or irrelevant.

As a beginner in this tech myself, I figured I'd make a technical resource for me to refer back to, documenting the different steps as I actually go through them.

Aims

• Create a blog style website for technical articles using Nuxt & Prismic
• Keep everything as low cost as possible
• To have a resource I can refer back to and hopefully, to help others

Requirements & features

• Code block with syntax hi-lighting
• Prismic editor with nested `li`s
• Prismic editor with inline code wrapped in back-ticks
• Heading anchor links

Nice to have

• Inline code demos, perhaps Codepen

Getting started

• Prismic blog starter for Nuxt
• Guides and docs used
• Git
• Prismic content purge & sensible defaults
• Nuxt deployment on Netlify
• Netlify custom domain
• Webhook setup for Prismic content changes
• Prettier and eslint

Guides & documentation used

• https://github.com/prismicio-community/nuxt-starter-prismic-blog
• https://nuxtjs.org/deployments/netlify/
• https://docs.netlify.com/domains-https/custom-domains/configure-external-dns/
• https://prismic.io/docs/webhooks

Prismic blog starter for Nuxt

First thing is to setup a Prismic account and select the blog starter for Nuxt.

The starter uses: https://github.com/prismicio-community/nuxt-starter-prismic-blog

The documentation is good, and was fairly straightforward to follow the quick start.

From what I can tell so far, Prismic has repos where the content will live, and the Nuxt code will live in a Git repo.

Git setup

For now, I'll just put everything from the starter into my own repo.

  git init
git add .
git commit -m "first commit"
git branch -M main
git remote add origin [email protected]/repo.git
git push -u origin main

Now all of the code is safe, and there's a working version that can be reverted back to, let's start writing some code!

Project setup

Requirements: Node >= 14

The starter project will compile everything for you, and also includes Tailwind CSS too! To get things up and running

  npm install

Then, to run the dev server

  npm run dev

Okay, everything should be working as expected.

Project deployment with Netlify

As the code is living in a repo at the moment, we're going to need a way to serve up those files. This is where Netlify comes in.

https://nuxtjs.org/deployments/netlify/

Create an account and a new project on Netlify and point it at the Git repo and branch that it should use to deploy.

Netlify will show a unique URL for the project so that it can be viewed on the web.

Netlify custom domain

Once a custom domain has been added, Netlify pushes quite hard for the name servers to be updated to point at Netlify. This can be safely ignored as in my case I wanted to keep using Cloudflare.

https://docs.netlify.com/domains-https/custom-domains/configure-external-dns/

The easiest way to hook up Netlify with a custom domain is to add two records to the domain:

  +-------+------+----------------------------+
| Type  | Name | Target                     |
+-------+------+----------------------------+
| CNAME | @    | unique-id-here.netlify.app |
+-------+------+----------------------------+
| CNAME | www  | unique-id-here.netlify.app |
+-------+------+----------------------------+
*

* I need to add a table component to the editor - this is ridiculous. Thanks to a plain text table generator for saving me the trouble for now.

Once the new records have propagated the domain should now be serving the content on Netlify (in this case, the Nuxt app).

Webhook setup for content updates

So Netlify will rebuild the app when the code repo is pushed to. But the content is living inside of Prismic - how will Netlify know when the content has been updated so that the app can rebuild? Webhooks.

https://prismic.io/docs/webhooks

Also make sure that you follow the guide below. The Netlify URL should be input into the URL field on Prismic. So once content is saved, Prismic will hit the Netlify URL and trigger a new deployment of the app. Sweet.

https://prismic.io/docs/webhooks#netlify

Great, now there's the starter blog on the custom domain. It looks ok, but since I've never used Nuxt or Prismic before, I feel like getting my hands dirty with something simple... let's change the fonts used. Simple, right?

Changing the starter content on Prismic to some sensible defaults

Now the site is being served on the custom domain, it probably makes sense to change some of the blog starter content with some more sensible defaults; purely because I'm not Margaret Smith and it will test the content deployment webhook is working properly.

Once content is updated on Prismic it needs to be saved and then published. Once it is published the webhook fires and triggers a rebuild.

Updated name and job title in settings, saved and published. Nothing happened. The deployment ran fine, but there's no content change.

Is it Cloudflare caching? Cleared cache and nothing.

Nope, it must be something else...

Changing the Nuxt API endpoint to the Prismic API endpoint

Turns out, an important part of the step has been skipped over which isn't really mentioned in any of the docs I've seen so far... change the API endpoint in the starter to your API endpoint.

In `sm.json` change the API endpoint to the correct Prismic content API endpoint. That should then work.

Once it's been pushed to git and the deployment ran again, everything burst into life and the updated content is displayed.

Changing the font family used

So, we'll kick off development with something simple. Changing the font family used.

In the `nuxt.config.js` we can see that the default fonts are inter and libre-baskerville

  '@fontsource/inter/400.css',
'@fontsource/inter/600.css',
'@fontsource/libre-baskerville/400.css',
'@fontsource/libre-baskerville/400-italic.css',
'@fontsource/libre-baskerville/700.css'

However, I've never seen this `fontsource` package before. Guess I'll start there.

Fontsource

https://fontsource.org/docs/introduction

So it turns out that fontsource is a way to self host fonts, but also includes Google Fonts. Fine, that sounds good to me as the two fonts I want are Google Fonts.

I'll do a direct swap of the default fonts with my fonts and all should be well.

  "@fontsource/lora/400.css",
"@fontsource/lora/600.css",
"@fontsource/montserrat/400.css",
"@fontsource/montserrat/400-italic.css",
"@fontsource/montserrat/700.css",

On saving, I hit some issues. Typescript was shouting and there were shed loads of changes showing in the diff. Prettier had gone wild! Upon spot checking a few other files (just saving them with no changes to force the formatting), two things were clear to me:

• Prettier was conflicting with eslint
• This needed resolving now before I went any further

aaaaaaand save.

Nope. Loads of Typescript errors moaning about the formatting. Yep, it's a conflict with eslint and prettier.

Resolving conflicts with Prettier & eslint

First

  npm install --save-dev eslint-config-prettier

Then add the config to .eslint.json

  {
  "extends": [
    "some-other-config-you-use",
    "prettier"
  ]
}

Then...

Everything should work when saving the file now.

Changing the font family used continued...

I then updated the `tailwind.config.js` to use those fonts instead.

    theme: {
    fontFamily: {
      sans: '"Montserrat", ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, "Noto Sans", sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol", "Noto Color Emoji"',
      serif:
        '"Lora", ui-serif, Georgia, Cambria, "Times New Roman", Times, serif',
    },
    extend: {},
  },

Okay, that seems to be working on the dev environment, good.

Let's push those changes so I can see them deployed on the website.

Adding some nice CSS defaults

Since this isn't really relevant to the setup of Prismic with Nuxt and is mainly focused on styling, I've broken that part of the process out into another article, just the keep everything here nice and relevant to Prismic and Nuxt specifically.

> Adding some simple styling