Forem: Brendan

Build a tool to understand your companys internal language with SanityCMS

Brendan — Sun, 08 Dec 2024 10:31:20 +0000

Purpose

This is a simple search app that allows new and existing employees to quickly search for terms, definitions, and acronyms for commonly used phrases within Consulting or Corporate workplaces.

The idea is to have a quick and accessible means for people to search for concepts without having to ask that dreaded 'silly question' of 'what does that mean' in a meeting.

The main intention is to support newly onboarded colleagues, or those of us who have a forgetful mind!

Preview

Check out the website here on Vercel: Jargon Buster

How It's Built

The application itself is probably 'over-engineered' for it's current purpose, however the intent behind the architecture chosen is to easily support and facilitate expansion of features and requirements depending on the companies use-case.

The interesting bit about this application in my opinion is the support for techy people and non-techy people. The search function has the option to use one of two diffrent sources when searching for content.

Excel Parsing

Within the app, there's an embedded excel spreadsheet that can be updated when new content needs added or old content needs to be removed. Simply make your changes in excel, then run the commands at the bottom of this document to deploy them.

SanityCMS

Sanity offers a more dynamic approach to making changes. This tool can be used to make updates without having to redeploy - this is certainly a win win for both sides as the CMS tool is infinitely customisable for those of you that want to tinker with the code base, as well as being straight-forward for non-technical users to add and update terms without having to make any changes to the codebase, or having to jump through hoops for redploying. Simply update the CMS, and your changes will be live.

Tools

React
TypeScript
NextJS
Zod
ShadCN UI
Tailwind CSS
Vercel

Data Sources

Sanity CMS
Excel Spreadsheet

How It's Configured

Inside env.example you can swap the Data Source being pulled into the app.
Swap the values for NEXT_PUBLIC_ENVIRONMENT depending on what data source you want to use.

Find out more

Check out the GitHub here: GitHub: Jargon Buster
Ask me any questions here: Portfolio: Brendan Campbell

Using Notion as a CMS and create a personal blog with React

Brendan — Sun, 08 Sep 2024 19:52:23 +0000

If you’re like me, you’re always on the look-out for the next big app that helps with all things; productivity, note-taking, adhoc lists that you’ll never get through.

That’s where Notion finally comes in. After years of jumping between Evernote, Todoist and a plethora of others, Notion was the one for me. Then, when they released their API, I knew I had made the right choice, and I wanted to see if Notion could be used as a free CMS alternative.

Well, since you’re seeing this now - I finally got around to setting it up, and I want to give a breakdown of how I went about it.

Final Product

Everything in this post is a Notion Block that has been retrieved using their API, and rendered using a mixture of TailwindCSS and DaisyUI.

Prerequisites

Have a notion account
Have node and npm installed on your machine
Create a Notion Integration for a simple page - Check out Notion's Guidance here

Tech Stack

This site is based off of the Create T3 App scaffolding tool. Is it overkill for how I’m currently using it? Absolutely! But, it forced me to make some good decisions in the end (typescript), and overtime I plan to utilise the rest of the features as part of this powerful tech stack because this site is my own sandbox playground.

Technologies

NextJS
TypeScript
Tailwind CSS
ESLint
DaisyUI (themes and card components)

"dependencies": {
    "@notionhq/client": "^2.2.13",
    "next": "^13.4.19",
    "next-auth": "4.20.1",
    "react-syntax-highlighter": "^15.5.0"
}
"devDependencies": {
    "daisyui": "^3.7.4",
    "eslint": "^8.49.0",
    "eslint-config-next": "^13.4.19",
}

Getting Started

Install Notion Package

pnpm i @notionhq/client

Expected File Structure

Root Directory
- lib
  - notion.ts
- src
  - pages
  - Blog.tsx
    - posts
      - [id].tsx
  - types
  - notion_types.ts
- next.config.mjs
- .env

The Code

If you’re not using Create T3 App, the only thing you have to change here is to disregard the import for env.mjs and import your env variables as you normally would.

`lib/notion.ts`

import { Client } from "@notionhq/client";
import { env } from "~/env.mjs";

// instantiate the client
const client = new Client({
    auth: process.env.NOTION_KEY,
});

