DEV Community: Garrick Crouch

The Ultimate Guide to Trunk-Based Next.js Monorepo Deployments on Vercel

Garrick Crouch — Wed, 18 Mar 2026 15:38:22 +0000

If you are running a modern Next.js application inside a monorepo (like Turborepo), Vercel is undoubtedly the best place to host it. However, if your team practices strict trunk-based development—where main is your single source of truth for all environments—Vercel's default Git integration can feel a bit restrictive.

Many teams end up creating multiple separate Vercel projects (e.g., acme-web-staging and acme-web-prod) to handle different environments. This creates massive overhead: drifting environment variables, duplicated build minutes, and messy webhook configurations.

In this guide, we are going to configure a single Vercel project to perfectly support trunk-based development.

The Goal:

PRs: Automatically build and deploy to a random preview URL.
Staging: Automatically build and deploy to our staging domains (stage.acme.app) whenever a PR merges into main.
Production: Manually triggered via GitHub Actions, building directly from main and deploying to our production domains (acme.app).

Here is the exact blueprint to set this up, including the gotchas that usually trip teams up.

---

Phase 1: Decoupling main from Production

By default, Vercel assumes your default branch (main) is your Production environment. Any push to main instantly updates your live production URLs. To make the main branch our Staging environment, we have to trick Vercel into demoting it.

The Gotcha: You cannot assign a "Production Branch" in Vercel unless that branch actually exists in your GitHub repository.

Open your local terminal and create a dummy branch: git checkout -b vercel-do-not-deploy
Push this empty branch to GitHub: git push origin vercel-do-not-deploy
Go to your Vercel Project Settings > Git.
Change the Production Branch from main to vercel-do-not-deploy. Save the changes.
(Optional but recommended): Delete any vercel.json files that have "main": false deployment overrides. We want Vercel to auto-deploy main now.

Result: Vercel now considers main to be a Preview branch. Merges to main will no longer touch your live production users.

---

Phase 2: Domain Routing

Now that main is technically a Preview environment, we need to wire up our custom staging domains so they update automatically on merge.

Go to Project Settings > Domains.
Add your production domains (e.g., acme.app, dashboard.acme.app). Ensure their Git Branch mapping is left blank or points to your dummy production branch. These are now locked to Production.
Add your staging domains (e.g., stage.acme.app, stage.dashboard.acme.app).
Click Edit on your staging domains and set the Git Branch explicitly to main.

Result: When a PR merges, Vercel finishes the Preview build on main and automatically points stage.acme.app to that exact artifact.

---

Phase 3: Scoping Environment Variables

Because Next.js bakes NEXT_PUBLIC_ variables into the frontend code at build time, environment variable hygiene is critical.

The Gotcha: Leaving production variables set to "All Environments" is a massive security risk. If a staging variable is missing, Vercel falls back to the production key, and your staging app might accidentally process live Stripe transactions or hit production databases.

Go to Project Settings > Environment Variables.
Lock down Production: Edit every production variable (API keys, DB URLs) and uncheck "Preview" and "Development". Leave only "Production" checked.
Scope Staging to main: Add your staging variables. Check the Preview box. A dropdown will appear asking for a specific branch. Type exactly main.
Handle PR Previews: If you want PRs to use staging data, add the staging variables again, check Preview, but leave the branch selection completely empty. This acts as the fallback for any branch that isn't main.

---

Phase 4: The CI/CD Pipeline (GitHub Actions)

Since main is no longer the Production branch, a standard Vercel Webhook triggered against main will only build stage. To trigger a true Production build directly from main, we must use the Vercel CLI inside GitHub Actions.

The Gotcha: Do not use a sparse checkout to only pull your Next.js app folder (apps/acme-web). Vercel is heavily optimized for monorepos (like Turborepo). If you don't hand Vercel the entire monorepo with the root package.json and lockfiles, the build will crash because it cannot resolve your shared workspaces (e.g., @acme/ui, @acme/tailwind-config).

