#Full disclosure this blog does have a bit of "Product placement" in it with an open-source package I wrote. Other than that this is one way to implement client-side GA4 analytics.#

Why add google analytics to a web App?

1. Error tracking and analytics

2. Discover what works and what doesn't

3. Discover website usage patterns to better inform feature development or refactors

4. Understand the cost of features against how often they are used

5. Justify further spending on new features

6. For anything that you want to measure, you can use google analytics for this.

Add google analytics to a web App?

Let's start by adding a way for collecting data to our website, and then deciding which data we want to capture. In this scenario, we are interested to know who is clicking on the register button and who is clicking the signing in button.

First, we will install a dependency #react-marketing-tools(RMT) this will provide us with a way to capture data and send it to GA4 via our GTM. Also for convenience, I recommend using this dependency react-gtm-module for adding GTM and the 👍dataLayer to your project, or you could do it manually if you prefer.

React Marketing Tools Demo

This is an example of a very simple implementation, some of this we will breakdown and explain further, just continue reading 🙃

https://codepen.io/roryfn/pen/OJBGvMG

The above demo implementation doesn't use a react Context/Provider so you have the option of using this package outside of react.
By clicking register or login and then showing dataLayer you can see the key/values that go to your GA4 analytics.
To view the Context/Provider implementation checkout the example in the
GitHub repo README.md.

React Marketing Tools global config

const TOKENS = { // all TOKENS are optional
  /*
    If withServerLocationInfo is true you must supply IP_INFO_TOKEN token.
  */
  IP_INFO_TOKEN: 'SOME_TOKEN',
  /* 
    If analyticsType = analyticsPlatform.GOOGLE the below tokens must be supplied.
  */
  GA4_PUBLIC_API_SECRET: 'SOME_TOKEN',
  GA4_PUBLIC_MEASUREMENT_ID: 'SOME_TOKEN',
}

const analyticsConfig = {
  appName: "my-awesome-app",
  appSessionCookieName: "AWESOME_APP",
  eventActionPrefix: {},
  globalEventActionList: {
    // this will extend the default values of globalEventActionList
    LOGIN: "LOGIN",
    REGISTER: "REGISTER",
    UNAUTHENTICATED: "UNAUTHENTICATED",
    AUTHENTICATED: "AUTHENTICATED"
  },
/*
   * If you dont add the user data keys to this includeUserKeys
   * the values will be adde to the journeyProps not the userProps
*/
  includeUserKeys: ["email"],
/*
   * showMissingUserAttributesInConsole if true will console.log in the browser console user data that does not match the includeUserKeys array
*/
  showMissingUserAttributesInConsole: false,
  TOKENS,
  withDeviceInfo: true,
  withServerLocationInfo: false
};

Note: withDeviceInfo, withServerLocationInfo use the following dependencies to get the respective data. These are great tools for making your life much easier!

1. withDeviceInfo - device-detector-js

2. withServerLocationInfo - https://ipinfo.io

React Marketing Tools event config

      const eventNameInfo = {
/*
   * eventName is optional and will be change to "REGISTER_ACCOUNT"
   * this is the event name you will add to your Tag in GTM
   * If this is not passed in the event name will be a combination of actionPrefix & globalAppEvent e.g. I_REGISTER
*/
        eventName: 'register account',
/*
   * actionPrefix this will be added to the eventName
   * this helps to quickly identify the type of action in GTM & GA4
   * "I_REGISTER_ACCOUNT"
*/ 
        actionPrefix: "I", // INTERACTION | J: JOURNEY
/*
   * globalAppEvent here the key/values added to "globalEventActionList" are used
*/ 
        globalAppEvent: "REGISTER",
/*
   * previousGlobalAppEvent this is helpful for building user journeys         with the data, 
   * It is not always available or needed therefore it is optional
*/ 
        previousGlobalAppEvent: "UNAUTHENTICATED"
      };

Google Tag Manager

Now we set up our GTM with all the events, triggers and variables we want to collect.

There are any number of ways you can set up your GTM. I will show you a way that I prefer, it helps me manage a dev & prod environment that way I don't pollute my prod data with any testing or dev data.

Below is a snapshot of things we will cover in this section and some of the terms that will be used.

• Google Tag Manager(GTM)

• Versions/Workspace

• Live, Latest (aka production)

• dev

• Tags

• Triggers

• Variables & Folders

So first sign up to GTM with the Google account you want to use to manage GTM. Once we have signed in to GTM we will have access to the values below.

id: string, // GTM-ABC....
gtm_auth: string, // Qr08F...
preview: string, // env-1 - This value is what we use to define which environment we are using.

If you don't see these right away you can find them under Admin > Install Google Tag Manager This is also where you will find the code needed to manually add GTM/dataLayer to your App if you do not want to use react-gtm-module.

Add TagManager

Now we have these values we can add GTM and the dataLayer to our website with react-gtm-module.

import TagManager from 'react-gtm-module'

// Usually these values can be added to your .env
const tagManagerArgs = {
   gtmId: "GTM-ABC",
   dataLayerName: "dataLayer",
   auth: "Qr08F...",
   preview: "env-1"
};

useEffect(function initiateGoogleTagManager() {
  TagManager.initialize(tagManagerArgs);
}, []);

If you have set up your data collection with #react-marketing-tools(RMT) and you have completed the above initialisation of GTM, at this point you will be able to see the data in your dataLayer in the console.
Either use the built-in logging from RMT or just open the console type dataLayer and hit enter you will see something like this.

At this point, I recommend taking a little time to understand the parts of this dataLayer and understand where most of the data comes from.

TLDR; It is a combination of the analyticsConfig you passed to the buildConfig from RMT, also what you added to each event data object trackingData, in this case, the events of Register and Login.
Check-out the handleButtonClick from the above demo.

NOTE:

• All journeyProps variables will be CAPITALISED. This point is important to remember when we come to assign the dataLayer values to new GTM variables.

• At this point none of the data that is in the dataLayer is going to go to GA4 via GTM because we have not configured GTM yet.

Google Tag Manager Setup

We are going to start from the bottom up to setup our GTM.

1. Variables & Folders

2. Triggers

3. Tags

Variables ✅

We are setting up the variables based on what you might use with RMT, but this setup can be used for any implementation of GTM. The variables will be added to your Tags.

Built-In Variables

User-Defined Variables

"constant" variables in this case are used as a fallback to convert any other user-defined values to an acceptable type. This is a "helper variable" in case the parsing of the data to a JSON object ever fails.
I decided to use these "helper variables" because it can take a lot of time to figure out why a variable is not appearing in the payload for GA4, at least with this fallback I can see the variable, and I can see it has no value "" or a "boolean" value and work directly on fixing it.

Example: You can see below we take the value from the dataLayer by assigning userProps.client_id to the GTM client_id variable.

Folders ✅

This is one example of how to organise your variables, you can arrange the folders however you like.

Triggers ✅

1. Give your trigger a name and add it to a folder

2. Add the Event Name, the Trigger event name must match the name you add to the dataLayer. The event name can also use regex which can be useful for event names that have a key/s to match on.
   I will not cover regex this time. A quick simple example in this case could be I_*_ACCOUNT the * will Trigger both REGISTER & LOGIN.

3. That is it for Triggers.

Tags ✅

This is where it all comes together! Tags house your variables and triggers consolidating the event and data that is sent to Google Analytics.

Here the Parameter Name is what we will see in Google Analytics 4, and the value is the variable reassignment as seen above in the "Variables ✅" section.

This is where we decide what data should be assigned to what trigger/events.
If we want GTM can act as a filter, this means what is sent to GTM from React Marketing Tools does not always have to be sent through to GA4.

Versions ✅

The version is very important because we don't want to mix dev data with production data. You will get one environment setup automatically env-1.

To add a new env we need to go to Admin > Environments and then click the button in the top right "New".

1. Give the env a name. Optionally add a description

2. Enable debugging

3. Add a destination URL; we will add a dev environment, so you can add something like http://localhost:3000

Workspace ✅

Here is where we can check our setup before publishing to the respective environments.

NOTE: "Publish to Environment", initially I will publish to production env-1 and then make a trivial change to republish to my development environment env-3.

That is it!
We have now passed data from our App, through to Google Tag Manager, then on to Google Analytics 4. From here I will leave it to you.

If you want to check the data is arriving go to your production site open GA4 and go to Reports > Real Time. You should see 1 or more visitors and here you can inspect the events, variables and data that arrive.

Thanks for reading, if you have any questions or comments, please leave them below. ✌️

Okay so maybe there is nothing "cool" about redux, but I think it is cool how you can use vanilla redux, createReducer and createSlice all in the same project if I want or if I have to.

Why use redux?

Well for me one thing I enjoy is the "separation of concerns"(SC) when managing business logic and app state.
SC; is a case by case requirement, if not given a good amount of thought, it will mess up a project and have the reverse effect on Developer Experience(DX).

Another thing that can have an undesired effect on DX is redux, so make sure you really need it for your next incomplete side project 😅🫠🤣
If you decide "Yes I need it" then use what I am sharing below to get the most out of it, or at least to get things moving.

redux folder structure for some developers might go something like this.

- redux
    - helpers
        # hooks.ts
        # reduxActions.ts
    - middleware
        # logger.ts
    - reducers
        # menuReducer.ts
   # store.ts

Vanilla Redux

Actions

export const EVENT_MAIN_MENU_ACTIVE = 'EVENT_MAIN_MENU_ACTIVE'
export const EVENT_MAIN_MENU_HIDE = 'EVENT_MAIN_MENU_HIDE'

Reducer

Yes... The warmth of a familiar bit of code!!

// mainMenuReducer.ts
import {
  EVENT_MAIN_MENU_ACTIVE,
  EVENT_MAIN_MENU_HIDE,
} from '../../helpers/reduxActions'

export type MenuStoreState = {
  menu: MenuState
}

export type MenuState = {
  mainMenuVisible: boolean
}

export const menuDefaultState: MenuState = {
  mainMenuVisible: false,
}

export default (
  state: MenuState = menuDefaultState,
  action: { type: string },
): MenuState => {
  switch (action.type) {
    case EVENT_MAIN_MENU_ACTIVE: {
      return {
        ...state,
        mainMenuVisible: true,
      }
    }
    case EVENT_MAIN_MENU_HIDE: {
      return {
        ...state,
        mainMenuVisible: false,
      }
    }
    default: {
      return {
        ...state,
      }
    }
  }
}

Usage

import { useCallback, MouseEvent } from 'react'
import { useDispatch, useSelector } from 'react-redux'
import {
  EVENT_MAIN_MENU_ACTIVE,
  EVENT_MAIN_MENU_HIDE,
} from '../../redux/helpers/actionTypes'
import { MenuStoreState } from '../../redux/reducers/menuReducer'