// get an individual post
async function post(id: string) {
    const myPost = await client.pages.retrieve({
        page_id: id,
});
return myPost;
}

// get all the posts
async function posts() {
    const myPosts = await client.databases.query({
        database_id: env.NOTION_BLOG_DATABASE,
});
return myPosts;
}

// get all the blocks that make up a single post
async function blocks(id: string) {
    const blocks = await client.blocks.children.list({
        block_id: id,
    });
return blocks;
}

export { post, posts, blocks };

`pages/Blog.tsx`

Create a page to show all of the posts, and link to them using Notions ID for the post.

Here we import the get requests for the posts from the lib/notion file we’ve just created

We’re creating a next NextPage passing in the Props

The type for Post hasn’t been created yet - if you don’t NEED this to be type safe, swap posts: [Post] for posts:[any] - it’ll save you a lot of hassle but it’ll be harder to follow these guidelines.

This is using a card design from DaisyUI, that can be changed - the important part is to map over the results, pass the index into the div key={index} to loop through your posts and access the notion properties like this:
javascript{result.properties.Name.title[0].plain_text}

import { type NextPage } from "next";
import Head from "next/head";
import Link from 'next/link';
import Image from 'next/image';
import { posts } from '../../lib/notion'
import type { Post } from '../types/notion_types'

interface Props {
    posts: [Post]
}

const Blog: NextPage<Props> = (props) => {
return (
    <>
<section className="container px-5 py-10 mx-auto max-w-6xl">
<main>
    <h1 className="p-2 font-bold text-center justify-evenly text-4xl text-primary">
        Latest Posts
    </h1>
    <div className='flex flex-wrap justify-around p-10'>
        {
    props.posts.map((result, index) => {
        return (
            <>
                <div key={index} className="card w-64 bg-base-100 shadow-xl m-1">
                    <figure>
                        <Link href={`/posts/${result.id}`}>
                            <Image src={result.cover.external.url} width={300} height={200} alt={''} />
                        </Link>
                    </figure>
                    <div className="card-body">
                        <h2 className="card-title text-md hover:text-accent hover:underline">
                            <Link href={`/posts/${result.id}`}>
                                {result.properties.Name.title[0].plain_text}
                            </Link>
                        </h2>
                        <p className='text-sm'>{result.properties.Description.rich_text[0].plain_text}</p>
                        <div className="card-actions justify-end pt-2">
                            {/* TODO: Adjust this so it will work for 'x' number of tags selected */}
                            {result.properties.Tags.multi_select && result.properties.Tags.multi_select.length >= 1 && (
                                <div className="badge badge-primary text-white">
                                    {result.properties.Tags.multi_select[0]?.name}
                                </div>
                            )}
                            {result.properties.Tags.multi_select && result.properties.Tags.multi_select.length >= 2 && (
                                <div className="badge badge-secondary text-white">
                                    {result.properties.Tags.multi_select[1]?.name}
                                </div>)}
                        </div>
                    </div>
                </div>
            </>
        )})}
    </div>
</main>
</section></>
);};

export async function getServerSideProps() {
// Get the posts
const { results } = await posts();
// Return the result
return {
    props: { posts: results,}
}}

export default Blog;

`posts/[id].tsx`

Using NextJS, by declaring a page with the [id] syntax, we can dynamically pass in values (the individual notion post) and use this file as a template to create the design of our blog page.

The main complexity here lies within const renderBlock = (block: BlockObject) => {...} and const renderRichText = (paragraph: RichTextArr) => {...}

If you don’t care for images, skip the renderImageBlock function

import type { GetStaticProps, NextPage, GetStaticPaths } from 'next';
import Image from 'next/image';
import Head from 'next/head';
import type { ParsedUrlQuery } from 'querystring';
import { post, posts, blocks } from '../../../lib/notion';
import SyntaxHighlighter from 'react-syntax-highlighter';
import { atomOneDark } from 'react-syntax-highlighter/dist/cjs/styles/hljs';
import type { BlockObject, RichTextArr, ImageBlock, BlogPostProps } from '../../types/notion_types'
import { ImageEnum } from '../../types/notion_types'
import { motion, useScroll, useSpring } from "framer-motion";