Note: You can use sparse checkout with file path directives but it’s typically not needed.

First, add these two Repository Variables to GitHub:

VERCEL_ORG_ID: Found in your Vercel Team Settings.
VERCEL_PROJECT_ID: Found in your Vercel Project Settings.

Second, add this Repository Secret to Github:

VERCEL_TOKEN: Generated from your Vercel Personal Account settings.

Then, create this Workflow Dispatch file (.github/workflows/manual-deploy-vercel.yml):

name: Manual Vercel Deploy  
on:  
  workflow_dispatch:  
    inputs:  
      environment:  
        description: 'Which environment do you want to deploy?'  
        required: true  
        default: 'production'  
        type: choice  
        options:  
          - production  
          - staging

env:  
  VERCEL_ORG_ID: ${{ vars.VERCEL_ORG_ID }}  
  VERCEL_PROJECT_ID: ${{ vars.VERCEL_PROJECT_ID }}

jobs:  
  deploy:  
    runs-on: ubuntu-latest  
    steps:  
      - name: Checkout code  
        uses: actions/checkout@v4  
        with:  
          ref: main 

      - name: Install Vercel CLI  
        run: npm install --global vercel@latest

      # --- STAGING DEPLOYMENT STEPS ---  
      - name: Deploy to Vercel (Staging)  
        if: github.event.inputs.environment == 'staging'  
        run: |  
          # Pass the Git SHA so our app knows its version  
          DEPLOY_URL=$(vercel deploy --yes --token=${{ secrets.VERCEL_TOKEN }} --build-env APP_COMMIT_SHA=${{ github.sha }})  
          echo "Successfully deployed to: $DEPLOY_URL"

          # Explicitly alias our staging domains to this manual build  
          DOMAINS=("stage.acme.app" "stage.dashboard.acme.app" "stage.api.acme.app")  
          for DOMAIN in "${DOMAINS[@]}"; do  
            vercel alias set $DEPLOY_URL $DOMAIN --token=${{ secrets.VERCEL_TOKEN }}  
          done

      # --- PRODUCTION DEPLOYMENT STEPS ---  
      - name: Deploy to Vercel (Production)  
        if: github.event.inputs.environment == 'production'  
        run: vercel deploy --prod --yes --token=${{ secrets.VERCEL_TOKEN }} --build-env APP_COMMIT_SHA=${{ github.sha }}

---

Phase 5: Pro-Tips & Quality of Life

1. Injecting the Commit SHA as an HTTP Header

Ever wonder if your deployment actually went through? You can permanently stamp your Next.js builds with their exact Git commit hash.

In your next.config.js:


// Grab Vercel's automatic PR variable, or the one we passed via CLI  
const commitSha = process.env.VERCEL_GIT_COMMIT_SHA || process.env.APP_COMMIT_SHA || 'unknown';  
const shortSha = commitSha.length > 7 ? commitSha.substring(0, 7) : commitSha;

/** @type {import('next').NextConfig} */  
const nextConfig = {  
  async headers() {  
    return [  
      {  
        source: '/:path*',  
        headers: [{ key: 'X-App-Version', value: shortSha }],  
      },  
    ];  
  },  
};  
module.exports = nextConfig;

Now, just open the Network tab in your browser, click the document request, and look for X-App-Version: 1a2b3c4.

2. Sentry Environments

You do not need separate Sentry DSNs for Staging and Production. Leave your NEXT_PUBLIC_SENTRY_DSN as an "All Environments" variable in Vercel. Instead, rely on a variable like NEXT_PUBLIC_VERCEL_ENV to pass the environment tag into your Sentry.init() call. This keeps all your errors in one Sentry project, perfectly filterable by environment.

Creating Data Structures with Array.reduce()

Garrick Crouch — Wed, 20 Oct 2021 00:05:06 +0000