const useMainMenu = () => {
  const showMainMenu = useSelector<MenuStoreState>(
    state => state.menu.mainMenuVisible,
  ) as boolean

  const dispatch = useDispatch()

  const handleMainMenuClick = useCallback(
    async (event: MouseEvent<HTMLButtonElement>) => {
      event.preventDefault()
      event.stopPropagation()

      dispatch({
        showMainMenu,
        type: !showMainMenu ? EVENT_MAIN_MENU_ACTIVE : EVENT_MAIN_MENU_HIDE,
      })
    },
    [showMainMenu, dispatch],
  )
...

And that is it, that is the code to manage opening and closing a drawer that will contain the main menu of your website, usually on a mobile device.

Yes, we still need to add a logger.ts & store.ts, which is coming later.

createReducer redux

Nothing like using a well-formed hook to manage app state!

Reducer, Initial state and Actions.

All are nicely co-located.

// authedUserReducer.ts
import { createAction, createReducer, PayloadAction } from '@reduxjs/toolkit'

type UserState = {
  user: User | undefined
}

export const initialState: UserState = {
  user: undefined,
}
// In this example this is also known as reduxActions.ts
export const userData = createAction('USER_DATA', (user: User) => {
  return { payload: user }
})

const authedUserReducer = createReducer(initialState, builder => {
  builder.addCase(
    userData,
    (state, action) => {
      // payload has types inferred because of the create action!
      state.user = action.payload
    },
  )
})

export default authedUserReducer

Something pretty cool, in the above code inside the (state, action) function is that the data is mutable aka; state: WritableDraft<UserState> Do what you want with the data inside this function and no need to ...spread the data or return anything that is all taken care of 👍

Usage

import { useEffect, useReducer } from 'react'
import userReducer, { userData } from '../../redux/reducers/userReducer'

type UserData = {
  user: User | undefined
}

const useGetUserData = (): UserData => {
  const [state, dispatch] = useReducer(
    authedUserReducer,
    authedUserReducer.getInitialState(),
  )

  useEffect(
    function getUserDetailsFromAuthOrSession() {
      const setUserSession = async () => {
        const user: User = await getUser()

        dispatch(userData(user))
      }

      setUserSession()
    },
    [dispatch],
  )

  return {
    user: state.user,
  }
}

export default useGetUserData

Yep that's it, nothing else to write!

createSlice redux

createSlice has quite a bit of boilerplate code, but code usage is reduced (sorry that is unintended that pun...), so it depends on where you want to write your code, more code in usage or more boilerplate pick your poison.
createSlice just like createReducer nicely packaged in the same place, if that's what you like, easy to see all the code and the moving parts. It is also nice to have all the reducers in one place to see how it all works together.

Note:: pageDataReducer.ts <- This name is misleading but rather than create another folder for slices I named it as a reducer, whatever you prefer in this case.

Slice

// pageDataReducer.ts
import { createAsyncThunk, createSlice, PayloadAction } from '@reduxjs/toolkit'
import { optimisticLoadArrayResource } from '../../../utils/helpers/staticAssets'
import { Subset } from '../../../utils/valueCheckers'

type PageState = {
  resources: Subset<Resource>[]
}

const initialState: PageState = { resources: [] }

export const fetchPageData = createAsyncThunk(
  'page/fetchResources',
  async (): Promise<Subset<Resource>[]> => {
    // Make the backend call.
    // NOTE:: This will run when user is unauthed but only an empty array will be returned,
    // This is why we have the optimisticLoadArrayResource fallback here and when the thunk fetch is "pending"
    const response = await getResources(ResourceTypes.resource)

    return response ?? optimisticLoadArrayResource
  },
)

export const createResource = (
  resources: Subset<Resource>[],
): Subset<Resource> => {
// This is a great place to cherry pick what you need and define a new type.
  return resources
}

const pageDataSlice = createSlice({
  name: 'page', // <- this is the name used in the store.ts
  initialState,
  reducers: {
    createPageData: (state, action: PayloadAction<Subset<Resource>>) => {
      const newResource = createResource(action.payload)
      state.resources = [newResource, ...state.resources]
    },
    updatePageData: (state, action: PayloadAction<Subset<Resource>>) => {
      const newResource = createResource(action.payload)
      const index = state.resources.findIndex(
        resource => resource.id === newResource.id,
      )
      state.resources.splice(index, 1)

      state.resources = [newResource, ...state.resources]
    },
    deletePageData: (state, action: PayloadAction<ResourceId>) => {
      const deleteId = action.payload
      const newResourceList = state.resources.filter(
        resource => resource.id !== deleteId,
      )

      state.resources = [...newResourceList]
    },
  },
  extraReducers: builder => {
    builder.addCase(fetchPageData.pending, state => {
      state.resources = optimisticLoadArrayResource
    })
    builder.addCase(
      fetchPageData.fulfilled,
      (state, action: PayloadAction<Subset<Resource>[]>) => {
        const resources = action.payload
        state.resources = resources
      },
    )
  },
})

export const pageDataReducer = pageDataSlice.reducer
export const { createPageData, updatePageData, deletePageData } =
  pageDataSlice.actions

export default pageDataSlice

What are some great things about createReducer & createSlice ?

• First of all and most importantly you get inferred types!!
  "correctly infer the action type in the reducer based on the provided action creator. It's particularly useful for working with actions produced by createAction and createAsyncThunk"

• You can add extraReducers these functions let you interact or work with actions outside of the slice that houses the regular reducers.
  In the above example the actions for the fetchPageData fetching statuses are handled with extraReducers
  "One of the key concepts of Redux is that each slice reducer "owns" its slice of state, and that many slice reducers can independently respond to the same action type. extraReducers allows createSlice to respond to other action types besides the types it has generated."

• Co-location of code export what you want as you need it, reusability

Usage

The good old "wrapper" hook in a hook...

import { TypedUseSelectorHook, useDispatch, useSelector } from 'react-redux'
import { ApplicationDispatch, ApplicationState } from '../store'

export const useReduxUseSelector: TypedUseSelectorHook<ApplicationState> =
  useSelector

export const useReduxUseDispatch: () => ApplicationDispatch = useDispatch

Now just dispatch your reducers in functions or as needed in any files you need to create, read, update, or delete data.

  const dispatch = useReduxUseDispatch()

  dispatch(createPageData(response))
  dispatch(fetchPageData())
  dispatch(updatePageData({ ...currentData, newData }))
  dispatch(deletePageData(payload.deleteNodeId))

For me, the above usage is just the same as importing and using a hook like useSWR or reactQuery throughout your code. One thing that can be done here, you can't do with useSWR or reactQuery hooks are fetching data before the app has mounted. 👇

import { fetchPageData } from './redux/reducers/pageDataReducer'

const container = document.getElementById('root')

store.dispatch(fetchPageData())

// eslint-disable-next-line @typescript-eslint/no-non-null-assertion
const root = createRoot(container!)

root.render(
  <StrictMode>
    <Provider store={store}>
      <ErrorBoundary>
        <App />
      </ErrorBoundary>
    </Provider>
  </StrictMode>,
)

Finally the Logger and the Store.

Logger

Pretty standard right not much to say here, also I am pretty sure there is a built-in option for this in the toolkit, but I am not sure, I'll leave you to find that out 🙌

import { Middleware, MiddlewareAPI, Dispatch } from 'redux'

const loggerMiddleware: Middleware =
  ({ getState }: MiddlewareAPI) =>
  // eslint-disable-next-line consistent-return
  (next: Dispatch) =>
  action => {
    const { type } = action

    if (process.env.NODE_ENV === 'development') {
      console.group(
        '🚀 ~ file: logger.js ~ line 3 ~ logger ~ action.type',
        type,
      )
      console.info(
        '🚀 ~ file: logger.ts ~ line 13 ~ logger -> will dispatch',
        action,
      )

      const result = next(action)
      console.info(
        '🚀 ~ file: logger.js ~ line 8 ~ logger ~ store.getState() -> state after dispatch',
        getState(),
      )
      console.groupEnd()

      // This will likely be the action itself, unless
      // a middleware further in chain changed it.
      return result
    } else {
      const result = next(action)
      return result
    }
  }

export default loggerMiddleware

Store

import { configureStore } from '@reduxjs/toolkit'
import { applyMiddleware } from 'redux'
import thunkMiddleware from 'redux-thunk'
import loggerMiddleware from './middleware/logger'

import { pageDataReducer } from './reducers/pageDataReducer'
import authedUserReducer from './reducers/authedUserReducer'
import menuReducer from './reducers/menuReducer'

const middlewareEnhancer = applyMiddleware(loggerMiddleware, thunkMiddleware)

const store = configureStore({
  devTools: process.env.NODE_ENV !== 'production',
  reducer: {
    menu: menuReducer, // vanilla redux
    page: pageDataReducer, // createSlice redux
    auth: userReducer, // createReducer redux
  },
  enhancers: [middlewareEnhancer],
})

// These below types are a big part of why we have the custom hook wrappers useReduxUseSelector & useReduxUseDispatch
export type ApplicationState = ReturnType<typeof store.getState>
export type ApplicationDispatch = typeof store.dispatch

export default store

Signoff

That is it! This app is now using 3 different implementations of redux and you wouldn't even know without looking at the code 😅.

Redux is a powerful tool for managing app state in complex applications. It provides a structured approach that makes it easier to reason about.

Thank you for taking the time to read this post. If you have any questions or comments, please feel free to leave them below.

SOLID

To help you sleep easier 😅🤯😎🫠 this code is S.O.L.I.D

1. Single Responsibility Principle (SRP): Each function and module has a single responsibility and does not take on additional responsibilities that would violate this principle.

2. Open/Closed Principle (OCP): The code is open for extension but closed for modification. It achieves this by using abstraction (e.g., asyncThunkAction) to separate different concerns, allowing the code to be extensible without modifying existing code.

3. Liskov Substitution Principle (LSP): The code implements the LSP by using interfaces (e.g., PayloadAction) to ensure that derived classes can be substituted for their base classes without affecting the correctness of the program.

4. Interface Segregation Principle (ISP): The code follows the ISP by using interfaces to define only what is needed for a particular module, preventing unnecessary coupling between modules.

5. Dependency Inversion Principle (DIP): The code follows the DIP by depending on abstractions (e.g., optimisticLoadArrayResource) instead of concrete implementations, allowing for greater flexibility in the implementation of the code.

ℹ️ I recently did some work on this for a project I am working on, and I don't know if it was just me, but it was not the most enjoyable experience trying to figure out the correct configuration for a frontend file upload to AWS s3 bucket.
I wanted to share my solution, hopefully, it can help others 😃.

I also want to acknowledge that there are plenty of dependencies available to do all this work for you around file uploads, but considering the file upload API doesn't change very often, it might be a better option to manage this yourself.

AWS s3 bucket setup 📐

Setting up an account and logging in as a root user I will leave it up to you to figure out (I can answer questions about that setup if a comment is left about it 👍).
Once logged in, add s3 to the search in the top left, beside the services waffle menu, the top result "S3" will be what you click on. (It is useful to click on the star)

Now you want to create a bucket

I have left all the suggested default settings as they are, except for the "Block Public Access setting for this bucket" this setting I have deactivated and consented to.

Now scroll down to the bottom and click "Create Bucket".
That covers the bucket creation config, I am sure per your requirements, you can make the changes you need. For this example, default settings are good enough.

Bucket Permissions 🔐

You should see your bucket in the "Buckets" table list now, click on it, and now click on the "Permissions" tab.

update the following sections to what you see below;

Bucket Policy

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "PublicListGet",
            "Effect": "Allow",
            "Principal": "*",
            "Action": [
                "s3:List*", // could be "s3:ListBucket"
                "s3:Get*" // could be "s3:GetObject"
            ],
            "Resource": "arn:aws:s3:::view-my-property-au"
        },
        {
            "Sid": "PutFiles",
            "Effect": "Allow",
            "Principal": "*",
            "Action": [
                "s3:PutObject",
                "s3:GetObject",
                "s3:DeleteObject"
            ],
            "Resource": "arn:aws:s3:::view-my-property-au/*"
        }
    ]
}

In the above policy, we have two Statements.

1. The first is for allowing access to view our images, either a list or individual images.

2. The second is allowing access to some CRUD actions see the prefix for which actions we are allowing.

3. The Resource each of the actions has an effect on is slightly different, this is a small distinction to show in this case, that you cannot PUT files without a name or subfolder, you cannot delete all files in a bucket and you can GET individual files.

4. The Bucket Policy Elements each has a description that can better provide you with some context on the JSON structure: Policy Language Overview & Here

Note: There are no "Conditions" for the Statement "Actions".
Conditional Actions can only be applied to one action, here we have an array of actions. In the case of Delete & Put it is safe to assume that these actions would only be accessible after authentication, and this authentication would only grant access to the images the authed user owns, therefore it is safe to leave these actions without conditions on the s3 bucket. (That is my assumption, happy to hear otherwise, or of a better option).

Cross-origin resource sharing (CORS)

As stated in the cors section of the bucket; "The CORS configuration, written in JSON, defines a way for client web applications that are loaded in one domain to interact with resources in a different domain". This section feels pretty straightforward to me, but please leave a comment if you would like more info, or see here for some examples

[
    {
        "AllowedHeaders": [
            "*" // could be defined if needed
        ],
        "AllowedMethods": [
            "HEAD",
            "PUT",
            "POST",
            "GET"
        ],
        "AllowedOrigins": [
            "*" // should be defined once in production
        ],
        "ExposeHeaders": [
            "ETag",
            "x-amz-meta-custom-header" // not always needed
        ]
    }
]

AWS s3 client setup

import { S3Client } from '@aws-sdk/client-s3'

export const s3Client = new S3Client({
  region: process.env.REGION,
  credentials: {
    accessKeyId: process.env.ACCESS_KEY,
    secretAccessKey: process.env.SECRET_KEY,
  },
})

• Install dependency

  • yarn add @aws-sdk/client-s3

  • npm install @aws-sdk/client-s3

• Add your keys to the .env file.

  (see below how to set up a user and get these keys)

  • ACCESS_KEY

  • SECRET_KEY

IAM user (Programmatic) setup 🙈

• The following steps are how you can get the above KEYs

  • Add iam to the search in the top left, beside the services waffle menu, the top result "IAM" will be what you click on.

  • In the menu on the left click "users"

  • Click "Add users"

  • Add the User name and select "Access key - Programmatic access"

    • More info reference: IAM users

• Go to the next section, section 2

• Here you can either create a group with the correct permissions or add the correct permissions direct to the user

  • If you have created a group with the correct permissions select it, Or

  • Search for AmazonS3FullAccess and select it to add to the user

    • If you have not set up a group you will only see a place to search for permissions. What you see will look similar to the image just below.

  • Then go to the next optional step.

At the end of this setup, you will be presented with the Access key ID and the Secret access key as listed above, copy them into your .env, .env.local...

Drag&Drop upload components 🫳

UploadFile usage

<UploadFile<ListingDetailsData> // add type to make UploadFile more generic
  {...{
    formDataFields, // some state that is used for adding files to subfolder
    currentFiles, // image urls
    setCurrentFiles, // state setter for image urls
    hasNewFiles, // optional boolean used for updating loader and or user feedback
    setHasNewFiles, // state setter for hasNewFiles boolean
  }}
/>

UploadFile component 🗂️

import React, { useState, Dispatch, SetStateAction } from 'react'
import dynamic from 'next/dynamic'
import { endPoint } from '../../utils/endPoint'
import { handleUploadFiles } from './fileUploadFunction'
import imageResize from './imageResize'
import useWindowSizeTracker from '../../hooks/useWindowSizeTracker' // a hook that keeps track of the window dimensions. Window size tracking could be done with TailwindCSS.

const FlexGridLayout = dynamic(() => import('../common/flexGridLayout')) // just a wrapper for flex which can be used as is or passed some TailwindCSS class styling.
const DragAndDrop = dynamic(() => import('./dragAndDrop'))
const BASE_URL = process.env.BACKEND_URL || endPoint

interface UploadFileProps<T> {
  formDataFields: T
  currentFiles: Record<string, string>[] // TODO:: should be better typed
  setCurrentFiles?: Dispatch<SetStateAction<Record<string, string>[]>>
  hasNewFiles?: boolean
  setHasNewFiles?: Dispatch<SetStateAction<boolean>>
}

const UploadFile = <T,>({
  formDataFields,
  currentFiles,
  setCurrentFiles,
  // hasNewFiles,
  // setHasNewFiles,
}: UploadFileProps<T>) => {
  // ** OPTIONAL STATE you can pass to DragAndDrop if needed. **
  // uncomment and pass to DragAndDrop if you want to use.

  // const [error, setError] = useState<unknown>(null)
  // const [uploadSize, setUploadSize] = useState<string>('0')
  // const [uploadFiles, setUploadFiles] = useState<Record<string, string>>({})
  // const [uploadProgress, setUploadProgress] = useState<string>('')
  // const [uploadRunning, setUploadRunning] = useState<boolean>(false)

  // TODO:: Maybe just do all of this with TailwindCSS
  const { windowSize } = useWindowSizeTracker() 

  const handleDrop = (files: FileList) => {
    for (let i = 0; i < files.length; i += 1) {
      const file = files[i]
      if (!file.name) {
        return
      }

      const fileSize = file.size
      // TODO:: add a function for file size check handling
      const fileSizeCheck = Math.round(fileSize / 1024)

      if (fileSizeCheck < 1024) {
        handleUploadFiles<T>(
          file,
          `${BASE_URL}/s3-upload`,
          formDataFields,
        ).then(response => {
          setCurrentFiles(prevState => [...prevState, { imageUrl: response }])
        })
      } else {
        const image = imageResize<T>(file, formDataFields)

        setCurrentFiles(prevState => [...prevState, { imageUrl: image.url }])
      }
    }
  }

  return (
    <>
      <div className="w-full h-full flex text-left flex-col px-4">
        <DragAndDrop
          {...{
            windowSize,
            handleDrop,
          }}
        >
          <FlexGridLayout
            childContainerClass="w-12"
            containerClass="w-full absolute h-28 top-52 left-1/2 transform -translate-x-1/2 flex flex-wrap items-center overflow-y-scroll mb-4 space-x-2 z-50"
          >
            {currentFiles?.length > 0 &&
              currentFiles.map(({ imageUrl }: Record<string, string>) => {
                return (
                  <img
                    src={imageUrl}
                    key={imageUrl}
                    alt="upload-preview-image"
                    className="w-full object-contain rounded"
                  />
                )
              })}
          </FlexGridLayout>
        </DragAndDrop>
      </div>
    </>
  )
}