// Get a single post
export const getStaticProps: GetStaticProps = async (ctx) => {
const { id } = ctx.params as IParams;
// Get the dynamic id
const page_result = await post(id);
const { results } = await blocks(id);

    // Get the children
    return {
        props: {
            id,
            post: page_result,
            blocks: results
        }
    }
}

// Get all posts
export const getStaticPaths: GetStaticPaths = async () => {
const { results } = await posts();

    return {
        paths: results.map((post) => {
            // Go through every post
            return {
                params: {
                    // set a params object with an id in it
                    id: post.id
                }
            }
        }),
        fallback: false
    }
}

const renderBlock = (block: BlockObject) => {
const { type } = block;

    switch (type) {
        case 'heading_1': {
            const text = block.heading_1.rich_text[0].plain_text;
            return (
                <h1 className="...">
                    {text}
                </h1>
            );
        }
        case 'image': {
            const content = renderImageBlock(block.image)
            return (
                <div className='...'>
                    <div className='...'>
                        {content}
                    </div>
                </div>
            )}
        case 'paragraph': {
            const content = renderRichText(block.paragraph);
            return <p className='font-reading my-3 line px-4 leading-6'>{content}</p>;
        }
        default:
            console.log(block)
    }
};

const renderRichText = (paragraph: RichTextArr) => {
return (
    <>
    {paragraph.rich_text.map((text, index) => (
        <span
        key={index}
        className={`
            ${text.annotations.bold ? 'font-bold' : 'font-normal'} 
            ${text.annotations.italic ? 'italic' : 'not-italic'} 
            ${text.annotations.strikethrough ? 'line-through' : ''} 
            ${text.annotations.underline ? 'underline' : ''} 
            ${text.annotations.code ? '...' : ''}`}>
        {text.href ? (
            <a className='text-accent underline font-semibold hover:text-secondary' 
               href={text.href} 
               target="_blank">{text.plain_text}
            </a>
        ) : (
            text.plain_text
        )}
        </span>
        ))}
    </>
    );
}

const Post: NextPage<BlogPostProps> = ({ post, blocks }) => {
const { scrollYProgress } = useScroll();
const scaleX = useSpring(scrollYProgress, {
    stiffness: 100,
    damping: 30,
    restDelta: 0.001
});

    const title = `BC | ${post.properties.Name.title[0].plain_text}`
    return (
        <div className='mx-auto bg-slate-600'>
            <div className="...">
                <Head>
                    <title>
                        {title}
                    </title>
                    <link rel="icon" href={"/favicon.png"} />
                </Head>
                <motion.div className="progress-bar" style={{ scaleX }} />
                {
                    blocks.map((block, index) => {
                        return (
                            <div key={index}>
                                {
                                    renderBlock(block)
                                }
                            </div>
                        )
                    })
                }
            </div>
        </div>
    )}

export default Post;

Making it all TypeScripty

This file is a beast, and I am still learning TypeScript. So whilst I’ve tried to make parts of it reusable such as RichTextArr and not all of it is used in the code base, like MultiSelect - it is great to have this when it came to IDE prompting.

Check out the full file on my GitHub Gist: NotionTypes.ts

export type {
    Post,
    BlockObject,
    BlogPostProps,
    RichText,
    ImageBlock,
    RichTextArr,
};

Constraints (How janky is it?)

First things first, notion was not intended to be used this way. It’s hacky, but it works - and that’s the fun of it.

Images

Notion doesn’t allow you to dynamically set image sizes - you can either set all images in your posts to the same size OR, I used the caption as a way to pass in aspect ratios inside the renderImageBlock function.

Block Types

Everything in Notion is a block, which means - if you haven’t accounted for a style within that - then you don’t render it. For example, bold, underline, italic is all taken care of, and bullet points are fine… but I haven’t implemented styling to render nested bullet points yet.

NextJS 13

If you are failing to connect to notion, or the images from unsplash aren’t working then check your config file. In this case, I had to edit next.config.mjs

If you upload a file into your blog, Notion uses AWS S3 buckets to store these so you need to add that too. My region was us-west-2 but yours may differ.