I recently saw an older youtube video on using array.reduce to build data structures on the fly in ways that you may find surprising or unintuitive. Normally we always think of reduce when it comes to doing math on array elements or something similar, and while that is a great use case, lets explore some of the more unique ways leverage this array method.

Create An Object From An Array

To do this you could use any old loop, but lets say you need to build an object of objects, with the properties equal to one of the objects property values, eg.

// this is the data we have...
const data = [
  {
    id: 1,
    name: 'New Post',
    author: 'Jeff',
    date: '2021-05-01'
  },
  {
    id: 2,
    name: 'Newer Post',
    author: 'Sabrina',
    date: '2021-05-02'
  },
  {
    id: 3,
    name: 'Newest Post',
    author: 'Mike',
    date: '2021-05-02'
  },
  {
    id: 4,
    name: 'Fourth Post',
    author: 'Mike',
    date: '2021-03-02'
  },
  {
    id: 5,
    name: 'Fifth Post',
    author: 'Sabrina',
    date: '2021-08-09'
  }
];

// this is the structure we want...
const authors = {
  jeff: {
    posts: [
      {
        id: 1,
        title: 'Post Name',
        created_at: '2021-05-01'
      }
    ]
  },
  sabrina: {
    posts: [ ...posts ]
  },
  mike: {
    posts: [ ...posts ]
  },
}

Basically we want build an object containing author objects that each contain an array of any posts they've written. A map won't do because we don't really want to return an array of course (contrived on purpose for the example) and we would like to easily aggregate them into the appropriate arrays keyed by the name. Also the specification says we should rename the date to created_at and name to title.

So how could we reduce this array to the data structure specified in a functional way and it make sense to the reader of our code?

Remember that array.reduce will return any value you want it to...aha...so we want to return an object.

reduce((previousValue, currentValue) => { ... }, initialValue)

This above is the function we'll use. Notice the initialValue argument. That'll set the stage for our returned value.

Let's Reduce

(data || []).reduce((acc, curr) => ({}), {});

This is our basic setup. We'll pass acc or the accumulated value and the curr or current array element into the callback, returning an expression, which is an object literal. Our default value you may notice is an empty object.

const result = (data || []).reduce((acc, curr) => ({
  ...acc,
  [curr?.author?.toLowerCase()]: {
    ...acc[curr?.author?.toLowerCase()],
    posts: [
      ...(acc[curr?.author?.toLowerCase()]?.posts || []),
      {
        id: curr?.id,
        title: curr?.name,
        created_at: curr?.date
      }
    ]
  }
}), {});

This is our workhorse above. We'll step through each stage of working with the data. It's done in a functional way meaning we're copying data, never overwriting it.

First, we spread the value of `acc` into the object that we're returning

const result = data.reduce((acc, curr) => ({
  ...acc,
  // more stuffs
}), {});

Second, we'll use the computed value to set our property name of an author

const result = data.reduce((acc, curr) => ({
  ...acc,
  [curr?.author?.toLowerCase()]: {
    // more stuffs
  }
}), {});

This way it ensures we're preserving any objects that don't match the computed property name in the carry. We use the toLowerCase bc the spec says it wants lowercase author names as the object property.

Third, we'll set and spread on the posts property of a computed name author object

const result = data.reduce((acc, curr) => ({
  ...acc,
  [curr?.author?.toLowerCase()]: {
    ...acc[curr?.author?.toLowerCase()],
    posts: [
     // we'll use a short circuit since the posts property won't e 
     // exist on the first of any given author, just spread an 
     // empty array
      ...(acc[curr?.author?.toLowerCase()]?.posts || []),
     // add our object with the specified data mapping
      {
        id: curr?.id,
        title: curr?.name,
        created_at: curr?.date
      }
    ]
  }
}), {});

Success

If we serialize the result and pretty print it we'd get....