export default UploadFile

• FileList is an object but has some iterator properties like length. This means you will have to use the synchronous OG for loop 👍

• fileSizeCheck here we want to know if each image is greater than 1MB or not if so we will resize it to be smaller.

• handleUploadFiles<T>

  • file = image file

  • `${BASE_URL}/s3-upload` = path to Nextjs API handler

  • formDataFields = object with some state in it for constructing an image path in s3 bucket. (or whatever you need it for)

  • imageResize<T> uses the handleUploadFiles<T> function under the hood, once you have finished resizing your image the same args are passed to the handleUploadFiles<T>.

  • handleUploadFiles<T> expects a <File> type not a base64string, but you can change this if you prefer.

DragAndDrop component

import React, { useState, useEffect, useRef, ReactNode } from 'react'
import ActiveAnimation from '../../activeAnimation' // just a loader indicating to user image is being uploaded
import useEventListener from '../../../hooks/useEventListener'
import { WindowSizeTracker } from '../../../hooks/useWindowSizeTracker'

type DragAndDropProps = {
  children: ReactNode // This could be made optional children?:
  windowSize: WindowSizeTracker // { width: number, height: number }
  handleDrop: (fileList: FileList) => void
  uploadSize?: string
  uploadRunning?: boolean
  uploadProgress?: string
}

const DragAndDrop = ({
  children,
  handleDrop,
  uploadProgress,
  uploadRunning,
  uploadSize,
  windowSize, 
}: DragAndDropProps) => {
  const [dragging, setDragging] = useState<boolean>(false) // this state is used to provide user with feedback on dragging "safe" area.

  const dropRef = useRef<HTMLDivElement>(null)
  const selectRef = useRef<HTMLInputElement>(null)

  const handleDrag = (event: DragEvent) => {
    event.preventDefault()
    event.stopPropagation() // stops the event from being propagated through parent and child elements. So we can do what we want!
  }

  const handleDragIn = (event: DragEvent) => {
    event.preventDefault()
    event.stopPropagation()

    // conditional chaining can be used here if you prefer
    // event.dataTransfer?.items?.length > 0
    if (
      event.dataTransfer !== undefined &&
      event.dataTransfer.items &&
      event.dataTransfer.items.length > 0
    ) {
      setDragging(true) // TODO::consider a better name for this state
    }
  }

  const handleDragOut = (event: DragEvent) => {
    event.preventDefault()
    event.stopPropagation()

    setDragging(false)
  }

  const handleDropItem = (event: DragEvent) => {
    event.preventDefault()
    event.stopPropagation()
    const target = event.target as HTMLInputElement


    if (
      event.dataTransfer === undefined &&
      target.files &&
      target.files.length > 0
    ) {
      const fileList: FileList = target.files
      handleDrop(fileList)
    } else if (
      event.dataTransfer !== undefined &&
      event.dataTransfer.files &&
      event.dataTransfer.files.length > 0
    ) {
      handleDrop(event.dataTransfer.files)
    }
  }

  useEventListener('dragenter', handleDragIn, dropRef)
  useEventListener('dragleave', handleDragOut, dropRef)
  useEventListener('dragover', handleDrag, dropRef)
  useEventListener('drop', handleDropItem, dropRef)
  useEventListener('change', handleDropItem, selectRef)

  return (
    <div className="top-0 w-full h-80 flex relative" ref={dropRef}>
      <div className="h-full right-0 bottom-0 left-0 text-center absolute border-dashed border-2 border-gray-800 z-40 bg-gray-100">
        {dragging && !uploadProgress && (
          <div className="top-1/2 text-theme-grey text-4xl right-0 left-0 text-center absolute">
            <div>
              drop here
              <span
                role="img"
                className="ml-2"
                aria-label="Beaming Face with Smiling Eyes"
              >
                😁
              </span>
            </div>
          </div>
        )}
        {!dragging && !uploadProgress ? (
          <div className="top-1/2 text-theme-grey text-4xl right-0 left-0 text-center absolute">
            Drag and Drop
          </div>
        ) : (
          uploadProgress && (
            <div className="top-1/2 text-theme-grey text-4xl right-0 left-0 text-center absolute">
              {uploadProgress}
              {uploadSize && (
                <div>Error: image/s must be below 1Mb or 1028Kb in size</div>
              )}
              {uploadRunning && (
                <ActiveAnimation active="" backgroundColour="" />
              )}
            </div>
          )
        )}
        <label
          htmlFor="file-upload"
          className="flex flex-row items-center mt-16 mx-auto w-32 h-16 bg-contrast-colour hover:bg-gray-500 active:bg-gray-500 text-center text-white border border-1 border-gray-200 border-opacity-10 font-base rounded-lg cursor-pointer"
        >
          <span className="w-full text-center">
            {windowSize.width >= 800 ? 'Upload' : 'Take photo'}
          </span>
          <input
            multiple
            type="file"
            id="file-upload"
            accept="image/*"
            className="hidden"
            ref={selectRef}
          />
        </label>
      </div>
      {children}
    </div>
  )
}

export default DragAndDrop

• dragging state is used to indicate to the user they can drop the files in the "safe" area.

• target.files Vs event.dataTransfer.files see this StackOverflow discussion

• handleDrop is a prop passed down to handle uploading to s3 bucket

• useEventListener see Add custom context menu to your website with React & TypeScript for an example of this hook

• windowSize.width is used to show different text when DragAndDrop is being used on a mobile,

• all event listeners are listening on the respective ref

• input type file takes care of uploading on mobile device and the native mobile image select or image capture will take over in this case

  • We have limited the input to any image/* type, this is untested with Apple's image type HEIC

  • Must be selected from the album, this includes capturing images with the camera

    • <input type="file" accept="image/*">

  • Must be captured from the camera, this is only allowing you to capture images with the camera no photo album access.

    • <input type="file" accept="image/*" capture="">

  • The input is hidden with a htmlFor reference on the label so we can customize the style on the browser's default "Browse..." input. The selectRef handles the onChange functionality for us.

  • children in this case is just a thumbnail preview of all uploaded images.

Before dragging

After dragging

After the image is uploaded to the s3 bucket

The handleUploadFiles function

import { singlePostRequest } from '../../pages/api/requests' // just a wrapper for axios.post()
import { convertGenericTypeToListingDetails } from '../../forms/addListing/helpers/listingDetailsValueChecker' // some type checking on generic <Type> used in this component
import {
  removeSpecialCharacters,
  replaceWhiteSpace,
} from '../../utils/helpers/commonFunctions' // some regex helper functions to strip out unwanted string items

type FileResponse = {
  url: string
  fields: Record<string, string> // TODO:: better type this
}

type FileRequest = {
  fileType: string
  fileName: string
}

export const handleUploadFiles = async <T>(
  file: File,
  apiUrl: string,
  formDataFields?: T, // type is checked before being used here
) => {
  const fileName = encodeURIComponent(file.name)
  const fileType = encodeURIComponent(file.type)

  const details = convertGenericTypeToListingDetails(formDataFields)
  const fileTitleFormatted = encodeURIComponent(
    replaceWhiteSpace(removeSpecialCharacters(details.fileTitle, ' '), '-'),
  )
  // get presigned put url to send file to s3 bucket
  // TODO:: probably should move this presigned POST to its own little function and add better typing for it.
  const { data } = await singlePostRequest<FileRequest, FileResponse>(
    `${apiUrl}?file=${fileName}&fileType=${fileType}&listingId=${details.fileId}&listingTitle=${fileTitleFormatted}`,
    {
      fileType,
      fileName,
    },
  )
  const { url, fields } = data

  const formData = new FormData()
  // NOTE:: the order of which these fields are appended to the FormData object are important
  // the file: File must be the list attribute in the formData object.
  Object.entries({ ...fields, file }).forEach(([key, value]) => {
    formData.append(key, value)
  })

  // NOTE:: this post request is successful if and only if it returns a 204 status.
  const uploadResponse = await singlePostRequest<FormData, unknown>(
    `${url}`,
    formData,
  )

  if (uploadResponse) {
    // return image url path used in your s3 bucket of image just uploaded this is used for thumbnail preview.
    return `${url}${details.fileId}-${fileTitleFormatted}/${fileName}`
  } else {
    // TODO:: add a toast or some feedback here and logging here
    console.error('Upload failed.')
  }
}

• Get Presigned URL for uploading files from the frontend to the s3 bucket

• data

  • url = The values used in the URL used to get the presigned URL must match, see below for how these fields are used in the upload config for presigned URL.

  • fields = These fields must be sent in the payload body of the post request that is using the presigned URL, along with your file.

    • I recommend console.log('presigned fields ->', fields) the fields to get a better understanding of what this object consists of.

  • The file must be the last item on the payload body object, or in this case the formData object

    • Object.entries({ ...fields, file })

Upload config for presigned URL, API handler

import { NextApiRequest, NextApiResponse } from 'next'
import { createPresignedPost } from '@aws-sdk/s3-presigned-post'
import { s3Client } from '../../../lib/awsS3Client'

const uploadHandler = async (
  req: NextApiRequest,
  res: NextApiResponse,
): Promise<void> => {
  const {
    query: { file, fileType, fileId, fileTitle },
    method,
  } = req

  switch (method) {
    case 'POST':
      try {
        const post = await createPresignedPost(s3Client, {
          Bucket: process.env.S3_BUCKET_NAME,
          // Key: must match POST url for file upload
          Key: `${fileId}-${fileTitle}/${file}`,
          Fields: {
            ContentType: fileType as string,
          },
          Expires: 600, // seconds
          Conditions: [
            { bucket: process.env.S3_BUCKET_NAME },
            ['starts-with', '$ContentType', 'image/'],
          ],
        })

        res.status(200).json(post)
      } catch (error: any) {
        console.error('🚀 ~ file: index.ts ~ line 45 ~ error', error)
        // throw error for errorWrapper to handle?
        // send to some error logging service?
        res.json(error)
        // throw error
      }
    default:
      res.status(405).end(`Method ${method} Not Allowed`)
  }
}

export default uploadHandler

• You will need to install @aws-sdk/s3-presigned-post

  • npm install @aws-sdk/s3-presigned-post

  • yarn add @aws-sdk/s3-presigned-post

• createPresignedPost handles all the complexity of getting the presigned URL for file upload, you can see it can be configured with options passed in.

• Key: = This matches the folder and file path used in the s3 bucket which goes after the presigned URL.

• Conditions: = Checking the bucket is correct and matches the Bucket: and also check the file type is allowed.

• This API handler only allows POST method

• You will need to add the following key values to your .env file

  • S3_BUCKET_NAME

  • BACKEND_URL this most likely will be /api/ or something very similar.

There is a lot to go through in this blog, yell out if something doesn't quite make sense or you see some smelly code! At this point you can now drag and drop multiple image files and have them upload to a sub folder directory in your AWS s3 bucket.

Any questions leave me a comment 🙌 or déjame un comentario en español 🙌
(I am working on my espanol)

The first thing I want to point out is, working with mapbox is very enjoyable, the docs are great, and there are tons of resources to learn from and work with.

This is a small part of my experience working with mapbox, here is the little web app Info Meliquina I started, which also incorporates some of the example code below.

As this is a small app I did not use typescript, but you can find all the typings in the code and the docs 👍node_modules/@types/mapbox-gl/index.d.ts

Setup and initialise mapboxGL

We want to make our mapboxGL globally available, so at the top of our file, we add the below snippet of code, just as a placeholder for when mapboxGL is initialised.

if (typeof window.mapboxGL === 'undefined') {
  window.mapboxGL = {}
}

Below you see a useEffect which only runs when the client aka window is ready and available.
This is where we can initialise our map and make it accessible throughout our app. Our dependency array [] of the useEffect is empty, this is because we only want to initialise our map when the app is first mounted.

  useEffect(function initializeProceduralGL() {
    const map = mapRef.current

    if (map) {
      const mapboxGL = initMap(map)

      window.mapboxGL = mapboxGL
    }
  }, [])

Here you will also see we are passing a div node ref to the initMap function.
This div is apart of the return statement of the jsx component

<div style={{ height: '100%', width: '100%' }} ref={mapRef}></div>

Once initMap is finished initialising our new mapboxGL object, it will return the new mapboxGL object and then this is attached to the window so we can access the same instance of mapboxGL globally in our app.

You will also notice I am not using an anonymous function inside the useEffect, I think it is a much better developer experience to provide the function with a name;

• It will be noticed much more than a comment above useEffect(() =>..

• It is nice to be able to read the function name and know, you don't need to look into the code to figure out what's happening with the side effect.

• Makes the useEffect searchable 🙌

The initMap function

import mapboxgl from 'mapbox-gl'
import { markerPointFeatures } from './constants'
import { mapBoxLoadPointImages } from './helpers/mapBoxLoadPointImages'

const MAPBOX_APIKEY = import.meta.env.VITE_CUSTOM_MAPBOX_TOKEN

const initMap = async map => {
  mapboxgl.accessToken = MAPBOX_APIKEY

  let mapboxGL = new mapboxgl.Map({
    container: map, // container ID
    center: [longitude, latitude], // starting position [lng, lat]
    zoom: 10, // starting zoom
    style: 'mapbox://styles/bronz3beard/your-custom-styled-map-key', // style URL or style object
    pitch: 70, // camera angle
    bearing: 120, // camera direction measured clockwise as an angle from true north
  })

  mapboxGL.on('load', function () {
// Add custom markers
    markerPointFeatures.forEach(value => {
// value = Feature
      mapBoxLoadPointImages(
        value.source,
        value.iconImage,
        value.iconPath,
        value.features,
        mapboxGL,
      )
    })
// Set the default atmosphere style
    mapboxGL.setFog({
      range: [0, 20],
    })
  })

  return mapboxGL
}

export default initMap

initMap breakdown.

1. I used vite to create this app

2. MAPBOX_APIKEY - how to set up a mapbox api key

3. initial mapboxgl.Map object attributes

   • Breakdown

     • container: value should be either HTMLElement | string

     • center: the order is important here [longitude, latitude]

     • zoom: The initial zoom level of the map defaults to 0 the range is 0-24

     • pitch: The initial pitch (tilt) of the map defaults to 0, measured in degrees away from the plane of the screen 0-85

     • bearing: camera direction measured clockwise as an angle from true north defaults to 0

4. There is a custom-styled map being used.

   • To learn more about how to do this, the docs have a great walkthrough which at the end also walks through adding your new map to your app.

5. mapboxGL.on('load', function () this is where we are adding our custom markers to the map

6. mapboxGL.setFog atmosphere styling

The mapBoxLoadPointImages function

This is a little helper function I wrote to help a developer (me) maintain a single focus when working on the code while dividing up the responsibilities of the code. Also helps keep my files light and easier to read.

This function accepts all the values that make up a Feature as you can see a little further down 👍

export const mapBoxLoadPointImages = (
  source,
  iconImage,
  iconPath,
  features,
  mapboxGL,
) => {
    mapboxGL.loadImage(iconPath, (error, image) => {
// if the image is already on loaded remove it, this is to ensure there is alwaays a fresh feature set on the map.
      if (mapboxGL.hasImage(iconImage)) {
        mapboxGL.removeImage(iconImage)
      }
      if (error) {
// I want this to work every time or not at all, there are other ways you might want to handle an error here, logging.
        throw error
      }
/* 
add the name of the image(iconImage) and the image itself. 
iconImage: string,
image: HTMLImageElement
       | ArrayBufferView
       | { width: number; height: number; data: Uint8Array | Uint8ClampedArray }
       | ImageData
       | ImageBitmap,
*/
      mapboxGL.addImage(iconImage, image)
    })

