alexburner / catchy-next

Next.js site for Catchy Agency

Catchy Website

https://catchyagency.com/

# Installation
npm run i # install dependencies

# Development
npm run dev # start development server

# Type-checking
npm run types # start typescript compiler --watch
npm run types:once # run typescript compiler once

# Linting / Formatting
npm run format # run prettier
npm run lint # run eslint --fix
npm run fix # run format & lint

# Updating generated GraphQL types
npm run schema # download graphql schema & codegen types

# Manually building / deploying
npm run build # write production version to ./build
npm run start # start production server
npm run deploy:prod # deploy to prod
npm run deploy:dev # deploy to dev

# Debugging dev/build
npm run clean # removes .next cache

Overview

JAMstack architecture

data — Headless CMS

• DatoCMS (with GraphQL API)

view — Frontend Site

• Vercel — hosting, deployment
• Next.js — build, server, routes
• React
  • Apollo GraphQL
  • Bulma CSS
• TypeScript

Frontend Code

• Next.js routes/pages — pages/*
• React components — components/*
• Apollo queries — gql/*
• Bulma styles — styles/*

Initial Setup

DatoCMS API Token

This token is protected/private, to prevent unauthorized use of our API.

It's already added to Vercel for deployments, but we also need it locally for development:

1. Copy .env.local.sample to .env.local (will by ignored by git)
2. Update DATOCMS_API_TOKEN with our Read-only API token value

Node.js & NPM versions

The node and npm versions for this project are defined by the engines field in package.json. Their use is enforced with engine-strict=true in .npmrc. This helps prevent compatibility issues with the Next.js build.

If you're running this locally on your machine, it's recommended to use a tool like nvm or n to help manage installed versions.

Dev Environment

These tools help protect us from ourselves:

• TypeScript for type checking (tsconfig.json)
• Prettier for formatting (.prettierrc)
• ESLint for linting (.eslintrc.js)

They can be run from npm scripts, but it's easier if you install corresponding editor plugins for each.

This repo also has .vscode files to recommend & configure extensions, if you're using that editor:

• .vscode/extensions.json
• .vscode/settings.json

Common Workflows

Updating Site Pages & Components

These changes involve both DatoCMS and the frontend site.

First, in the DatoCMS Admin UI:

1. Update models & blocks in Settings
   • Models — independent schemas (pages, posts, categories)
   • Blocks — child components (sections, cards, rich text, images)
   • When to use blocks instead of models?
   • Note: Some of our models could've been blocks, but they didn't have Nested Blocks when we created them. Newer additions do leverage Nested Blocks (yay!). Someday, it would be nice to take the time and fully migrate over.
2. Test your GraphQL queries in API Explorer

Then, on your computer:

1. Update GraphQL queries (in gql/queries/*)
2. Update TS GraphQL types (run npm run schema)
   • downloads latest schema from DatoCMS
   • constructs types based on gql/queries/*
   • writes type definitions to gql/types/*
3. Update corresponding pages/* and/or components/*

Updating Site Styles

The frontend site uses Bulma, plus a modified version of the Darkly theme.

Theme styles are in:

• styles/theme_variables.scss
• styles/theme_overrides.scss

Site-specific styles are in:

• styles/global.scss

Updating Social Media Trackers

• Social tracking tags (Google, LinkedIn, Twitter) are injected in pages/_document.tsx.
• Route changes in pages/_app.tsx trigger util/gtag.ts tracking.

Deployment

The frontend site is hosted as a Vercel project. It builds Next.js and deploys the results.

All prod builds and deployments should happen automatically.

Automatically

Automatic deployments are triggered by integrations

• GitHub
  • Commit to main branch — builds & deploys to prod
  • Commit to other branches — builds & deploys to new preview
• DatoCMS
  • Publish/unpublish content — rebuilds main & deploys to prod URL
    • This keeps the prod site up-to-date with CMS data

Manually / Locally

• Write build locally — npm run build
• Serve build locally — npm run start
• Deploy local to dev — npm run deploy:dev
• Deploy local to prod — npm run deploy:prod

Previewing CMS updates

DatoCMS + Next.js support a "Preview" feature with live real-time updates, circumventing static site generation. This is accomplished via the DatoCMS useQuerySubscription() hook for fetching data, which will either work with SSG or live preview data, depending on a preview cookie.

The preview cookie is set/unset by two endpoints, using Next.js built-in helpers:

• /api/preview?slug=<destination path>
• /api/exit-preview

We use the Next.js Preview Links plugin to generate a "Preview" button for content editors within the CMS, to view their unpublished updates.