{
    "jeff": {
        "posts": [
            {
                "id": 1,
                "title": "New Post",
                "created_at": "2021-05-01"
            }
        ]
    },
    "sabrina": {
        "posts": [
            {
                "id": 2,
                "title": "Newer Post",
                "created_at": "2021-05-02"
            },
            {
                "id": 5,
                "title": "Fifth Post",
                "created_at": "2021-08-09"
            }
        ]
    },
    "mike": {
        "posts": [
            {
                "id": 3,
                "title": "Newest Post",
                "created_at": "2021-05-02"
            },
            {
                "id": 4,
                "title": "Fourth Post",
                "created_at": "2021-03-02"
            }
        ]
    }
}

Please leave me any thoughts on optimization or better ways to accomplish the given task. The primary focus of this is to get people thinking about array.reduce in interesting ways but I always enjoy learning new or better ways to do stuff.

Optimize Renders in React.js Function Components

Garrick Crouch — Mon, 18 Oct 2021 01:55:53 +0000

You may come across issues in react where transitions and animations fire more than you'd like and in some cases it may be hard to control those renders, especially when dealing with libraries. In my case I had chart animations that would fire when the component was rendered and there wasn't any easy way to throttle that or prevent the duplicate transitions.

The docs point out that

This method only exists as a performance optimization. Do not rely on it to “prevent” a render, as this can lead to bugs.

Speaking of https://reactjs.org/docs/react-api.html#reactmemo.

This is a memoization technique not afforded by component should update since we're not using class components. To the react docs point it can be buggy, but in my case it works wonders and prevents rampant animations.

import * as React from 'react';

export default React.memo(function MyComponent({
  data,
  options
}) {

  const [chartData, setChartData] = React.useState(() => {
    // some advanced filtering for the chart
    return (data || []).filter(item => item !== item + 1);
  });

  return (
    <Chart {...options} {...chartData} />
  );
});

In this hypothetical chart component, if the parent would render, well the myComponent would rerender, which normally isn't an issue, but in our case the chart has transitions on it that trigger on every render and we cannot modify that API because it's a 3rd party. This will provide and easy way for us to still use hooks and only have the myComponent to render once, which will run our filter logic on the data and allow a performance optimization as well possibly.

Important note: hooks still work as you'd expect in a memoized component so you can use them and get renders on state change.

I think the majority use case is the intended of the react team which is performance for unnecessary renders, but this works perfectly for throttling renders in the case of UI side effects.

Create a Custom React.js Hook to Get Subdomains

Garrick Crouch — Sun, 17 Oct 2021 01:30:02 +0000

Often times it's extremely useful to be able to easily parse the hostname or domain parts of your website. The use cases are many but we'll just look at how to make a react hook to help us get subdomain info for use in our application.

We'll use the Web API window.location.hostname. It'll return the string representation of the current host.
https://developer.mozilla.org/en-US/docs/Web/API/Location/hostname

import * as React from 'react';

export default function useSubdomain(position = 0) {

  const [subdomain] = React.useState(() => {
    try {
      return window?.
        location?.
        hostname?.
        split('.')[position];
    } catch (err) {
      console.error(err.message);
    }
  });

  return subdomain;
}

You can see we just create an array from the hostname parts based on the . as a delimiter, and access the array index you pass in as the argument for the call to the hook.

We could take it a step further and create a function to run this logic at any time, but for now let's just assume that we only want this to run once as we call it, so we would use it like this:

export default function MyComponent() {

  const subdomain = useSubdomain(0);

  return (
    <h1>
      The website subdomain is {subdomain}
    </h1>
  );
}

You could add checks in to make sure you're actually on a subdomain as well, and also guards for www.

What Does 'queue:listen' actually do in Laravel?

Garrick Crouch — Thu, 14 Oct 2021 20:59:37 +0000

When using the queue command in Laravel you may have noticed that you can do queue:work or queue:listen. The queue:listen command in fact runs this:

php artisan queue:work --once --name=default --queue=default --backoff=0 --memory=128 --sleep=3 --tries=1