// Add a GeoJSON source with 2 points can be 3 but in this case it is just 2
/*
type: 'geojson' = GeoJSONSourceRaw -> GeoJSONObject -> Geometry -> Point -> {
        type: 'Point';
        coordinates: Position;
    } -> Position = number[]; // [number, number]
*/
    mapboxGL.addSource(source, {
      type: 'geojson',
      data: {
        type: 'FeatureCollection',
        features,
      },
    })

// Add a symbol layer allowing us to hook into node attrubites and customise the values
// This gives the layer a chance to initialize gl resources and register event listeners. 
    mapboxGL.addLayer({
      id: source,
      interactive: true,
      type: 'symbol',
      source: source,
      layout: {
        'icon-image': iconImage,
// get the title name from the source's "title" property
        'text-field': ['get', 'title'], // text to use for title
        'text-font': ['Open Sans Semibold', 'Arial Unicode MS Bold'],
        'text-offset': [0, 1.25], // text spacing and location from point icon
        'text-anchor': 'top', // text location relative to point icon
      },
    })

    if (iconPath) {
// update the mouse on hover over an icon
      mapboxGL.on('mouseover', source, event => {
        const features = mapboxGL.queryRenderedFeatures(event.point)
      })

      mapboxGL.on('mouseleave', source, event => {
        mapboxGL.getCanvas().style.cursor = ''
      })
    }
  }
}

mapBoxLoadPointImages breakdown

• loadImage loads the image from an external domain,

• addImage add the image to the style as an icon,

• addSource add the data source containing one or more point features

• addLayer create a new symbol layer that uses the icons to represent the point data and instructs the client to "draw" the image for each point in the data source.

The above breakdown is a summary of the docs found here.

markerPointFeatures

ℹ markerPointFeatures is an array of featuresto display on the map.

Feature example

  {
    source: 'Food',
    iconImage: 'food-marker',
// icon png just in the public folder
    iconPath: '/map-icons/food-32.png',
    features: [...foodFeatures],
  },

Features example

// foodFeatures
[{
    type: 'Feature',
    properties: {
      title: 'This is the title givien to this particular marker',
      locationType: 'Food',
      description: 'A helpful description of the marker point',
// you can add any key: value you think you might need here 
      ...
    },
    geometry: {
//lng, lat
      coordinates:  [-71.24808117629131, -40.386091124703896],
      type: 'Point',
    },
  },
  { ... },
]

Feature breakdown

Features are a simple JSON object defined by the geometry and properties attributes along with a type

• The outer feature object, is an object I use to build out features by what source they are "feature grouping", which means in this case "Food" icons are all the same.

• Everything in the features array is what mapboxGl needs to add an icon to a specific location on the map, along with some "metadata" that can be added to properties, you can add anything you want to properties.

• properties: "This can contain any JSON object*. Some examples of common properties, often known as metadata, include title and description*". *

  • *source is google search top result.

Accessing the properties metadata