images: {
    remotePatterns: [
        {
            protocol: 'https',
            hostname: 'www.notion.so',
            port: '',
            pathname: '/images/**',
        },
        {
            protocol: 'https',
            hostname: 'images.unsplash.com',
            port: '',
            pathname: '/**',
        },
        {
            protocol: 'https',
            hostname: 's3.us-west-2.amazonaws.com',
            port: '',
            pathname: '/**',
          }
        ]
    }

Conclusion

If you like notion, then it’s a fun and interesting exercise to get into setting up their API and using NotionSDK.

It gives you unlimited flexibility to render items as you want, but it does come at a cost, and that can’t be understated.

Next time I'd like to repeat this prototype using NextJS 14 and it's new app router.

If you have any questions, please feel free to get in touch.

How to use multiple fonts in NextJS

Brendan — Fri, 19 Jul 2024 14:47:57 +0000

Objective

Implement multiple fonts in your React, NextJS application.
Completion time: 5-10 minutes.

Breakdown

Let's Get Started

New Application

Follow the installation docs from NextJS.
Make sure you select 'yes' when asked if you want to install TailwindCSS.

npx create-next-app@latest

Existing application

Once you're up and running with a new, or existing application we need to do the following:

Install the packages
Import Google Fonts into the application
Update the tailwind config file
Use the font on the frontend

Install the packages

Install the @next/font package that allows us to access all of the Google Fonts out there. Using your preferred package manager: npm, bun, pnpm

There are hundreds of Google Fonts available to choose from, each with their own properties to adjust them to your liking.

npm install @next/font

Import Google Fonts

Import the package into your layout.tsx or _app.tsx file

// import
import {Cormorant, Nunito_Sans, Baskervville} from 'next/font/google'

// Create a font object, passing in properties. 
// Note the 'variable' property, it's needed inside tailwind.config
const fancyFont = Cormorant({
    weight: '400',
    subsets: ['latin'],
    variable: '--font-fancy',
});
const readingFont = Nunito_Sans({
    subsets: ['latin'],
    variable: '--font-reading',
});

const alternative = Baskervville({
    weight: '400',
    subsets: ['latin'],
    variable: '--font-alternative-syntax'
});

// pass the font values into the wrapper class to
// make them available throughout the entire application
// this can also go in the html or body elements if necessary
export default function MyApp({ Component, pageProps }) {
  return (
        <main className={`
                    ${fancyFont.variable} 
                    ${readingFont.variable} 
                    ${alternative.variable}`}>

            <Component {...pageProps} />
        </main>
  )
}

Configure `tailwind.config.ts`