As you can see they're the exact same two commands under the hood. The listen just sets some simple options for you, like rebooting the framework on every job, so it makes development easier.

Simplifying Hostnames in Docker Compose for Laravel Apps

Garrick Crouch — Wed, 13 Oct 2021 04:00:04 +0000

You may come across weird situations in development using Docker, specifically docker compose, and the way networking is done. I use WSL2 with Docker Desktop to make my life easy and recently had to figure out aliases for hostnames so that containers could reference each other without an ip address or the service name, i.e. while using an http client to make a request from service a to service b.

Hopefully this will shed some light for people or just make it easier to use docker in general which is a great tech for development.

this is not intended for production or staging use. for development purposes only

Setting Up

I'll assume you have 3 laravel apps, and that NGINX is your proxy server (web server). That means we'll use PHP-FPM since all requests to your services are proxy passed from NGINX to the PHP-FPM service for the given application. FPM then runs the actual code and returns the response to NGINX.

We'll add in an assumed database service just so our docker-compose file looks complete. We'll walk through each part of the compose file paying more attention to the networking portions.

Lets pretend we have 3 laravel apps:
one each for management, payroll, and marketing.

services:
  management:
    build:
      context: .
    container_name: management
    image: laravel-example/management
    restart: unless-stopped
    tty: true
    working_dir: /var/www/management
    volumes:
      - ./:/var/www/management
    networks:
      - laravel-example
  payroll:
    build:
      context: ../payroll
    container_name: payroll
    image: laravel-example/payroll
    restart: unless-stopped
    tty: true
    working_dir: /var/www/payroll
    volumes:
      - ../payroll:/var/www/payroll
    networks:
      - laravel-example
  marketing:
    build:
      context: ../marketing
    container_name: marketing
    image: laravel-example/marketing
    restart: unless-stopped
    tty: true
    working_dir: /var/www/marketing
    volumes:
      - ../marketing:/var/www/marketing
    networks:
      - laravel-example
  nginx:
    image: nginx:latest
    container_name: nginx
    restart: unless-stopped
    tty: true
    ports:
      - 80:80
      - 443:443
    volumes:
      - ../payroll:/var/www/payroll
      - ../marketing:/var/www/marketing
      - ./:/var/www/management
      - ./build/dev/nginx/conf:/etc/nginx/conf.d
      - ./build/dev/nginx/certs/:/etc/nginx/ssl
    networks:
      laravel-example:
        aliases:
          - payroll.bigcorp.test
          - marketing.bigcorp.test
          - management.bigcorp.test
    depends_on:
      - marketing
  mariadb:
    image: mariadb:10.2
    container_name: mariadb
    ports:
      - 33065:3306
    environment:
      MYSQL_ROOT_PASSWORD: "password"
      MYSQL_DATABASE: "your_db"
      MYSQL_USER: "root"
      MYSQL_PASSWORD: "password"
      MYSQL_ALLOW_EMPTY_PASSWORD: "yes"
    volumes:
      - laravel-mariadb:/var/lib/mysql
    networks:
      - laravel-example
    restart: on-failure
    healthcheck:
      test: ["CMD", "mysqladmin", "ping"]
networks:
  laravel-example:
    driver: bridge
    external: false
    name: laravel-example
volumes:
  laravel-mariadb:
    driver: local

The yaml file may seem large, but it's actually fairly easy to break down service by service and understand what each part does. Our main concern for this post is understanding the hostname aliases. Normally docker will assign an ip to a service based on its internal networking, so you'll never have the same ip address for a given service on a given build or run. Services can "talk" to each other by their name since docker will resolve the service name to an ip address. Where this breaks down is a service making an http request within the docker network to another service. The call will fail since the hostname will not resolve, there is no DNS server of course. To fix this we need to look at two things:

Our networks key in the compose file says "make me a network named laravel-example, and use the bridge driver, this is not an external (already existing network).
Each of our services is built in this network. The key to making the hostname resolve within docker like DNS would is the networks key in our NGINX service