Below code snippet is a truncated view of how you can access the properties you add to your custom feature point markers. You have to add an event listener which is built into mapboxGL -> mapboxGL.on('click',

You might want to access the properties metadata to display somewhere when the icon is clicked on, to log it to an analytics platform or to change it, it is really up to you what you do with it inside this onclick event listener.

  useEffect(
    function listenForFeatureIconClick() {
      const featureIconClick = async () => {
        const mapboxGL = await window.mapboxGL
// a simple check for existance of mapboxGL and if the object has some values in it already.
        if (mapboxGL && objectHasAttributes(mapboxGL)) {
          mapboxGL.on('click', event => {
            const features = mapboxGL.queryRenderedFeatures(event.point)

            const feature = features[0]
            ...
            const title = feature.properties.title
            ...

    }

    featureIconClick()
}, [window.mapboxGL])

This is just the tip of the iceberg with the kind of fun you can have building out map features. Check out Info Meliquina if you see anything you like, let me know! I can write up another blog about what you see in the app.
I am looking to build out the app in the future and add more features to the map and overall UI 💪

Till next time ✌️

I write this blog knowing that right now everyone is fanning out on AI (Generative Pre-trained Transformer 3) for any automation around code, and that is great! If you would prefer to look into this topic more, I suggest starting with #openGPT on Twitter or OpenAI Turn comments into code & API example.

Plop - Looks to be quite popular for React file generation and is better suited to smaller file code generation tasks, But it can be used to generate entire apps.

Other considerations

• Yeoman

• Hygen

• Agrippa

• Backstage

Yeoman looks better suited to generating entire apps but can also generate files and is cross-cutting so your backend and your frontend can use the same code generator.
Yeoman would be my next recommendation if Plop doesn't quite fit your needs.👍

Let me know if you would like to know more about the above-mentioned considerations, I can write another blog about them. 🙌

Things to consider before deciding on any automated code generation.

At what level do you want to set conventions and maintain code generation? App folder level or the file level?

• Generating an entire app, all or part of scaffolding is required to get developing quickly, but would also be used infrequently.

• Files/folders in existing apps File code generation will have a high frequency of use for feature work and adding to existing apps, which could add the highest value.

Consider your current codebase, which provides the most value?

Does the answer lend itself to maintaining conventions & patterns for app folder scaffolding, file boilerplate or maybe both?

Frequent use is not always a great indication of the high value of auto-generating code. Through frequent implementation, consistency is higher, but if it is the same implementation over and over, we should automate it.
Infrequent implementation can be less consistent, meaning we should lean on a template for consistency.

My recommendation; When starting with maintaining automated code generation templates, start at the file level. It is more forgiving, quicker to implement and easier to update 💪

The below examples only show how to generate new code, not how to update existing code.

Plop simple setup

package.json

{
    "name": "plopCodeGen",
    "version": "1.0.0",
    "description": "collection of templates for generating file boilerplate or app skeletons",
    "main": "plopfile.js",
    "author": "me@hello.com",
    "private": true,
    "scripts": {
        "new": "plop",
        "new:app": "plop app",
        "new:comp": "plop component",
        },
    "devDependencies": {
        "plop": "^3.1.1",
    }
}

plopfile.js

You will notice the first arg of the plop.setGenerator(name, config) matches the scripts in the package.json

import generateApp from './templates/appTemplate'
import generateComponent from './templates/componentTemplate'

module.export = function (plop) {
    plop.setGenerator('app', generateApp),
    plop.setGenerator('component', generateComponent)
}

Templates

Example; App skeleton - simple folders & files layout.

templates/
    appTemplate/
    |   app/
    |   |   public/
    |   |   |   favicon.ico
    |   |   |   index.html.hbs
    |   |   |   manifest.json.hbs
    |   |   src/
    |   |   |   App.js.hbs
    |   |   |   index.css.hbs
    |   |   |   index.js.hbs
    |   |   |   routes.js.hbs
    |   |   test/
    |   |   package.json.hbs
    |   index.js
    |

Generate an app skeleton

Prompts and actions

In actions you will see to get our app folder structure correct we have to replicate the type: 'add', rather than use the type: addMany which will add many files into one folder. There are many action types you can use.

You can also see the "name" variable has a modifier in front of it pascalCase you can find all modifiers here.

templates/appTemplate/index.js

module.exports = {
  description: 'Generates new App folder',
    prompts: [
      {
// "input" standard inquirer prompt
        type: "input",
// name is the variable you can reuse in your template files and path
        name: "name",
// message is the prompt to the user aka. context
        message: "What's the name of the new app?",
// optional input validation function
        validate: function (value) {
          let message = true
          if (!/.+/.test(value)) {
            message = console.error('Missing', 'you must define the app name')
          } else if (value.length < 4) {
            // send new message for user feedbaack 
            message = console.error(
              'Too Short',
              `"${value}" is not descriptive enough`,
            )
          }

          return message
        }
      }
    ],
// TODO:: Make destination path an input in above prompts for user to choose where the component should live.
  actions: function () {
    return [
      {
        // action type
        type: 'add',
        // output path
        path: '../../../apps/{{pascalCase name}}/package.json',
        // input path
        templateFile: './templates/appTemplate/package.json.hbs',
        // the section of the path that should be excluded when adding files to the destination folder
        base: 'app'
      },
      {
        type: 'add',
        path: '../../../apps/{{pascalCase name}}/src/App.js',
        templateFile: './templates/appTemplate/src/App.js.hbs',
        base: 'app'
      },
      {
        type: 'add',
        path: '../../../apps/{{pascalCase name}}/src/index.css',
        templateFile: './templates/appTemplate/src/index.css.hbs',
        base: 'app'
      },
      {
        type: 'add',
        path: '../../../apps/{{pascalCase name}}/src/index.js',
        templateFile: './templates/appTemplate/src/index.js.hbs',
        base: 'app'
      },
      {
        type: 'add',
        path: '../../../apps/{{pascalCase name}}/src/routes.js',
        templateFile: './templates/appTemplate/src/routes.js.hbs',
        base: 'app'
      },
      {
        type: 'add',
        path: '../../../apps/{{pascalCase name}}/public/favicon.ico',
        templateFile: './templates/appTemplate/public/favicon.ico',
        base: 'app'
      },
      {
        type: 'add',
        path: '../../../apps/{{pascalCase name}}/public/index.html',
        templateFile: './templates/appTemplate/public/index.html.hbs',
        base: 'app'
      },
      {
        type: 'add',
        path: '../../../apps/{{pascalCase name}}/public/manifest.json',
        templateFile: './templates/appTemplate/public/manifest.json.hbs',
        base: 'app'
      },
    ]
  }
}

index.js.hbs

import React, { StrictMode } from "react"
import ReactDOM from "react-dom/client"
import App from "./App"
import { BrowserRouter } from "react-router-dom"

import './index.css'

const root = ReactDOM.createRoot(document.getElementById("root"))
root.render(
  <StrictMode>
    <BrowserRouter>
      <App />
    </BrowserRouter>
  </StrictMode>
)

App.js.hbs

import React from 'react'
import Routes from './routes'

const App = () => <Routes />

export default App

routes.js.hbs

import { Routes, Route } from 'react-router-dom'

export default function {{pascalCase name}}AppRoutes() {
    return (
      <Routes>
        <Route path="/" element={<Landing />} 
          <Route path="/tab-one" element={<TabOne />} />
          <Route path="/tab-two" element={<TabTwo />} />
        </Route>
      </Routes>
    )
}

index.css.hbs

This is a small preview of a main.css file showing that you can add your CSS as normal you could ask in your prompts for global styling named variables if you wanted to add them here.

body,
html {
    height: 100%;
    margin: 0;
    padding: 0;
    font-family: ...
}

manifest.json.hbs

This is a small preview of a manifest file showing how you can assign the name variable to keys in the JSON file.

{
    "short_name": "{{name}}",
    "name": "The Best {{name}}",
    "icons": [],
    ...
}

Generate a file

Prompts and actions

templates/componentTemplate/index.js

module.exports = {
  description: 'Generates new component',
  prompts: [
    {
      type: 'input',
      name: 'name',
      message: "What's the name of the component? (make sure to suffix/prefix with ...)",
      validate: function (value) {
        let message = true

        if (!/.+/.test(value)) {
          message = console.error('Missing', 'you must define a component name')
        } else if (value.length < 4) {
          message = console.error(
            'Too Short',
            `"${value}" is not descriptive enough`,
          )
        }

        return message
      },
    },
    {
      type: 'input',
      name: 'app',
// useful for multi app codebase or in not multi just add src/pages/app or remove.
      message: "What's the name of the app for this component to be added?",
      validate: function (value) {
        let message = true

        if (!/.+/.test(value)) {
          message = console.error('Missing', 'you must define a app name')
// TODO:: add some smarts, can a config file be used to check the existence of an app here?
        } else if (value.length < 4) { 
          message = console.error(
            'Too Short',
            `"${value}" is not descriptive enough`,
          )
        }

        return message
      }
    },
    {
      type: 'input',
      name: 'location',
      message: "Where inside the app src folder should this component live? (e.g. shared common folder)",
      validate: function (value) {
        let message = true

        if (!/.+/.test(value)) {
          message = console.error('Missing', 'you must define a folder location name')
// TODO:: add some smarts, can a config file be used to check the existence of an app here?
        } else if (value.length < 4) {
          message = console.error(
            'Too Short',
            `"${value}" is not descriptive enough`,
          )
        }

        return message
      }
    }
  ],
// TODO:: make destination path an input above for user to choose where the component should live.
  actions: function () {
    return [
      {
        type: 'add',
        path: '../../../apps/{{app}}/src/{{location}}/{{pascalCase name}}/index.js',
        templateFile: './templates/componentTemplate/index.hbs',
      }
    ]
  }
}

index.js.hbs

import React from 'react'
// Add your other imports for this component here...

// Add types here if you are using .ts/.tsx

// NOTE: If you know the required props for this component you can destructure them and add them below insted of "props"
function {{pascalCase name}}(props) {
// Add functions as you need them...

// Add as usual add your component return jsx...
  return (
    <div className="">
      <label>HW</label>
    </div>
  )
}

Some Pros & Cons of using Plop

Pros:

• Very quick implementation gentle learning curve.

• Easy to add new code to existing apps.

• Easy to make adjustments to templates to keep aligned with any new conventions or updated patterns*.

• You can also import non-template files like favicon.ico...

Cons:

• * Because of its ease of use, it is simple to make adjustments to the templates that suit the developer on the fly. Docs and an opinionated implementation guide would need to be maintained.

• Plop template files cannot be dynamically downloaded and used from a template repo. They can be published as a (private) npm module, git issue

Some final things to consider

• Is code auto-gen a complete buy-in for all devs when creating new apps/folders/files?

• Does this implementation replace manual creation altogether? Should it?

• Where/How should manual code creation be managed when used side by side with automated code auto-gen?

• How can conventions and code patterns be established for templates?

• How can existing auto-generated code be updated when the code auto-gen template changes with an evolving codebase?

I recommend using code auto-generation for brand new projects or files, but only after establishing some foundations & opinions on how templating should be implemented and maintained.
It is a great way for any developer, especially freelancers or solo workers to free up some time so you can get down to the fun stuff.

Till next time 👋

1. Make sure you use consistent language and remember words matter.
2. Identify what the the deliverable feature is before you start working on it.
3. Identify and clearly communicate in the code the areas of awkwardness.
4. Make sure you understand responsibilities in/of the code and make it obvious where they are.
5. Duplication over incorrect abstraction (this one requires more thought than you might assume!).
6. Always have and show empathy for your fellow developer 🙌

Caveat; Try your best to form opinions, it will help with all of the above, even if those opinions get old or are slightly off they will still help!

I want to add to the list in the future as I continue to learn and gain experience, if there are any other obvious items you would like to add or some gems I am missing, please share them in the comments below. The wider the range of values and perspectives for this list the more accurate and helpful it will be.

Rory

By the end of this post, you will have a new custom context menu component to drop into your web app. 💪

So what is a "custom context menu"? It is the menu that appears when you use your mouse to right click on a website, or two fingers on a mac track pad. You will notice some website disable this functionality, on the Firefox browser you can press cmd + shift + right mouse click to see the context menu.

⚠️ Before adding a custom context menu to your website, remember you are removing what is standard expected behavior for the right mouse click event, so remember to consider accessibility and check your design is providing a real solution for the user with a custom context menu.

So what do we want to deliver here? 💰

• A custom menu with specific options relevant to the current website.

• When the user right clicks, the custom context menu should appear with the custom menu options.

• The menu needs to always be visible, no matter where the user clicks on your website.

• The context menu should disappear when the user scrolls or clicks outside the menu.

How do the deliverables translate into code? 🤲

1. We need event listeners to capture the user mouse events.

   • Considering there are 3 different types of events to listen for, an event listener hook will be useful.

2. We need a component to handle all the logic for showing and hiding the context menu.

3. We need a component for the menu options. (Not included here this is where you get creative)

The event listener hook 🎧

Considering this is not the main focus of this post I am not going to go deep into this hook, but feel free to ask about it.

import { useEffect, useRef, RefObject } from 'react';

/*
  - "type" of listener.
  - "listenerCallback" to handle event.
  The keyof operator takes an object type
  and produces a string or numeric literal union of its keys

  - "target" for listener to be attached to,
  right now can be window or html element
  not hooked up to work with document.

  "options" generally goes unused can also be set to false by default,
  but unused is okay.
*/

const useEventListener = <
  KW extends keyof WindowEventMap,
  KH extends keyof HTMLElementEventMap,
  T extends HTMLElement
>(
  type: KW | KH,
  listenerCallback: (
    event: WindowEventMap[KW] | HTMLElementEventMap[KH] | Event
  ) => void,
  target?: RefObject<T>,
  options?: boolean | EventListenerOptions | undefined
): void => {
  // using ref so we dont have to add listenerCallback
  // to the dependency array
 // of the useEffect where the listener is added below.
  const savedHandler = useRef(listenerCallback);

  useEffect(() => {
    // add callback to ref
    savedHandler.current = listenerCallback;
  }, [listenerCallback]);

  useEffect(() => {
    // window or element
    const targetActual: T | Window = target?.current || window;

    // check event listener is available on targetElement,
    // TODO:: maybe add assert here?
    if (!targetActual?.addEventListener) {
      return undefined;
    }

    // Create event listener that calls handler function stored in ref
    const eventListenerCallback: typeof listenerCallback = (event) =>
      savedHandler.current(event);
    // on component mount listen for event
    targetActual.addEventListener(type, eventListenerCallback);
    // on component unmount remove listener
    return () =>
      targetActual.removeEventListener(type, eventListenerCallback);
  }, [target, type]);
};

export default useEventListener;

The context menu component 🙈🙉🙊

This is where the logic for showing and hiding the context menu lives & the container of the menu itself.

import React, { FC, useEffect, useRef, useState } from 'react'
import ShareMenu from '../shareMenu'
import useEventListener from '../hooks/useEventListener'

const CustomContextMenu: FC = () => {
    const [visible, setVisible] = useState<boolean>(false)
    const [confirmCopy, setConfirmCopy] = useState<boolean>(false)
    const [clientSide, setClientSide] = useState<boolean>(false)

    useEffect(function onClientSideSetClientIsTrue(): void {
        // This approach for checking client side is preferred over
        // typeof window !== 'undefined' as window is not available server side.
        // useEffect method will only be executed on the client.
        setClientSide(true)
    }, [])

    // refs provide a way to access DOM nodes or React elements created in the render method.
    const rootMenuRef = useRef<HTMLDivElement>(null)
    const copyRef = useRef<HTMLDivElement>(null)

    const handleContextMenu = (event: Event | MouseEvent): void => {
        event.preventDefault()

        setVisible(true)

        const rootRef: HTMLDivElement | null = rootMenuRef?.current
        if (!rootRef) {
            return
        }

        const clickX: number = (event as MouseEvent).clientX
        const clickY: number = (event as MouseEvent).clientY
        const screenW: number = window.innerWidth
        const screenH: number = window.innerHeight
        // root width and height have to be hard coded,
        // this is because the element in not visible making innerHeight and innerWidth === 0
        const rootW: number = 256 // menu width you will see this matches the tailwindcss in the return
        const rootH: number = 320 // menu height you will see this matches the tailwindcss in the return


        const right: boolean = clickX > screenW / 2
        const left: boolean = !right

        const top: boolean = screenH - clickY > rootH
        const bottom: boolean = !top

        const refStyles: CSSStyleDeclaration | undefined = rootRef?.style
        if (refStyles === undefined) {
            return
        }

        if (refStyles !== undefined) {
            if (left) {
                refStyles.left = `${clickX + 5}px`
            }
            if (right) {
                // horizontal mouse location, minus the menu width - 5
                refStyles.left = `${clickX - rootW - 5}px`
            }
            if (top) {
                refStyles.top = `${clickY + 5}px`
            }
            if (bottom) {
                // vertical mouse location, minus the menu height - 5
                refStyles.top = `${clickY - rootH - 5}px`
            }
        }
    }

    const handleMouseAction = (event: Event): void => {
        // prevent event propagating to parent because
        // without this prevention this click will hide the menu
        event.stopPropagation()

        const rootRef = rootMenuRef?.current
        if (!rootRef) {
            return
        }

        const copRef = copyRef?.current
        if (!copRef) {
            return
        }
        /* if() logic in plain english */
        // If the context menu is not visible AND 
        // the click event target is from the menu itself OR
        // the click event is from the menu option to copy a url THEN
        // show the menu OTHERWISE
        // hide the menu.
        if (
            !visible &&
            ((rootRef && rootRef.contains(event.target as HTMLDivElement)) ||
                (copRef && copRef.contains(event.target as HTMLDivElement)))
        ) {
            setVisible(true)
        } else {
            setVisible(false)
        }
    }

    const handleScrollAction = (): void => {
        // if on scroll the menu is visible hide it OTHERWISE
        // do nothing
        if (visible) {
            setVisible(false)
        }
    }

    useEventListener('click', handleMouseAction)
    useEventListener('scroll', handleScrollAction)
    useEventListener('contextmenu', handleContextMenu)

    return !clientSide ? null : (
        <div
            ref={rootMenuRef}
            className={`${
                !visible
                    ? 'hidden'
                    : 'flex items-center justify-center w-64 h-80 fixed p-1 rounded bg-gray-100 text-center z-50 shadow-lg shadow-black'
            }`}
        >
            {visible && (
                <ShareMenu
                    ref={copyRef}
                    confirmCopy={confirmCopy}
                    setConfirmCopy={setConfirmCopy}
                />
            )}
        </div>
    )
}

export default CustomContextMenu

What does all this gibberish mean? Lets break it down.

First you will see we have some state that handles 3 different things. Which are all initially false.

1. Menu visibility.

2. A confirmation for if the copy menu option was clicked.

3. Checking if the client is available.

const [visible, setVisible] = useState(false) const [confirmCopy, setConfirmCopy] = useState(false) const [clientSide, setClientSide] = useState(false)

#### Then you see we have two ```refs

1. ref 1 holds the reference to the DOM node, which in this case is just a div.
2. ref 2 is actually forwarded to a DOM node which is inside the ShareMenu react element.

// refs provide a way to access DOM nodes
// or React elements created in the render method
const rootMenuRef = useRef<HTMLDivElement>(null)
const copyRef = useRef<HTMLDivElement>(null)

Now we have the smarts of the component the handleContextMenu function.

There is a bit going on here so we can break this down also. This function handles if the context menu is visible & what the location is for the menu.

Show the menu

setVisible(true)

Check if the context menu ```
ref
``` is not null
> ```typescript   
const rootRef: HTMLDivElement | null = rootMenuRef?.current
if (!rootRef) {
   return
}

These are the coordinates of the mouse when the user clicked.

• We need a Type Assertion for clickX/Y because in this case we know better than the compiler.

"as" is a Type Assertion in TypeScript which tells the compiler to consider the object as another type than the type the compiler infers the object to be.

const clickX: number = (event as MouseEvent).clientX // horizontal const clickY: number = (event as MouseEvent).clientY // vertical

Browser window width and height
> ```typescript
const screenW: number = window.innerWidth
const screenH: number = window.innerHeight

Root width and height have to be hard coded. This is because the DOM node in not visible making innerHeight and innerWidth both zero

const rootW: number = 256 // px // menu width const rootH: number = 320 // px // menu height

Here we are checking which quarter the mouse was click in.
*Imagine there is a line through the middle of the screen left to right & top to bottom.*
>```typescript
const right: boolean = clickX > screenW / 2
const left: boolean = !right
const top: boolean = screenH - clickY > rootH
const bottom: boolean = !top

Here is how we tell the context menu where to appear relative to the browser window and the mouse location.

if (refStyles !== undefined) { if (left) { refStyles.left = ${clickX + 5}px } if (right) { refStyles.left = ${clickX - rootW - 5}px } if (top) { refStyles.top = ${clickY + 5}px } if (bottom) { refStyles.top = ${clickY - rootH - 5}px } }

#### Next we have two functions ```handleMouseAction``` & ```handleScrollAction

These functions are callback functions for their respective event listeners, both handle showing and hiding the context menu.

Lastly we have our event listeners

useEventListener('click', handleMouseAction)
useEventListener('scroll', handleScrollAction)
useEventListener('contextmenu', handleContextMenu)

Finally we the return statement for our context menu component

You will see that if the client is not ready we return null, when it is we will have access to show and hide our context menu based on some react state and some tailwindcss styling.

return !clientSide ? null : (

... ```

That's it! You now your very own custom context menu to add to and react project.

Rory. ✌️

The following are some of my learning's migrating from old to new with NextJS framework, also included, is a collection of resources used a long the way.

I am generally not a great technical writer, I always end up with the TLDR; version, so I apologize for that now. Writing is something I am actively trying to improving on as a software engineer, hence this is why I am starting a blog, thanks hashnode!

This is a hindsight reflection on how things went down, so please ask any questions as I have surely left things out on my path to upgrade.

Jargon translation - words, acronyms

• TLDR = too long don't read
• Programming language = They are a kind of computer language
• Library = A collection of pre-written code
• Framework = abstraction which can provide generic functionality
• Javascript = ¿programming language?
• React = Javascript Library
• NextJS = react framework
• Closed Source = not available for public use
• Client-side = refers to operations that are performed by the client(essentially the web browser)
• Server-side = refers to operations that are performed by the server, (a different computer to the one you are using the app on)
• UI = user interface (the stuff you look at, aka the most important part of the app)
• Web app = an application that runs inside your web browser aka: app
• Software engineer = Someone who writes gibberish across a computer screen all day, and then analyses why what has been written is not yet as good as it could be
• Stack trace = A list of things the application was doing when an Exception(error) happened
• Component = An independent and reusable bit of code
• Use client = An instruction for when building the app that explains that this component should be used Client side
• Leaf = is a reference to the location of a leaf on a tree, usually being the most outer part of the tree, in reference to this app the trunk of the tree is everything inside the app folder.

Resources

1. NextJS 13 blog
2. [Feedback] App Directory in Next.js 13
3. Your Next.js 13 upgrade guide
4. Routing
5. Layout component
   • Nested layouts with routing
6. Data fetching
7. How to Build a Fullstack App with Next.js, Prisma, and PostgreSQL
   • NextJS Auth - Providers
8. Getting started with Next.js, TypeScript, and Stripe Checkout
   • Adding prebuilt stripe to NextJS
   • Creating a product for stripe checkout

Project

How it started	How its going

Nothing outrageous there, no refactoring... I know you all want to see what is in the app folder, so here it is.

The app folder

Learning's so far, potential points of interest

• I only have one layout.tsx (server-side), this is because I have a PageTemplate component that handles some general styling throughout my app. This could change as I get more familiar with layout.tsx components. check out the code section below to see what *PageTemplate looks like.

  // single flex col with marginX
  return (
      <PageTemplate>
        <Title headerType="h1Title" title="Add a your Details" />

        <AddDetailsForm />
      </PageTemplate>
  )

  // tripple flex col
  return (
      <PageTemplate
        fixedLeftContent={
          [<div className="text-black">left content</div>]
        }
        fixedRightContent={
          [<div className="text-black">right content</div>]
        }
      >
        <Title
          headerType="h1Title"
          title="Update a your Profile"
        />

        <UpdateProfileForm />
      </PageTemplate>
  )

• I only use one error.tsx(client-side), this is because previously I used a pretty standard errorBoundary component, it handles all major UI failures, this code now lives inside error.tsx. As I get more comfortable with error.tsx and needing better stack trace I am sure this will change.
• All Pages except the list/page.tsx are client-side, I will need to move the 'use client' to the leaf components as I continue work on this app, this will help lift the performance of the site, and better inform the developer where client-side interactive components live.
• For now I have offloaded payment responsibility to stripe for payment through url, the pages/api, handles that redirect
• Next auth is handled through pages/api also, essentially following the above resource How to Build a Fullstack App with Next.js, Prisma, and PostgreSQL with some tweaking here and there.
• Prisma client and usage, essentially followed the above recourse How to Build a Fullstack App with Next.js, Prisma, and PostgreSQL with some tweaking here and there
• tailwindcss I didn't notice any changes for adding tailwindcss to the project.

Pros & Cons of upgrade

Pros

• Having a constant reminder to write code that is composition over abstraction, the reminder is the new folder/file convention.
• Requesting data where it is needed in a simple way and now only one way.
• Flexibility to implement different patterns for folder/file management outside of app folder per team or application requirements.
• New and easier way to add fonts to the project
• Remove <head> node noise from page, it now lives in layout.tsx
• Better developer experience
  • Reduced code abstraction
  • Reduced need for context providers
  • Reduced duplication of tailwindcss utility styling throughout app
  • Better Image component implementation
  • Overall better developer experience
  • Single focus when working on UI, API, App composition, related to developer experience
  • No more custom server stuff, this was always possible, but it just feel more permanent now, your head space is either with in app/components or api/prisma

Cons

• pages/api I was very ready to get rid of pages folder, I never really liked it. I think api folder can be a first class citizen just like app.
• Learning curve of server side and client side working in tandem, not specific to NextJS, just my limited knowledge so far.
• Have to update all Link components to no longer contain <a> elements, or use a legacy version of Link.

Code snippets

I have added some code snippets to reference, hopefully adding some context to all the words above.

rootLayout

  import React, { ReactNode } from 'react'
  import { Iceland } from '@next/font/google'
  import CustomContextMenu from '../components/contextMenu'
  import BootstrapContext from '../context/bootstrapContext'
  import Footer from '../components/common/footer'

  import '../styles/globals.css'

  const iceland = Iceland({
    weight: '400',
    style: 'normal',
    subsets: ['latin'],
  })

  export default function RootLayout({ children }: { children: ReactNode }) {
    return (
      <html lang="en" dir="ltr" className={iceland.className}>
        <head>
          <title>The Shop</title>
          <meta name="description" content="buy and sell merchandise online" />
          <link rel="icon" href="/favicon.ico" />

          <link rel="manifest" href="/site.webmanifest" />
          <link
            rel="sitemap"
            type="application/xml"
            title="Sitemap"
            href="/sitemap.xml"
          />
          <link rel="home" href="/" />

          <link rel="canonical" href="https://www..." />
          <link
            rel="apple-touch-icon"
            sizes="180x180"
            href="/apple-touch-icon.png"
          />
          <link
            rel="icon"
            type="image/png"
            sizes="32x32"
            href="/favicon-32x32.png"
          />
          <link
            rel="icon"
            type="image/png"
            sizes="16x16"
            href="/favicon-16x16.png"
          />
          <link rel="manifest" href="/site.webmanifest" />
          <link rel="mask-icon" href="/safari-pinned-tab.svg" color="#5bbad5" />
          <link rel="icon" href="/favicon.ico" />
        </head>
        <body className="font-theme">
          <BootstrapContext>{children}</BootstrapContext>
          <Footer />
          <CustomContextMenu />
        </body>
      </html>
    )
  }

PageTemplate

  import React, {
    FC,
    Children,
    cloneElement,
    ReactNode,
    ReactElement,
  } from 'react'
  // NOTE:: PageContent just provides "padding: 1rem"
  import PageContent from '../common/pageContent'

  type PageTemplateProps = {
    children: ReactNode | ReactNode[]
    fixedLeftContent?: ReactNode | ReactNode[]
    fixedRightContent?: ReactNode | ReactNode[]
  }
  // TODO:: maybe update hiding showing side columns based on count remove css.
  const PageTemplate: FC<PageTemplateProps> = (props: PageTemplateProps) => {
    const { children, fixedLeftContent, fixedRightContent } = props

    const fixedSideContentWidth =
      fixedRightContent && fixedLeftContent
        ? 'w-fixed lg:w-1/4 md:w-1/4 w-full flex-shrink flex-grow-0'
        : 'w-fixed lg:w-1/2 md:w-1/2 w-full flex-shrink flex-grow-0'

    return (
      <>
        <div className="w-full flex flex-col sm:flex-row flex-wrap sm:flex-nowrap pb-4 flex-grow">
          <div
            className={`${
              !fixedLeftContent || Children.count(fixedLeftContent) === 0
                ? 'hidden'
                : fixedSideContentWidth
            }`}
          >
            <div className="sticky w-full h-full justify-center text-center items-center">
              <PageContent>
                {Children.count(fixedLeftContent) > 0
                  ? Children.map(fixedLeftContent, (child: ReactElement) =>
                      cloneElement(child),
                    )
                  : null}
              </PageContent>
            </div>
          </div>
          <main role="main" className="w-auto flex-grow">
            <PageContent>
              {Children.count(children) === 1
                ? children
                : Children.map(children, (child: ReactElement) =>
                    cloneElement(child),
                  )}
            </PageContent>
          </main>
          <div
            className={`${
              !fixedRightContent || Children.count(fixedRightContent) === 0
                ? 'hidden'
                : fixedSideContentWidth
            }`}
          >
            <div className="flex sm:flex-col justify-center text-center items-center">
              <PageContent>
                {Children.count(fixedRightContent) > 0
                  ? Children.map(fixedRightContent, (child: ReactElement) =>
                      cloneElement(child),
                    )
                  : null}
              </PageContent>
            </div>
          </div>
        </div>
      </>
    )
  }

  PageTemplate.defaultProps = {
    fixedLeftContent: undefined,
    fixedRightContent: undefined,
  }

  export default PageTemplate

error.tsx

  'use client'
import React, { useState, useEffect } from 'react'
import Link from 'next/link'

interface ErrorBoundaryProps {
  error: Error
  reset: () => void
}

interface Error {
  message: string
}

const __DEV__: boolean =
  !process.env.NODE_ENV || process.env.NODE_ENV === 'development'

function AppErrorBoundary({ error, reset }: ErrorBoundaryProps) {
  const [hasError, setHasError] = useState<boolean>(false)

  useEffect(() => {
    if (error) {
      setHasError(true)
      // Log the error to an error reporting service
      console.error(error)
    }
  }, [error])

  return (
    <div className="flex items-center justify-center w-screen h-screen bg-gradient-to-r from-indigo-600 to-blue-400">
      <div className="px-40 py-20 bg-white rounded-md shadow-xl">
        <div className="flex flex-col items-center">
          <h1 className="font-bold text-blue-600 text-9xl capitalize">Error</h1>
          <h6 className="mb-2 text-2xl font-bold text-center text-gray-800 md:text-3xl">
            <span className="text-red-500">Oops! </span>
            This wasn&apos;t meant to happen! 😫😢
          </h6>
          <p className="mb-8 text-center text-gray-500 md:text-lg">
            Sorry for any inconvenience. If you&apos;re seeing this often,
            please
            <Link href="/">contact us</Link>
          </p>
          <Link
            href="/"
            className="px-6 py-2 text-sm font-semibold text-blue-800 bg-blue-100"
          >
            Take me home
          </Link>
          {__DEV__ && (
            <button onClick={() => reset()}>Reset error boundary</button>
          )}
        </div>
      </div>
    </div>
  )
}

export default AppErrorBoundary

list/page.tsx

  import prisma from '../../../../lib/prisma'
  import { MerchandiseApi } from '../../../../pages/api/merchandiseApi'
  import { formatDate } from '../../../../utils/helpers/commonFunctions'
  import CardGrid from '../../../../components/cardGrid'
  import Title from '../../../../components/common/title'
  import SearchBanner from '../../../../components/searchBanner'
  import PageTemplate from '../../../../components/pageTemplate'

  async function getData() {
    const data = await prisma.merchandise.findMany({
      include: {
        seller: { include: { user: true } },
        shop: true,
        item: true,
        itemImages: { include: { image: true } },
      },
    })

    const merchandise: MerchandiseApi = {
      merchandise: data.map(item => {
        return {
          ...item,
          creationDate: formatDate(item.creationDate, 'readableShortDate'),
        }
      }),
    }
    return merchandise
  }

  export default async function PropertiesPage() {
    const data = await getData()

    return (
      <>
        <SearchBanner
          bannerImage=""
          bannerHasSearch
          showPropertyTypeFilters
          width="w-full mx-auto transition-width transition-slowest ease"
        />
        <PageTemplate
          fixedLeftContent={[<div className="text-black">left content</div>]}
          fixedRightContent={[<div className="text-black">right content</div>]}
        >
          <Title
            headerType="h1Title"
            containerClassName="text-center"
            title="Merchandise result page"
          />

          <CardGrid data={data.merchandise} />

        </PageTemplate>
      </>
    )
  }

stripe

  import { Stripe, loadStripe } from '@stripe/stripe-js'

  let stripePromise: Promise<Stripe | null>
  const getStripe = () => {
    if (!stripePromise) {
      stripePromise = loadStripe(process.env.NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY!)
    }
    return stripePromise
  }

  export default getStripe

  'use client'
  import { useEffect } from 'react'
  import { loadStripe } from '@stripe/stripe-js'
  import { usePathname } from 'next/navigation'
  import { PrimaryButton } from '../common/button'

  // Make sure to call `loadStripe` outside of a component’s render to avoid
  // recreating the `Stripe` object on every render.
  const stripePromise = loadStripe(process.env.NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY)

  const StripPaymentButton = () => {
    useEffect(() => {
      // Check to see if this is a redirect back from Checkout
      const query = new URLSearchParams(window.location.search)
      if (query.get('success')) {
        console.log('Order placed! You will receive an email confirmation.')
      }

      if (query.get('canceled')) {
        console.log(
          'Order canceled -- continue to shop around and checkout when you’re ready.',
        )
      }
    }, [])

    const pathname = usePathname()
    console.log(
      '🚀 ~ file: index.tsx ~ line 21 ~ StripPaymentButton ~ pathname',
      pathname,
    )

    return (
      <form
        action="/api/checkout_sessions"
        method="POST"
        className="relative w-full"
      >
        <PrimaryButton
          width="lg:w-max md:w-max w-full"
          height="h-full"
          buttonPadding="p-1"
          type="submit"
          role="link"
          textColour="text-gray-700"
          borderRadius="rounded-sm"
          backgroundColor="bg-green-300"
          containerClassName="absolute lg:right-2 right-0 lg:-top-64 md:-top-56 -top-24 lg:w-auto md:w-auto w-full"
        >
          Purchase
        </PrimaryButton>
      </form>
    )
  }

  export default StripPaymentButton

pages/api/checkout_sessions

  import { NextApiRequest, NextApiResponse } from 'next'
  import Stripe from 'stripe'

  const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!, {
    // https://github.com/stripe/stripe-node#configuration
    apiVersion: '2022-08-01',
  })

  const stripeHandler = async (
    req: NextApiRequest,
    res: NextApiResponse,
  ): Promise<void> => {
    if (req.method === 'POST') {
      try {
        // Create Checkout Sessions from body params.
        const session = await stripe.checkout.sessions.create({
          submit_type: 'pay',
          payment_method_types: ['card'],
          line_items: [
            {
              // Provide the exact Price ID (for example, pr_1234) of the product you want to sell
              price: 'YOUR_PRICE_CODE_FOR_THIS_ITEM,
              quantity: 1,
            },
          ],
          mode: 'payment',
          success_url: `${req.headers.origin}/?success=true`,
          cancel_url: `${req.headers.origin}/?canceled=true`,
          automatic_tax: { enabled: true },
        })
        res.redirect(303, session.url)
      } catch (err) {
        res.status(err.statusCode || 500).json(err.message)
      }
    } else {
      // TODO:: do i need 'OPTIONS' here also?
      res.setHeader('Allow', 'POST')
      res.status(405).end('Method Not Allowed')
    }
  }

  export default stripeHandler

pages/api/auth/[...nextauth].ts

  const handleNavToListMyProperty = useCallback(
    (event: MouseEvent<HTMLButtonElement>) => {
      event.preventDefault()
      router.push(!session ? '/api/auth/signin' : '/create-user')
    },
    [session],
  )

  import { NextApiHandler } from 'next'
  import NextAuth from 'next-auth'
  import { PrismaAdapter } from '@next-auth/prisma-adapter'
  import GitHubProvider from 'next-auth/providers/github'
  import prisma from '../../../lib/prisma'

  const authHandler: NextApiHandler = (req, res) => NextAuth(req, res, options)
  export default authHandler

  const options = {
    providers: [
      GitHubProvider({
        clientId: process.env.GITHUB_ID,
        clientSecret: process.env.GITHUB_SECRET,
      }),
    ],
    adapter: PrismaAdapter(prisma),
    secret: process.env.SECRET,
  }

Prisma

  import { PrismaClient } from '@prisma/client'

  let prisma: PrismaClient

  if (process.env.NODE_ENV === 'production') {
    prisma = new PrismaClient()
  } else {
    if (!global.prisma) {
      global.prisma = new PrismaClient()
    }
    prisma = global.prisma
  }

  export default prisma

client-side api POST example: pages/api/add-new-item

  const newItem = await fetcher(
    `${endPoint}/add-new-item`,
    payload,
    'POST',
  )

  export const fetcher = async <T>(
    endpointUrl: string,
    payload?: T | Record<string, string> | string,
    method = 'GET',
  ): Promise<T> => {
    const response = await fetch(endpointUrl, {
      method,
      headers: {
        'content-type': 'application/json;charset=UTF-8',
      },
      body: JSON.stringify(payload),
    })

    const responseData = await response.json()

    if (response.ok) {
      if (responseData) {
        return responseData
      } else {
        return Promise.reject(new Error())
      }
    } else {
      const error = new Error(
        responseData.errors?.map((e: Error) => e.message).join('\n') ?? 'unknown',
      )
      return Promise.reject(error)
    }
  }

  import { NextApiRequest, NextApiResponse } from 'next'
  import prisma from '../../../lib/prisma'
  import { ItemDetails } from '../itemDetails'

  const itemDetailsHandler = async (
    req: NextApiRequest,
    res: NextApiResponse,
  ): Promise<void> => {
    const {
      body,
      // query,
      method,
    } = req

    switch (method) {
      case 'POST':
        const newData: ItemDetails = {
          ...body,
        }

        try {
          const data = await prisma.item.create({
            data: {
              sometablecolumn: newData.value
              ...
            },
          })

          const newItem: ItemDetails = data

          return res.status(200).json(newItem)

          // return res.send(payload);
        } catch (error: any) {
          // TODO:: dispatch error to redux here maybe?
          // throw error for errorWrapper to handle?
          // send to some error logging service?
          throw error
        }

      default:
        res.setHeader('Allow', ['OPTIONS'])
        res.status(405).end(`Method ${method} Not Allowed`)
    }
  }

  export default itemDetailsHandler

tailwindcss

  /* TODO:: import any custom fonts here */

  /* import/add tailwind styles to project */
  @import "tailwindcss/base";
  @import "./custom-base.css";

  @import "tailwindcss/components";
  @import "./custom-components.css";

  /* import any npm dependency styles here under "tailwindcss/components" to make sure they are added as "custom" styling */
  @import "tailwindcss/utilities";
  /* @import "custom-utilities.css"; */

/** @type {import('tailwindcss').Config} */

module.exports = {
  content: [
    './app/**/*.{js,ts,jsx,tsx}',
    './pages/**/*.{js,ts,jsx,tsx}',
    './components/**/*.{js,ts,jsx,tsx}',
  ],
  presets: [],
  darkMode: 'media', // or 'class'
  variants: {
    extend: {
      opacity: ['disabled'],
    },
  },
  theme: {
    extend: {
      transitionProperty: {
        width: 'width',
      },
      zIndex: {
        '-1': '-1',
      },
      transformOrigin: {
        0: '0%',
      },
      animation: {
        loader: 'loader 0.6s infinite alternate',
      },
      keyframes: {
        loader: {
          from: {
            opacity: 1,
            transform: 'translate3d(0, -1rem, 0)',
          },
          to: {
            opacity: 0.1,
          },
        },
      },
      fontFamily: {
        script: ["'Nanum Brush Script', cursive"],
        theme: ["'Chillax-Regular', sans"],
      },
    },
    screens: {
      sm: '640px',
      md: '768px',
      lg: '1024px',
      xl: '1280px',
      '2xl': '1536px',
    },
    colors: ({ colors }) => ({
      inherit: colors.inherit,
      current: colors.current,
      transparent: colors.transparent,
      black: colors.black,
      white: colors.white,
      slate: colors.slate,
      gray: colors.gray,
      zinc: colors.zinc,
      neutral: colors.neutral,
      stone: colors.stone,
      red: colors.red,
      orange: colors.orange,
      amber: colors.amber,
      yellow: colors.yellow,
      lime: colors.lime,
      green: colors.green,
      emerald: colors.emerald,
      teal: colors.teal,
      cyan: colors.cyan,
      sky: colors.sky,
      blue: colors.blue,
      indigo: colors.indigo,
      violet: colors.violet,
      purple: colors.purple,
      fuchsia: colors.fuchsia,
      pink: colors.pink,
      rose: colors.rose,



      'primary-colour': '#fb5607',
      'secondary-colour': '#ff006e',
      'tertiary-colour': '#3a86ff',
      'secondary-contrast-colour': '#ffbe0b',
      'contrast-colour': '#8338ec',

      'theme-black': '#121212',
      'theme-grey': '#535353', 
    }),
    columns: {
      auto: 'auto',
      1: '1',
      2: '2',
      3: '3',
      4: '4',
      5: '5',
      6: '6',
      7: '7',
      8: '8',
      9: '9',
      10: '10',
      11: '11',
      12: '12',
      '3xs': '16rem',
      '2xs': '18rem',
      xs: '20rem',
      sm: '24rem',
      md: '28rem',
      lg: '32rem',
      xl: '36rem',
      '2xl': '42rem',
      '3xl': '48rem',
      '4xl': '56rem',
      '5xl': '64rem',
      '6xl': '72rem',
      '7xl': '80rem',
    },
    spacing: {
      px: '1px',
      0: '0px',
      0.5: '0.125rem',
      1: '0.25rem',
      1.5: '0.375rem',
      2: '0.5rem',
      2.5: '0.625rem',
      3: '0.75rem',
      3.5: '0.875rem',
      4: '1rem',
      5: '1.25rem',
      6: '1.5rem',
      7: '1.75rem',
      8: '2rem',
      9: '2.25rem',
      10: '2.5rem',
      11: '2.75rem',
      12: '3rem',
      14: '3.5rem',
      16: '4rem',
      20: '5rem',
      24: '6rem',
      28: '7rem',
      32: '8rem',
      36: '9rem',
      40: '10rem',
      44: '11rem',
      48: '12rem',
      52: '13rem',
      56: '14rem',
      60: '15rem',
      64: '16rem',
      72: '18rem',
      80: '20rem',
      96: '24rem',
    },
    animation: {
      none: 'none',
      spin: 'spin 1s linear infinite',
      ping: 'ping 1s cubic-bezier(0, 0, 0.2, 1) infinite',
      pulse: 'pulse 2s cubic-bezier(0.4, 0, 0.6, 1) infinite',
      bounce: 'bounce 1s infinite',
      fade: 'fadeIn 2s ease',
    },
    aspectRatio: {
      auto: 'auto',
      square: '1 / 1',
      video: '16 / 9',
    },
    backdropBlur: ({ theme }) => theme('blur'),
    backdropBrightness: ({ theme }) => theme('brightness'),
    backdropContrast: ({ theme }) => theme('contrast'),
    backdropGrayscale: ({ theme }) => theme('grayscale'),
    backdropHueRotate: ({ theme }) => theme('hueRotate'),
    backdropInvert: ({ theme }) => theme('invert'),
    backdropOpacity: ({ theme }) => theme('opacity'),
    backdropSaturate: ({ theme }) => theme('saturate'),
    backdropSepia: ({ theme }) => theme('sepia'),
    backgroundColor: ({ theme }) => ({
      ...theme('colors'),
      'primary-colour': '#fb5607',
      'secondary-colour': '#ff006e',
      'contrast-colour': '#8338ec',
    }),
    backgroundImage: {
      none: 'none',
      'gradient-to-t': 'linear-gradient(to top, var(--tw-gradient-stops))',
      'gradient-to-tr':
        'linear-gradient(to top right, var(--tw-gradient-stops))',
      'gradient-to-r': 'linear-gradient(to right, var(--tw-gradient-stops))',
      'gradient-to-br':
        'linear-gradient(to bottom right, var(--tw-gradient-stops))',
      'gradient-to-b': 'linear-gradient(to bottom, var(--tw-gradient-stops))',
      'gradient-to-bl':
        'linear-gradient(to bottom left, var(--tw-gradient-stops))',
      'gradient-to-l': 'linear-gradient(to left, var(--tw-gradient-stops))',
      'gradient-to-tl':
        'linear-gradient(to top left, var(--tw-gradient-stops))',
    },
    backgroundOpacity: ({ theme }) => theme('opacity'),
    backgroundPosition: {
      bottom: 'bottom',
      center: 'center',
      left: 'left',
      'left-bottom': 'left bottom',
      'left-top': 'left top',
      right: 'right',
      'right-bottom': 'right bottom',
      'right-top': 'right top',
      top: 'top',
    },
    backgroundSize: {
      auto: 'auto',
      cover: 'cover',
      contain: 'contain',
    },
    blur: {
      0: '0',
      none: '0',
      sm: '4px',
      DEFAULT: '8px',
      md: '12px',
      lg: '16px',
      xl: '24px',
      '2xl': '40px',
      '3xl': '64px',
    },
    brightness: {
      0: '0',
      50: '.5',
      75: '.75',
      90: '.9',
      95: '.95',
      100: '1',
      105: '1.05',
      110: '1.1',
      125: '1.25',
      150: '1.5',
      200: '2',
    },
    borderColor: ({ theme }) => ({
      ...theme('colors'),
      DEFAULT: theme('colors.gray.200', 'currentColor'),
    }),
    borderOpacity: ({ theme }) => theme('opacity'),
    borderRadius: {
      none: '0px',
      sm: '0.125rem',
      DEFAULT: '0.25rem',
      md: '0.375rem',
      lg: '0.5rem',
      xl: '0.75rem',
      '2xl': '1rem',
      '3xl': '1.5rem',
      full: '9999px',
    },
    borderWidth: {
      DEFAULT: '1px',
      0: '0px',
      2: '2px',
      4: '4px',
      8: '8px',
    },
    boxShadow: {
      sm: '0 1px 2px 0 rgb(0 0 0 / 0.05)',
      DEFAULT: '0 1px 3px 0 rgb(0 0 0 / 0.1), 0 1px 2px -1px rgb(0 0 0 / 0.1)',
      md: '0 4px 6px -1px rgb(0 0 0 / 0.1), 0 2px 4px -2px rgb(0 0 0 / 0.1)',
      lg: '0 10px 15px -3px rgb(0 0 0 / 0.1), 0 4px 6px -4px rgb(0 0 0 / 0.1)',
      xl: '0 20px 25px -5px rgb(0 0 0 / 0.1), 0 8px 10px -6px rgb(0 0 0 / 0.1)',
      '2xl': '0 25px 50px -12px rgb(0 0 0 / 0.25)',
      inner: 'inset 0 2px 4px 0 rgb(0 0 0 / 0.05)',
      none: 'none',
    },
    boxShadowColor: ({ theme }) => theme('colors'),
    caretColor: ({ theme }) => theme('colors'),
    accentColor: ({ theme }) => ({
      ...theme('colors'),
      auto: 'auto',
    }),
    contrast: {
      0: '0',
      50: '.5',
      75: '.75',
      100: '1',
      125: '1.25',
      150: '1.5',
      200: '2',
    },
    container: {},
    content: {
      none: 'none',
    },
    cursor: {
      auto: 'auto',
      default: 'default',
      pointer: 'pointer',
      wait: 'wait',
      text: 'text',
      move: 'move',
      help: 'help',
      'not-allowed': 'not-allowed',
      none: 'none',
      'context-menu': 'context-menu',
      progress: 'progress',
      cell: 'cell',
      crosshair: 'crosshair',
      'vertical-text': 'vertical-text',
      alias: 'alias',
      copy: 'copy',
      'no-drop': 'no-drop',
      grab: 'grab',
      grabbing: 'grabbing',
      'all-scroll': 'all-scroll',
      'col-resize': 'col-resize',
      'row-resize': 'row-resize',
      'n-resize': 'n-resize',
      'e-resize': 'e-resize',
      's-resize': 's-resize',
      'w-resize': 'w-resize',
      'ne-resize': 'ne-resize',
      'nw-resize': 'nw-resize',
      'se-resize': 'se-resize',
      'sw-resize': 'sw-resize',
      'ew-resize': 'ew-resize',
      'ns-resize': 'ns-resize',
      'nesw-resize': 'nesw-resize',
      'nwse-resize': 'nwse-resize',
      'zoom-in': 'zoom-in',
      'zoom-out': 'zoom-out',
    },
    divideColor: ({ theme }) => theme('borderColor'),
    divideOpacity: ({ theme }) => theme('borderOpacity'),
    divideWidth: ({ theme }) => theme('borderWidth'),
    dropShadow: {
      sm: '0 1px 1px rgb(0 0 0 / 0.05)',
      DEFAULT: ['0 1px 2px rgb(0 0 0 / 0.1)', '0 1px 1px rgb(0 0 0 / 0.06)'],
      md: ['0 4px 3px rgb(0 0 0 / 0.07)', '0 2px 2px rgb(0 0 0 / 0.06)'],
      lg: ['0 10px 8px rgb(0 0 0 / 0.04)', '0 4px 3px rgb(0 0 0 / 0.1)'],
      xl: ['0 20px 13px rgb(0 0 0 / 0.03)', '0 8px 5px rgb(0 0 0 / 0.08)'],
      '2xl': '0 25px 25px rgb(0 0 0 / 0.15)',
      none: '0 0 #0000',
    },
    fill: ({ theme }) => theme('colors'),
    grayscale: {
      0: '0',
      DEFAULT: '100%',
    },
    hueRotate: {
      0: '0deg',
      15: '15deg',
      30: '30deg',
      60: '60deg',
      90: '90deg',
      180: '180deg',
    },
    invert: {
      0: '0',
      DEFAULT: '100%',
    },
    flex: {
      1: '1 1 0%',
      auto: '1 1 auto',
      initial: '0 1 auto',
      none: 'none',
    },
    flexBasis: ({ theme }) => ({
      auto: 'auto',
      ...theme('spacing'),
      '1/2': '50%',
      '1/3': '33.333333%',
      '2/3': '66.666667%',
      '1/4': '25%',
      '2/4': '50%',
      '3/4': '75%',
      '1/5': '20%',
      '2/5': '40%',
      '3/5': '60%',
      '4/5': '80%',
      '1/6': '16.666667%',
      '2/6': '33.333333%',
      '3/6': '50%',
      '4/6': '66.666667%',
      '5/6': '83.333333%',
      '1/12': '8.333333%',
      '2/12': '16.666667%',
      '3/12': '25%',
      '4/12': '33.333333%',
      '5/12': '41.666667%',
      '6/12': '50%',
      '7/12': '58.333333%',
      '8/12': '66.666667%',
      '9/12': '75%',
      '10/12': '83.333333%',
      '11/12': '91.666667%',
      full: '100%',
    }),
    flexGrow: {
      0: '0',
      DEFAULT: '1',
    },
    flexShrink: {
      0: '0',
      DEFAULT: '1',
    },
    fontFamily: {
      sans: [
        '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: [
        'ui-serif',
        'Georgia',
        'Cambria',
        '"Times New Roman"',
        'Times',
        'serif',
      ],
      mono: [
        'ui-monospace',
        'SFMono-Regular',
        'Menlo',
        'Monaco',
        'Consolas',
        '"Liberation Mono"',
        '"Courier New"',
        'monospace',
      ],
    },
    fontSize: {
      xs: ['0.75rem', { lineHeight: '1rem' }],
      sm: ['0.875rem', { lineHeight: '1.25rem' }],
      base: ['1rem', { lineHeight: '1.5rem' }],
      lg: ['1.125rem', { lineHeight: '1.75rem' }],
      xl: ['1.25rem', { lineHeight: '1.75rem' }],
      '2xl': ['1.5rem', { lineHeight: '2rem' }],
      '3xl': ['1.875rem', { lineHeight: '2.25rem' }],
      '4xl': ['2.25rem', { lineHeight: '2.5rem' }],
      '5xl': ['3rem', { lineHeight: '1' }],
      '6xl': ['3.75rem', { lineHeight: '1' }],
      '7xl': ['4.5rem', { lineHeight: '1' }],
      '8xl': ['6rem', { lineHeight: '1' }],
      '9xl': ['8rem', { lineHeight: '1' }],
    },
    fontWeight: {
      thin: '100',
      extralight: '200',
      light: '300',
      normal: '400',
      medium: '500',
      semibold: '600',
      bold: '700',
      extrabold: '800',
      black: '900',
    },
    gap: ({ theme }) => theme('spacing'),
    gradientColorStops: ({ theme }) => theme('colors'),
    gridAutoColumns: {
      auto: 'auto',
      min: 'min-content',
      max: 'max-content',
      fr: 'minmax(0, 1fr)',
    },
    gridAutoRows: {
      auto: 'auto',
      min: 'min-content',
      max: 'max-content',
      fr: 'minmax(0, 1fr)',
    },
    gridColumn: {
      auto: 'auto',
      'span-1': 'span 1 / span 1',
      'span-2': 'span 2 / span 2',
      'span-3': 'span 3 / span 3',
      'span-4': 'span 4 / span 4',
      'span-5': 'span 5 / span 5',
      'span-6': 'span 6 / span 6',
      'span-7': 'span 7 / span 7',
      'span-8': 'span 8 / span 8',
      'span-9': 'span 9 / span 9',
      'span-10': 'span 10 / span 10',
      'span-11': 'span 11 / span 11',
      'span-12': 'span 12 / span 12',
      'span-full': '1 / -1',
    },
    gridColumnEnd: {
      auto: 'auto',
      1: '1',
      2: '2',
      3: '3',
      4: '4',
      5: '5',
      6: '6',
      7: '7',
      8: '8',
      9: '9',
      10: '10',
      11: '11',
      12: '12',
      13: '13',
    },
    gridColumnStart: {
      auto: 'auto',
      1: '1',
      2: '2',
      3: '3',
      4: '4',
      5: '5',
      6: '6',
      7: '7',
      8: '8',
      9: '9',
      10: '10',
      11: '11',
      12: '12',
      13: '13',
    },
    gridRow: {
      auto: 'auto',
      'span-1': 'span 1 / span 1',
      'span-2': 'span 2 / span 2',
      'span-3': 'span 3 / span 3',
      'span-4': 'span 4 / span 4',
      'span-5': 'span 5 / span 5',
      'span-6': 'span 6 / span 6',
      'span-full': '1 / -1',
    },
    gridRowStart: {
      auto: 'auto',
      1: '1',
      2: '2',
      3: '3',
      4: '4',
      5: '5',
      6: '6',
      7: '7',
    },
    gridRowEnd: {
      auto: 'auto',
      1: '1',
      2: '2',
      3: '3',
      4: '4',
      5: '5',
      6: '6',
      7: '7',
    },
    gridTemplateColumns: {
      none: 'none',
      1: 'repeat(1, minmax(0, 1fr))',
      2: 'repeat(2, minmax(0, 1fr))',
      3: 'repeat(3, minmax(0, 1fr))',
      4: 'repeat(4, minmax(0, 1fr))',
      5: 'repeat(5, minmax(0, 1fr))',
      6: 'repeat(6, minmax(0, 1fr))',
      7: 'repeat(7, minmax(0, 1fr))',
      8: 'repeat(8, minmax(0, 1fr))',
      9: 'repeat(9, minmax(0, 1fr))',
      10: 'repeat(10, minmax(0, 1fr))',
      11: 'repeat(11, minmax(0, 1fr))',
      12: 'repeat(12, minmax(0, 1fr))',
    },
    gridTemplateRows: {
      none: 'none',
      1: 'repeat(1, minmax(0, 1fr))',
      2: 'repeat(2, minmax(0, 1fr))',
      3: 'repeat(3, minmax(0, 1fr))',
      4: 'repeat(4, minmax(0, 1fr))',
      5: 'repeat(5, minmax(0, 1fr))',
      6: 'repeat(6, minmax(0, 1fr))',
    },
    height: ({ theme }) => ({
      auto: 'auto',
      ...theme('spacing'),
      '1/2': '50%',
      '1/3': '33.333333%',
      '2/3': '66.666667%',
      '1/4': '25%',
      '2/4': '50%',
      '3/4': '75%',
      '1/5': '20%',
      '2/5': '40%',
      '3/5': '60%',
      '4/5': '80%',
      '1/6': '16.666667%',
      '2/6': '33.333333%',
      '3/6': '50%',
      '4/6': '66.666667%',
      '5/6': '83.333333%',
      full: '100%',
      screen: '100vh',
      min: 'min-content',
      max: 'max-content',
      fit: 'fit-content',
    }),
    inset: ({ theme }) => ({
      auto: 'auto',
      ...theme('spacing'),
      '1/2': '50%',
      '1/3': '33.333333%',
      '2/3': '66.666667%',
      '1/4': '25%',
      '2/4': '50%',
      '3/4': '75%',
      full: '100%',
    }),
    keyframes: {
      spin: {
        to: {
          transform: 'rotate(360deg)',
        },
      },
      ping: {
        '75%, 100%': {
          transform: 'scale(2)',
          opacity: '0',
        },
      },
      pulse: {
        '50%': {
          opacity: '.5',
        },
      },
      bounce: {
        '0%, 100%': {
          transform: 'translateY(-25%)',
          animationTimingFunction: 'cubic-bezier(0.8,0,1,1)',
        },
        '50%': {
          transform: 'none',
          animationTimingFunction: 'cubic-bezier(0,0,0.2,1)',
        },
      },
      fadeIn: {
        from: {
          opacity: 0,
        },
        to: {
          opacity: 1,
        },
      },
    },
    letterSpacing: {
      tighter: '-0.05em',
      tight: '-0.025em',
      normal: '0em',
      wide: '0.025em',
      wider: '0.05em',
      widest: '0.1em',
    },
    lineHeight: {
      none: '1',
      tight: '1.25',
      snug: '1.375',
      normal: '1.5',
      relaxed: '1.625',
      loose: '2',
      3: '.75rem',
      4: '1rem',
      5: '1.25rem',
      6: '1.5rem',
      7: '1.75rem',
      8: '2rem',
      9: '2.25rem',
      10: '2.5rem',
    },
    listStyleType: {
      none: 'none',
      disc: 'disc',
      decimal: 'decimal',
    },
    margin: ({ theme }) => ({
      auto: 'auto',
      ...theme('spacing'),
    }),
    maxHeight: ({ theme }) => ({
      ...theme('spacing'),
      full: '100%',
      screen: '100vh',
      min: 'min-content',
      max: 'max-content',
      fit: 'fit-content',
    }),
    maxWidth: ({ theme, breakpoints }) => ({
      none: 'none',
      0: '0rem',
      xs: '20rem',
      sm: '24rem',
      md: '28rem',
      lg: '32rem',
      xl: '36rem',
      '2xl': '42rem',
      '3xl': '48rem',
      '4xl': '56rem',
      '5xl': '64rem',
      '6xl': '72rem',
      '7xl': '80rem',
      full: '100%',
      min: 'min-content',
      max: 'max-content',
      fit: 'fit-content',
      prose: '65ch',
      ...breakpoints(theme('screens')),
    }),
    minHeight: {
      0: '0px',
      full: '100%',
      screen: '100vh',
      min: 'min-content',
      max: 'max-content',
      fit: 'fit-content',
    },
    minWidth: {
      0: '0px',
      full: '100%',
      min: 'min-content',
      max: 'max-content',
      fit: 'fit-content',
    },
    objectPosition: {
      bottom: 'bottom',
      center: 'center',
      left: 'left',
      'left-bottom': 'left bottom',
      'left-top': 'left top',
      right: 'right',
      'right-bottom': 'right bottom',
      'right-top': 'right top',
      top: 'top',
    },
    opacity: {
      0: '0',
      5: '0.05',
      10: '0.1',
      20: '0.2',
      25: '0.25',
      30: '0.3',
      40: '0.4',
      50: '0.5',
      60: '0.6',
      70: '0.7',
      75: '0.75',
      80: '0.8',
      90: '0.9',
      95: '0.95',
      100: '1',
    },
    order: {
      first: '-9999',
      last: '9999',
      none: '0',
      1: '1',
      2: '2',
      3: '3',
      4: '4',
      5: '5',
      6: '6',
      7: '7',
      8: '8',
      9: '9',
      10: '10',
      11: '11',
      12: '12',
    },
    padding: ({ theme }) => theme('spacing'),
    placeholderColor: ({ theme }) => theme('colors'),
    placeholderOpacity: ({ theme }) => theme('opacity'),
    outlineColor: ({ theme }) => theme('colors'),
    outlineOffset: {
      0: '0px',
      1: '1px',
      2: '2px',
      4: '4px',
      8: '8px',
    },
    outlineWidth: {
      0: '0px',
      1: '1px',
      2: '2px',
      4: '4px',
      8: '8px',
    },
    ringColor: ({ theme }) => ({
      DEFAULT: theme('colors.blue.500', '#3b82f6'),
      ...theme('colors'),
    }),
    ringOffsetColor: ({ theme }) => theme('colors'),
    ringOffsetWidth: {
      0: '0px',
      1: '1px',
      2: '2px',
      4: '4px',
      8: '8px',
    },
    ringOpacity: ({ theme }) => ({
      DEFAULT: '0.5',
      ...theme('opacity'),
    }),
    ringWidth: {
      DEFAULT: '3px',
      0: '0px',
      1: '1px',
      2: '2px',
      4: '4px',
      8: '8px',
    },
    rotate: {
      0: '0deg',
      1: '1deg',
      2: '2deg',
      3: '3deg',
      6: '6deg',
      12: '12deg',
      45: '45deg',
      90: '90deg',
      180: '180deg',
    },
    saturate: {
      0: '0',
      50: '.5',
      100: '1',
      150: '1.5',
      200: '2',
    },
    scale: {
      0: '0',
      50: '.5',
      75: '.75',
      90: '.9',
      95: '.95',
      100: '1',
      105: '1.05',
      110: '1.1',
      125: '1.25',
      150: '1.5',
    },
    scrollMargin: ({ theme }) => ({
      ...theme('spacing'),
    }),
    scrollPadding: ({ theme }) => theme('spacing'),
    sepia: {
      0: '0',
      DEFAULT: '100%',
    },
    skew: {
      0: '0deg',
      1: '1deg',
      2: '2deg',
      3: '3deg',
      6: '6deg',
      12: '12deg',
    },
    space: ({ theme }) => ({
      ...theme('spacing'),
    }),
    stroke: ({ theme }) => theme('colors'),
    strokeWidth: {
      0: '0',
      1: '1',
      2: '2',
    },
    textColor: ({ theme }) => theme('colors'),
    textDecorationColor: ({ theme }) => theme('colors'),
    textDecorationThickness: {
      auto: 'auto',
      'from-font': 'from-font',
      0: '0px',
      1: '1px',
      2: '2px',
      4: '4px',
      8: '8px',
    },
    textUnderlineOffset: {
      auto: 'auto',
      0: '0px',
      1: '1px',
      2: '2px',
      4: '4px',
      8: '8px',
    },
    textIndent: ({ theme }) => ({
      ...theme('spacing'),
    }),
    textOpacity: ({ theme }) => theme('opacity'),
    transformOrigin: {
      center: 'center',
      top: 'top',
      'top-right': 'top right',
      right: 'right',
      'bottom-right': 'bottom right',
      bottom: 'bottom',
      'bottom-left': 'bottom left',
      left: 'left',
      'top-left': 'top left',
    },
    transitionDelay: {
      75: '75ms',
      100: '100ms',
      150: '150ms',
      200: '200ms',
      300: '300ms',
      500: '500ms',
      700: '700ms',
      1000: '1000ms',
    },
    transitionDuration: {
      DEFAULT: '150ms',
      75: '75ms',
      100: '100ms',
      150: '150ms',
      200: '200ms',
      300: '300ms',
      500: '500ms',
      700: '700ms',
      1000: '1000ms',
    },
    transitionProperty: {
      none: 'none',
      all: 'all',
      DEFAULT:
        'background-color, border-color, color, fill, stroke, opacity, box-shadow, transform, filter, backdrop-filter',
      colors: 'background-color, border-color, color, fill, stroke',
      opacity: 'opacity',
      shadow: 'box-shadow',
      transform: 'transform',
    },
    transitionTimingFunction: {
      DEFAULT: 'cubic-bezier(0.4, 0, 0.2, 1)',
      linear: 'linear',
      in: 'cubic-bezier(0.4, 0, 1, 1)',
      out: 'cubic-bezier(0, 0, 0.2, 1)',
      'in-out': 'cubic-bezier(0.4, 0, 0.2, 1)',
    },
    translate: ({ theme }) => ({
      ...theme('spacing'),
      '1/2': '50%',
      '1/3': '33.333333%',
      '2/3': '66.666667%',
      '1/4': '25%',
      '2/4': '50%',
      '3/4': '75%',
      full: '100%',
    }),
    width: ({ theme }) => ({
      auto: 'auto',
      ...theme('spacing'),
      '1/2': '50%',
      '1/3': '33.333333%',
      '2/3': '66.666667%',
      '1/4': '25%',
      '2/4': '50%',
      '3/4': '75%',
      '1/5': '20%',
      '2/5': '40%',
      '3/5': '60%',
      '4/5': '80%',
      '1/6': '16.666667%',
      '2/6': '33.333333%',
      '3/6': '50%',
      '4/6': '66.666667%',
      '5/6': '83.333333%',
      '1/12': '8.333333%',
      '2/12': '16.666667%',
      '3/12': '25%',
      '4/12': '33.333333%',
      '5/12': '41.666667%',
      '6/12': '50%',
      '7/12': '58.333333%',
      '8/12': '66.666667%',
      '9/12': '75%',
      '10/12': '83.333333%',
      '11/12': '91.666667%',
      full: '100%',
      screen: '100vw',
      min: 'min-content',
      max: 'max-content',
      fit: 'fit-content',
    }),
    willChange: {
      auto: 'auto',
      scroll: 'scroll-position',
      contents: 'contents',
      transform: 'transform',
    },
    zIndex: {
      auto: 'auto',
      0: '0',
      10: '10',
      20: '20',
      30: '30',
      40: '40',
      50: '50',
    },
  },
  variantOrder: [
    'first',
    'last',
    'odd',
    'even',
    'visited',
    'checked',
    'empty',
    'read-only',
    'group-hover',
    'group-focus',
    'focus-within',
    'hover',
    'focus',
    'focus-visible',
    'active',
    'disabled',
  ],
}