Extend the theme property to include our new fonts.
In this section, the left side fancy, "alternative-syntax" can be called anything you want.
The left side is what you'll use in your Tailwind class to use the font
The contents of var() must match variable name defined in the _app.tsx or layout.tsx file where you initialised the NextFont object.

  //content...
    theme: {
        extend: {
            fontFamily: {
                fancy: ["var(--font-fancy)"],
                reading: ["var(--font-reading)"],
                "alternative-syntax": ["var(--font-alternative-syntax)"]
            },
        },

Use the font

Now that the font is installed, all that is left is to use it inside your react components by adding the class onto the HTML element.

<div className="text-black">
    <h1 className="font-fancy">I am the fancy font using Cormorant</h1>
    <p className="font-reading">Reading font using Nunito Sans</p>
    <p className="font-alternative-syntax">Baskerville font with alternative syntax.</p>
</div>

Result

Why Bother?

The simple act of adding a few different font stylings into your NextJS, React application can help elevate your websites design much more than you would expect.

As developers, we can sometimes focus too much on getting things to work (who doesn't love that feeling), we add finesse through abstraction or complexity, and sometimes - we forget to make our frontend look as pretty as the code that's behind it.

Hopefully now, you can add an additional layer of creativity into your designs.

How to create a contact form with EmailJS, Zod, ShadCN UI, TypeScript using React and NextJS.

Brendan — Tue, 16 Jul 2024 08:26:17 +0000

With any luck, there are enough frontend buzzwords in that title to make this an interesting post!

In this article, I will take you through the steps involved in creating a basic contact form that has been jazzed up with a few libraries that take away some of the pain during development, (and add some of their own challenges).

Breakdown

As the title suggests, we'll be using the following tools:

NextJS v14.
EmailJS
Zod
ShadCN UI (under the hood, this is using react-hook-form)
TypeScript

Assumptions

This article assumes you have already configured your application to use NextJS - with Typescript, TailwindCSS, Zod. If not, the links above all have docs on how to install and configure these tools

Additionally, you'll need an account with EmailJS. The fun part is that EmailJS offers a free teir version for their services so there's no reason not to!

Let's Get Started

Using your favourite package manager, let's get the following packages installed. In my case, I am using npm for simplicity.

npm install @emailjs/browser react-hook-form zod @hookform/resolvers

If you haven't already configured ShadCN UI, check out their docs here for NextJS applications. Get started with ShadCN.

Create the Contact Form component

From here it's more straight-forward as we'll use a lot of ShadCN and EmailJS out of the box code, with some minor tweaks to let them work together.

Install your ShadCN components

npx shadcn-ui@latest add form button input toast textarea

Create a `Contact.tsx` file in your application

Organise your imports

Gotcha, check the filepath for the ShadCN components matches your configuration.

"use client";

import { zodResolver } from "@hookform/resolvers/zod";
import { useForm } from "react-hook-form";
import React, { useRef } from "react";
import { z } from "zod";
import emailjs from "@emailjs/browser";
import { Button } from "~/components/ui/button";
import {
  Form,
  FormControl,
  FormField,
  FormItem,
  FormLabel,
  FormMessage,
} from "~/components/ui/form";
import { Input } from "~/components/ui/input";
import { useToast } from "~/components/ui/use-toast"; //optional
import { Textarea } from "~/components/ui/textarea";

Create the form schema with Zod

In most contact forms you'll want the persons name, email address, and their message.

//...imports
const FormSchema = z.object({
  username: z.string().min(2, {
    message: "Username must be at least 2 characters.",
  }),
  email: z.string().email("Invalid email address.").min(2, {
    message: "Email must be at least 2 characters.",
  }),
  message: z.string().min(10, {
    message: "Message should be at least 10 characters.",
  }),
});

Create a reusable component using `export`

On your site, you want to make it as easy as possible for people to get in contact with you, by exporting the component you can import it in various places throughout your website.

Gotcha: Make sure you pass in your own valid EmailJS Template ID, Service ID, and Public Key. Here I reference them via my .env file.

In this component, we will need to define the following:

const formRef
const form
const onSubmit

export const Contact = () => {

  // EmailJS needs the `ref` parameter in a form, ShadCN doesn't use 
  // this by default so we have to import it.
  const formRef = useRef<HTMLFormElement | null>(null);

  // configure Zod default values for the form
  const form = useForm<z.infer<typeof FormSchema>>({
    resolver: zodResolver(FormSchema),
    defaultValues: {
      username: "",
      email: "",
      message: "",
    },
  });
}

// Create the handler that connects to EmailJS.  
  const onSubmit = (data: z.infer<typeof FormSchema>) => {
    if (formRef.current) {
      emailjs
        .sendForm(
          env.NEXT_PUBLIC_EMAILJS_SERVICE_ID,
          env.NEXT_PUBLIC_EMAILJS_TEMPLATE_ID,
          formRef.current,
          {
            publicKey: env.NEXT_PUBLIC_EMAILJS_PUBLIC_KEY,
          },
        )
        .then(
          () => {
            form.reset(); //clear the fields after submission
          },
          (error) => {
            console.warn("FAILED...", JSON.stringify(error));
          },
        );
    }
  };
// ...the ShadCN form will go here.
} //end of Contact component

Create your ShadCN form

Now that all of your functions and variables are declared, you want to create the actual React component that renders onto the screen. For this, we'll use ShadCN's form that is react-hook-form under the hood.

With this, you'll now have a well formed, semantically correct Form provided by ShadCN, with client side validation, responsive design, and a host of other benefits.

//... functions and variables
  return (
    <>
      <Form {...form}>
        <form
          ref={formRef} //Required by EmailJS
          onSubmit={form.handleSubmit(onSubmit)}
          className="w-2/3 space-y-6">
          <FormField
            name="username"
            render={({ field }) => (
              <FormItem>
                <FormLabel className="text-lg">Name</FormLabel>
                <FormControl>
                  <Input
                    className="border-primary bg-white"
                    placeholder="Your Name"
                    {...field}
                  />
                </FormControl>
                <FormMessage className="text-xs text-red-600" />
              </FormItem>
            )}/>
          <FormField
            control={form.control}
            name="email"
            render={({ field }) => (
              <FormItem>
                <FormLabel className="text-lg">Email</FormLabel>
                <FormControl>
                  <Input
                    className="border-primary bg-white"
                    placeholder="Email Address"
                    {...field}
                  />
                </FormControl>
                <FormMessage className="text-xs text-red-600" />
              </FormItem>
            )}/>
          <FormField
            control={form.control}
            name="message"
            render={({ field }) => (
              <FormItem>
                <FormLabel className="text-lg">Message</FormLabel>
                <FormControl>
                  <Textarea
                    className="border-primary bg-white"
                    placeholder="Type your message here."
                    id="message"
                    {...field}
                  />
                </FormControl>
                <FormMessage className="text-xs text-red-600" />
              </FormItem>
            )}/>
          <Button
            type="submit"
            className="text-md text-white hover:bg-secondary">
            {/*<PaperPlane />*/}
            Send{" "}
          </Button>
        </form>
      </Form>
    </>
  );

Optional Bonus: Add a `Toast` notification

What nicer way to inform your visitors that your email has been sent, or has failed to send, than by adding a neat Toast notification to your onSubmit handler function.

For this, we'll be using the optional imports above inside the Contact.tsx component, notably:

npx shadcn-ui@latest add toast

Ensure you have imported:

import { useToast } from "~/components/ui/use-toast";

Inside your Contact component, desconstruct useToast

const { toast } = useToast();

Inside your onSubmit handler, add the toast when the email submission is successful, or when it fails, inside the then() clause.

        .then(
          () => {
            console.info('SUCCESS');
            toast({
              title: "Email sent.",
              description: `Thanks ${data.username}, I'll be in touch.`,
            });
            form.reset(); //clear the fields after submission
          },
          (error) => {
            toast({
              variant: "destructive",
              title: "Email failed to send.",
              description: `Please contact support if this continues.`,
            });
            console.warn("FAILED...", JSON.stringify(error));
          },
        );

Lastly, Toast needs to be referenced inside your layout.tsx - if you're not seeing the toast notification on your screen, this is likely the cause.

import { Toaster } from "~/components/ui/toaster";
//...
    <html lang="en">
      <body>
          <Toaster /> // Reference toaster
      </body>
    </html>

Conclusion

And there you have it, with a few tweaks of the default code provided by EmailJS and ShadCN's Form component, you are up and running.

I have provided the entire code here in my GitHub Gist

If you have any thoughts, requests, or questions - let me know. Or, if you would like a complete guide from setting up a new project with all of these tools configured - leave a comment below.

Forem: Brendan

Build a tool to understand your companys internal language with SanityCMS

Purpose

Preview

How It's Built

Excel Parsing

SanityCMS

How It's Configured

Find out more

Using Notion as a CMS and create a personal blog with React

Final Product

Prerequisites

Tech Stack

Technologies

Getting Started

Expected File Structure

The Code

lib/notion.ts

pages/Blog.tsx

posts/[id].tsx

Making it all TypeScripty

Constraints (How janky is it?)

Images

Block Types

NextJS 13

Conclusion

How to use multiple fonts in NextJS

Objective

Breakdown

Let's Get Started

New Application

Existing application

Install the packages

Import Google Fonts

Configure tailwind.config.ts

Use the font

Result

Why Bother?

How to create a contact form with EmailJS, Zod, ShadCN UI, TypeScript using React and NextJS.

Breakdown

Assumptions

Let's Get Started

Create the Contact Form component

Install your ShadCN components

Create a Contact.tsx file in your application

Create the form schema with Zod

Create a reusable component using export

Create your ShadCN form

Optional Bonus: Add a Toast notification

Conclusion

`lib/notion.ts`

`pages/Blog.tsx`

`posts/[id].tsx`

Configure `tailwind.config.ts`

Create a `Contact.tsx` file in your application

Create a reusable component using `export`

Optional Bonus: Add a `Toast` notification