networks:
      laravel-example:
        aliases:
          - payroll.bigcorp.test
          - marketing.bigcorp.test
          - management.bigcorp.test

Basically we're just saying, "resolve any of these hostnames to the NGINX service". This works because of course all requests to NGINX get passed to server blocks that are proxied to a PHP-FPM service. We can look at how that works in a later post.

Hopefully this sheds some light on dockers networking in a practical way for development purposes.

Opinionated Project Structures in React.js without a Framework

Garrick Crouch — Fri, 08 Oct 2021 03:12:46 +0000

After using React professionally for nearly two years, I've finally settled on sensible ways to structure or compose applications in React. This strictly applies to using "vanilla" React, not any sort of framework, ecosystem, or starter environment. I say all that to say this, there's a million ways to structure a react app, and none of them are wrong on their face, but do they really make sense?

design systems shouldn't dictate project structure, focus on composability both in your system architecture and components

I've spent lots of time studying different ways to structure a react app and they often felt disjointed or opinionated in ways that I think a person would have a hard time justifying or explaining why it's structured that way. At the point of working on 10+ react apps, I finally asked myself, "why do we structure these apps the way we do? and can I give at least one reason for every folder or file being where it is that isn't arbitrary."

Studying different methods of application structure not just revolving around react but software in general, I finally decided to plunge into refactoring applications at work and being able to say, "this is why these folders are where they are, and this is why I think it's a good idea."

I settled on a project structure that tries to embody the word "responsibility". I realized that in a UI library, it's very easy to cram everything into messy hierarchies or paths. Basically, this thing is inside this thing is inside this thing and so on.

One final note before laying out the structure and the why for, testing is crucial and is the only first class file, meaning it can live where you want it to based on needs, since many people need to test various parts of their app in widely different ways since unit, feature, integration, and browser testing can be a wild place to wander.

The Structure - We Make Assumptions

src/
__tests__/
-common/
-components/
-context/
-forms/
-hooks/
-layouts/
-pages/
-routes/
-services/
-tables/
-utils/
--constants.jsx
--helpers/
-App.jsx

I'll step through each directory and explain the thought behind its placement and its "responsibility". This is after all, entirely about inferring structure based on responsibility.

src/ - just simply what contains the app in total.
tests - would contain feature and integration tests for me but may also contain your unit tests if that is what the team needs or likes (no opinion beyond you need testing)
common - this houses any component that is used more than once in the app with the potential of living in your own design system or external library. (excludes other components we'll go over). Be cautious about abstracting too early because refactoring is very easy using this structure. Considering that everything has its "place", we need good reason to say this component is common to the app yet doesn't have behavior which determines it to belong in another directory.
components - houses one offs or atoms, as well as wrapper, or container components. These will usually have business logic, hoisted state, and provide a place that atoms are composed and used with each other.
context - any context providers. these contain your global state, extended stores, and dependency injection components.
forms - houses any form element component in full. Forms make up the majority of data driven applications so its important to either reuse them in smart ways or keep track of their namespaces.
hooks - any custom hooks you may need to wrap the native react lifecycle hooks.
layouts - any structured or skeleton like html templates. Think navs, footers, sidebars, dashboard wrappers, content containers. Usually encapsulates exactly what the name implies, the page layout of your app.
pages - any component that is routed to. very simple concept to apply and maintain. if it is a routed component, it is a page. Then you take it from there with how you compose pages inside layouts or vice versa. Match the page name to the route which should match the URL. It's a document location so keep it simple and absolutely consistent. /dashboard would be Dashboard, /users/:id would be User, /users would be Users, etc. Follow namespacing rules for nested URL structure. /users/:id/profile would be UserProfile.
routes - route declaration files, protected and role based routing. These routes will only ever point to a page. Depending on what router you use, determines how you compose or use the route definitions.
services - links to the outside world via http, ws, and any 3rd party integrations. Defines the network clients.
tables - the other half of data driven applications are tables. namespaced and composed of only ever a table element integrating other components as needed from common/components.
utils - contains a constants page, and a helpers dir. constants are meant to be used throughout the app whether environmental or domain driven. The helpers dir is non react helper functions.

Individual Component Hierarchy

components/
YourComponent/
--index.jsx
--test.jsx

The rule to follow is that every component only ever contains an index.jsx file that exports itself as the default named function. This allows for extremely easy colocation of unit tests per component and if you need it, styles as well. I personally avoid CSS in JS due to responsibility, but you may favor that as a development habit or your build tool may necessitate it, though I prefer to be unbound by structuring my app based on the build tool.

Be cautious about deeply nesting inside components, when you find yourself nesting too much take the time to think about how you could compose it to not nest at all or would it serve better at being pulled into atoms.

Takeaway

Take the time to understand why code locates where it does and it'll become second nature to build systems that follow structured approaches. Reducing cognitive overhead is crucial to being effective in software. Complexity in structure or the lack of structure does not help. Focus on composability based on responsibility.

With a structure like this it is extremely easy to refactor an application when you see code bloat or code rot. Focusing on responsibility means you reduce spaghetti since component dependencies are decoupled more and more.

Using Custom HTML Attributes To Help Track Clicks With Google Analytics

Garrick Crouch — Wed, 29 Jan 2020 05:37:25 +0000

We will be utilizing a simple event listener to help us track when elements are clicked on our websites. This can give us a free birds-eye view of how people are interacting with our elements! Google Analytics will do all the heavy lifting, we just need to initialize a simple script and stick to proper markup. The scope of this article is not using Google Analytics, rather getting relevant data to it!
More on installing GA here: [https://developers.google.com/analytics/devguides/collection/gtagjs]

Here is the problem! We have added a phone number as a button to the header template of our site and we want to know if it is leading to calls or if other buttons containing our company number are getting all the attention. We can do this easily by adding some basic markup and our script.

First the HTML.

For every element we want to track clicks on we will give it the class click-tracking-ga and a custom attribute defined as data-ga-id. Our markup on elements we want to track should always follow this pattern:

<a class="click-tracking-ga" data-ga-id="Header Phone Button" href="tel:1-855-555-5555" type="button">Click To Call Now!</a>

Next lets look at our JavaScript:

/* Send click event to Google Analytics via custom attribute tags
 * @param  {Object} e Event object
 */

document.addEventListener('click', (e) => {
    // check that our element has the tracking class, return early if it doesn't
    if (!e.target.classList.contains('click-tracking-ga')) {
        return;
    }
    //use the gtag function passing the event target elements attribute tag we generated on the HTML
    //the 'data-ga-id' will be the same name you use in GA to flag these clicks
    //pass the action as 'Clicked', can be whatever you set up but that is descriptive
    gtag('event',
        'clicks', {
            event_category: `${e.target.getAttribute('data-ga-id')}`,
            event_action: 'Clicked'
        });
});

This event handler returns early if the class click-tracking-ga is not present but if it is we call the gtag() function, passing in the data-ga-id of the event target element. It is worth noting that our event_action: is predefined to Clicked which is important and should not be changed.

Now we will review our setup in Google Analytics to register this event.

First go to your admin panel for the domain property you want to track.

Next click the Goals under the View tab

Next we will make a new goal, using custom

We will name our goal with the string from our data-ga-id
Header Phone Button, select 'Event', and hit continue.

Next we have to define our parameters. This is very important we only fill in the first two fields. In the first field we enter in our data-ga-id, which is
Header Phone Button in the 'Category' field. Next input Clicked in your 'Action' field. Then hit save and you're done!

Now you can view this event from within GA from many different views including real-time. Remember to adjust to the 'Today' time view for goals or events or you will not see the for another 24-48 hours!