DEV Community: Andrew Ross

Taming the Interactions API in the @google/genai SDK

Andrew Ross — Thu, 25 Dec 2025 06:58:48 +0000

Fixing TypeScript Inference in Google's Gemini Interactions API

Google released beta support for a new Interactions API on 2025-12-11, described as "a unified interface for interacting with Gemini models and agents". The latest @google/genai SDK (v1.34.0 as of writing) surfaces this beta API, unlocking preview support for Deep Research tasks with background polling.

There's just one problem: you can't use it safely or sanely in TypeScript.

The Problem isn't Verbosity, it's Impossibility

When unknown appears in a union type, TypeScript doesn't treat it as "one possible type among many." It treats it as "this could be anything," which collapses inference entirely.

// What Google ships:
declare interface MCPServerToolResultContent {
  result: MCPServerToolResultContent.Items | unknown | string;
  // ...
}

declare namespace MCPServerToolResultContent {
  interface Items {
    items?: Array<string | InteractionsAPI.ImageContent | unknown>;
  }
}

// What TypeScript infers:
result: null | {}  // 💀 completely unusable

You can't narrow into result.items. You can't check typeof result === "string". The type system has given up. Your only options:

Unsafe assertions everywhere: (result as MCPServerToolResultContent.Items).items
Patch the SDK to remove unknown from unions

Option 1 defeats the purpose of TypeScript. Option 2 is what I'm providing below.

The Patch: Removing `unknown` From Union Types

Before any type utilities matter, you need a working foundation. The @google/genai SDK (applicable to v1.34.0) ships with unknown polluting critical union types, making safe narrowing impossible.

Applying the Patch

Using pnpm:

# Initialize the patch (creates a temporary editable copy)
pnpm patch @google/genai

Output:

Patch: You can now edit the package at:

  /your-project/node_modules/.pnpm_patches/@google/genai@1.34.0

To commit your changes, run:

  pnpm patch-commit '/your-project/node_modules/.pnpm_patches/@google/genai@1.34.0'

Navigate to that directory, apply the edits to dist/node/node.d.ts (detailed below), then commit:

pnpm patch-commit '/your-project/node_modules/.pnpm_patches/@google/genai@1.34.0'

Or grab the patch directly:

curl -o patches/@google__genai.patch \
  https://gist.githubusercontent.com/DopamineDriven/7a826cae206bc28c2c620d1eee0dea9e/raw/@google__genai.patch

Then add to your pnpm-workspace.yaml:

patchedDependencies:
  '@google/genai': patches/@google__genai.patch

Verifying the Patch

After committing, your pnpm-workspace.yaml should include the patchedDependencies entry above, and patches/@google__genai.patch will exist in your project root. This file is version-controlled—commit it so your team (and CI) gets the fix automatically.

What the Patch Fixes

The patch targets 8 locations across dist/node/node.d.ts (~8,500 LOC):

Line	Type	Change
1824	`ContentDelta.FunctionResultDelta.Items`	`Array<string \| ImageContent \| unknown>` → `Array<string \| ImageContent>`
1917	`ContentDelta.MCPServerToolResultDelta.Items`	`Array<string \| ImageContent \| unknown>` → `Array<string \| ImageContent>`
3867	`FunctionResultContent.result`	`Items \| unknown \| string` → `Items \| string`
3881	`FunctionResultContent.Items`	`Array<string \| ImageContent \| unknown>` → `Array<string \| ImageContent>`
5410	`HttpResponse.json()`	`Promise<unknown>` → `Promise<T = unknown>` (adds generic)
6997	`MCPServerToolResultContent.result`	`Items \| unknown \| string` → `Items \| string`
7011	`MCPServerToolResultContent.Items`	`Array<string \| ImageContent \| unknown>` → `Array<string \| ImageContent>`
8560	`SchemaUnion`	`Schema \| unknown` → `Schema`

The Full Patch File

Click to Expand

diff --git a/dist/node/node.d.ts b/dist/node/node.d.ts
index bc7365e795551b19fe390a25421e2611de75b168..5090f992b2deece3e098c311e06eee49cbda7db9 100644
--- a/dist/node/node.d.ts
+++ b/dist/node/node.d.ts
@@ -1821,7 +1821,7 @@ declare namespace ContentDelta {
     }
     namespace FunctionResultDelta {
         interface Items {
-            items?: Array<string | InteractionsAPI.ImageContent | unknown>;
+            items?: Array<string | InteractionsAPI.ImageContent>;
         }
     }
     interface CodeExecutionCallDelta {
@@ -1914,7 +1914,7 @@ declare namespace ContentDelta {
     }
     namespace MCPServerToolResultDelta {
         interface Items {
-            items?: Array<string | InteractionsAPI.ImageContent | unknown>;
+            items?: Array<string | InteractionsAPI.ImageContent>;
         }
     }
     interface FileSearchResultDelta {
@@ -3864,7 +3864,7 @@ declare interface FunctionResultContent {
     /**
      * The result of the tool call.
      */
-    result: FunctionResultContent.Items | unknown | string;
+    result: FunctionResultContent.Items | string;
     type: 'function_result';
     /**
      * Whether the tool call resulted in an error.
@@ -3878,7 +3878,7 @@ declare interface FunctionResultContent {

 declare namespace FunctionResultContent {
     interface Items {
-        items?: Array<string | InteractionsAPI.ImageContent | unknown>;
+        items?: Array<string | InteractionsAPI.ImageContent>;
     }
 }

@@ -5407,7 +5407,7 @@ export declare class HttpResponse {
      */
     responseInternal: Response;
     constructor(response: Response);
-    json(): Promise<unknown>;
+    json<T = unknown>(): Promise<T>;
 }

 /** An image. */
@@ -6994,7 +6994,7 @@ declare interface MCPServerToolResultContent {
     /**
      * The result of the tool call.
      */
-    result: MCPServerToolResultContent.Items | unknown | string;
+    result: MCPServerToolResultContent.Items | string;
     type: 'mcp_server_tool_result';
     /**
      * Name of the tool which is called for this specific tool call.
@@ -7008,7 +7008,7 @@ declare interface MCPServerToolResultContent {

 declare namespace MCPServerToolResultContent {
     interface Items {
-        items?: Array<string | InteractionsAPI.ImageContent | unknown>;
+        items?: Array<string | InteractionsAPI.ImageContent>;
     }
 }

@@ -7076,7 +7076,7 @@ export declare enum MediaResolution {
  * This type contains `RequestInit` options that may be available on the current runtime,
  * including per-platform extensions like `dispatcher`, `agent`, `client`, etc.
  */
-declare type MergedRequestInit = RequestInits & 
+declare type MergedRequestInit = RequestInits &
 /** We don't include these in the types as they'll be overridden for every request. */
 Partial<Record<'body' | 'headers' | 'method' | 'signal', never>>;

@@ -8557,7 +8557,7 @@ export declare interface Schema {
     type?: Type;
 }

-export declare type SchemaUnion = Schema | unknown;
+export declare type SchemaUnion = Schema;

 /** An image mask representing a brush scribble. */
 export declare interface ScribbleImage {

Bonus: Generic `HttpResponse.json()`

Line 5410 isn't strictly an unknown-in-union issue, but while we're in surgery-mode anyway making json() generic enables:

// After patch
const data = await response.json<MyExpectedType>();

// Instead of
const data = await response.json() as MyExpectedType;

Small win, same patch.

The Type Utilities: From Patched to Pleasant

With the patch applied, you could write verbose narrowing code. But why suffer? A few type utilities transform the SDK's 18-member delta union into a discriminated map.

UnionToRecord: The Core Transformation

export type UnionToRecord<
  TUnion extends { type: string },
  TDiscriminant extends string = TUnion["type"]
> = {
  [K in TDiscriminant]: Extract<TUnion, { type: K }>;
};

This takes any discriminated union (where each member has a type field) and produces an object type keyed by those discriminants.

CTR (Conditional to Required)

The SDK marks delta as optional on ContentDelta. We need it required to extract the union. CTR is a surgical Required<T> that only targets optional keys:

export type Rm<T, P extends keyof T = keyof T> = {
  [S in keyof T as Exclude<S, P>]: T[S];
};

export type IsOptional<T, K extends keyof T> = undefined extends T[K]
  ? object extends Pick<T, K>
    ? true
    : false
  : false;

export type OnlyOptional<T> = {
  [K in keyof T as IsOptional<T, K> extends true ? K : never]: T[K];
};

/**
 * CTR (Conditional to Required)
 *
 * - By default: makes all **optional** properties required.
 * - With K: makes only the specified optional keys required.
 */
export type CTR<
  T,
  K extends keyof OnlyOptional<T> = keyof OnlyOptional<T>
> = Rm<T, K> & {
  [Q in K]-?: T[Q];
};

Putting It Together — GeminiEventMap

import type { Interactions } from "@google/genai";

export type UnionToRecord<
  TUnion extends { type: string },
  TDiscriminant extends string = TUnion["type"]
> = {
  [K in TDiscriminant]: Extract<TUnion, { type: K }>;
};

export type InteractionDeltas = CTR<
  Interactions.ContentDelta,
  "delta"
>["delta"];

export type GeminiEventMap = UnionToRecord<InteractionDeltas>;

On hover, GeminiEventMap resolves to:

type GeminiEventMap = {
  text: Interactions.ContentDelta.TextDelta;
  image: Interactions.ContentDelta.ImageDelta;
  audio: Interactions.ContentDelta.AudioDelta;
  document: Interactions.ContentDelta.DocumentDelta;
  video: Interactions.ContentDelta.VideoDelta;
  thought_summary: Interactions.ContentDelta.ThoughtSummaryDelta;
  thought_signature: Interactions.ContentDelta.ThoughtSignatureDelta;
  function_call: Interactions.ContentDelta.FunctionCallDelta;
  function_result: Interactions.ContentDelta.FunctionResultDelta;
  code_execution_call: Interactions.ContentDelta.CodeExecutionCallDelta;
  code_execution_result: Interactions.ContentDelta.CodeExecutionResultDelta;
  url_context_call: Interactions.ContentDelta.URLContextCallDelta;
  url_context_result: Interactions.ContentDelta.URLContextResultDelta;
  google_search_call: Interactions.ContentDelta.GoogleSearchCallDelta;
  google_search_result: Interactions.ContentDelta.GoogleSearchResultDelta;
  mcp_server_tool_call: Interactions.ContentDelta.MCPServerToolCallDelta;
  mcp_server_tool_result: Interactions.ContentDelta.MCPServerToolResultDelta;
  file_search_result: Interactions.ContentDelta.FileSearchResultDelta;
};

Every delta type, keyed by its discriminant. No narrowing required.

The Handler Pattern: Type-Safe Event Dispatch

With GeminiEventMap in place, we can build a handler factory that infers types from the event key:

type HandlerRegistration<K extends keyof GeminiEventMap = keyof GeminiEventMap> = {
  event: K;
  handler: (data: GeminiEventMap[K]) => void;
};

protected interactionsHandler = <
  const K extends keyof GeminiEventMap = keyof GeminiEventMap
>(
  event: K,
  handler: (data: GeminiEventMap[K]) => void
) => ({ event, handler });

The const K generic constraint preserves literal types, so interactionsHandler("text", ...) infers K as "text", not string.

Registering Handlers

const handlers = [
  this.interactionsHandler("text", (delta) => {
    // delta is Interactions.ContentDelta.TextDelta
    console.log(delta.text);
  }),
  this.interactionsHandler("image", (delta) => {
    // delta is Interactions.ContentDelta.ImageDelta
    console.log(delta.mime_type, delta.data);
  }),
  this.interactionsHandler("file_search_result", (delta) => {
    // delta is Interactions.ContentDelta.FileSearchResultDelta
    for (const res of delta.result) {
      console.log(res.title, res.text);
    }
  }),
] as const satisfies readonly HandlerRegistration[];

Dispatch

function dispatch(delta: InteractionDeltas) {
  const registration = handlers.find((h) => h.event === delta.type);
  if (registration) {
    // The discriminant match guarantees type alignment at runtime
    (registration.handler as (data: InteractionDeltas) => void)(delta);
  }
}

The cast in dispatch is the one escape hatch—TypeScript can't prove the runtime discriminant match guarantees type alignment, but we know it does. A pragmatic concession vs. 18 if branches.

Before vs. After

Before: Manual Narrowing Hell

for await (const event of stream) {
  switch (event.event_type) {
    case "content.delta": {
      if (event.delta) {
        // First layer: check if result exists
        if (
          "result" in event.delta &&
          typeof event.delta.result !== "undefined"
        ) {
          // Second layer: is it a string? an array? an object with items?
          if (typeof event.delta.result === "string") {
            // handle string result...
          } else if (
            Array.isArray(event.delta.result) &&
            event.delta.result.length > 0 &&
            // Third layer: compound guards to narrow delta.type
            (event.delta.type === "url_context_result" ||
              event.delta.type === "google_search_result" ||
              event.delta.type === "file_search_result")
          ) {
            // Fourth layer: ANOTHER switch on delta.type
            switch (event.delta.type) {
              case "file_search_result": {
                for (const res of event.delta.result) {
                  // finally... we can access res.title, res.text
                }
                break;
              }
              // ... 2 more cases
            }
          } else if (
            // Back to layer 2: different shape check
            "items" in event.delta.result &&
            typeof event.delta.result.items !== "undefined" &&
            (event.delta.type === "function_result" ||
              event.delta.type === "mcp_server_tool_result")
          ) {
            // The `unknown` in the union forces this assertion
            for (const it of event.delta.result.items) {
              const item = it as Interactions.ImageContent | string; // 💀
              // ...
            }
          }
        }
        // Oh, and we still need to handle delta.type directly
        switch (event.delta.type) {
          case "image": { /* ... */ break; }
          case "google_search_call": { /* ... */ break; }
          // ... 16 more cases
        }
      }
      break;
    }
    // ... 6 more event_type cases
  }
}

After: Declarative, Composable, Typed.

const handlers = [
  this.interactionsHandler("file_search_result", (delta) => {
    // delta.result is FileSearchResult[] — no narrowing, no assertions
    for (const res of delta.result) {
      this.logger.info({ title: res.title, text: res.text });
    }
  }),
  this.interactionsHandler("image", (delta) => {
    // delta.data is the base64 payload, delta.mime_type is typed
    this.handleImageUpload(delta.data, delta.mime_type);
  }),
  this.interactionsHandler("text", (delta) => {
    this.emit("text", delta.text);
  }),
  // Register only what you need, skip what you don't
] as const satisfies readonly HandlerRegistration[];

The discriminated map pattern shifts narrowing from imperative branching to declarative registration. Handlers become composable units rather than branches in a monolithic switch.

Troubleshooting

MCP SDK Import Resolution

If your editor throws errors on the @modelcontextprotocol/sdk import while editing in .pnpm_patches, you have two options:

Option A (recommended): Ignore the editor error—it won't affect the committed patch or runtime behavior. The import resolves correctly once you're out of the patch directory.

Option B: If it's driving you mad, install the MCP SDK and add a triple-slash directive:

pnpm add -D @modelcontextprotocol/sdk

Then prepend to your patch:

 /// <reference types="node" />
+/// <reference path="../../../../../@modelcontextprotocol/sdk/dist/esm/client/index.js" />

-import type { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import type { Client } from '@modelcontextprotocol/sdk';

This is purely for editor peace of mind during patching—it doesn't affect the fix itself.

Bonus: Deep Research Config Reference

The Interactions API's Deep Research functionality is under two weeks old. An example working configuration with the non-obvious gotchas annotated is provided below:

const gemini = this.getClient(apiKey);

const system_instruction = this.formatSystemInstruction(systemPrompt);

const input = this.formatHistoryDeepResearch(msgs, system_instruction);

const previous_interaction_id = this.previousInteractionId(msgs);

const stream = await gemini.interactions.create(
  {
    agent: "deep-research-pro-preview-12-2025",
    // Interactions.Turn[] type signature
    input,
    // "v1alpha" | "v1beta"
    api_version: "v1alpha",
    tools: [
      { type: "google_search" },
      { type: "code_execution" },
      { type: "url_context" },
      {
        type: "file_search",
        file_search_store_names: [
          "fileSearchStores/my-file_search-store-123"
        ]
      }
    ] satisfies Interactions.Tool[],
    // "audio" is another supported option
    response_modalities: ["text", "image"],
    system_instruction,
    // enables thinking events for feedback throughout the task
    agent_config: { thinking_summaries: "auto", type: "deep-research" },
    background: true,
    // when streaming is enabled `store: true` is required
    store: true,
    previous_interaction_id,
    stream: true
  },
  { stream: true }
);

Key gotchas:

store: true is required when stream: true; the SDK doesn't enforce this at the type level
previous_interaction_id enables multi-turn research sessions; parsed from event.interaction.id on interaction.complete events
Audio input is unsupported; audio output is supported via response_modalities

Closing Thoughts

The Interactions API is genuinely powerful; it enables Deep Research tasks, background polling, multi-modal outputs (documents, images, audio, etc), MCP server integration, and more. But the TypeScript story is currently hostile. The types shipped in v1.34.0 of the @google/genai SDK were likely autogenerated from Protobuf definitions (explaining the unknown union member contamination that nukes type inference throughout the Interactions namespace without the patch fix).

Until Google ships cleaner types, the patch + utility pattern provides

Safe and sane narrowing without assertions
Composable handlers instead of nested switches
Full IntelliSense across all 18 delta types

The API is in beta. The shipped types will likely improve eventually. But if you want to harness bleeding edge features like Deep Research today, this is the way.

Resources:

"Ode to Advanced TypeScript", a poem by Grok

Andrew Ross — Fri, 11 Jul 2025 18:42:22 +0000

Backstory

I've been hand-rolling a multi-provider, multi-model SaaS prototype for the past ~4 weeks and finally have my AWS Fargate-hosted websocket server and my vercel hosted next.js web app working in perfect harmony to stream chats in real-time with full conversation persistence (the provider/model combo being up to the user).

Anyway, as I was testing all providers yesterday I began submitting prompts with whatever first came to mind.

So Advanced TypeScript it was.

Poetry

Grok rose to the occasion and even outshone Anthropic's formidable Claude when tasked with crafting a poem:

Ode to Advanced TypeScript

Oh, TypeScript, guardian of code so vast,
A language of types, both strict and steadfast.
Beyond the basics, your power unfurls,
In advanced realms, where magic swirls.

With generics, you bend to our will,
A type for each purpose, a void to fill.
T and K, placeholders so fine,
Crafting functions that dynamically align.
Array<T> or Promise<string>, you say,
Ensuring safety in every array.

Union types, a crossroads of choice,
string | number, you give us voice.
Discriminated unions, with tags to guide,
{ kind: "error" } | { kind: "success" }, decide!
Narrowing paths with if and switch,
You guard our logic from every glitch.

Intersection, oh blend of might,
Person & Logger, combined in light.
A type that’s both, no detail missed,
Properties merged in a harmonious tryst.
Yet never lurks, a type so bare,
A path impossible, a warning to beware.

Conditional types, a puzzle, a game,
T extends U ? X : Y, not quite the same.
Inferring logic, a type to derive,
ReturnType<T>, keeping magic alive.
Mapped types, remapping the keys,
Partial<T>, Pick<T, K>, as we please.

Utility types, your gifts abound,
Omit, Exclude, solutions found.
Transforming shapes with elegant ease,
Building new types as if by a breeze.
And infer, a keyword of subtle art,
Extracting types from structures apart.

Oh, keyof, index of a type’s domain,
A union of keys, no need to explain.
Accessing deeply with dotted paths,
type Deep = Nested['a']['b'], no wrath.
And template literals, types as strings,
type Event =on${string};, such clever things.

With decorators, though experimental still,
You hint at patterns, a future thrill.
Classes adorned with metadata bright,
A glimpse of a world where types ignite.
And module augmentation, extending with care,
Adding to globals, a type to share.

Yet challenges rise, as complexity grows,
Type errors perplex, frustration shows.
But with as assertions, we sometimes cheat,
unknown to string, a daring feat.
Still, you urge caution, to tread with thought,
For type safety’s promise must not be bought.

Oh, TypeScript advanced, a craft so rare,
A balance of power, of love, of care.
You shape our code with a vigilant eye,
Ensuring no bug shall silently lie.
So here’s to your unions, your generics, your might,
A coder’s companion in the endless night.

A poem by grok (grok-3)

JSON Receipts

{
  "conversation": {
    "id": "sf87jjxf99n27vxwm6g5v3kd",
    "userId": "x1sa9esbc7nb1bbhnn5uy9ct",
    "userKeyId": "n2w8hxsdbfphf2pz7oj3mikn",
    "title": "\"The Elegance of Advanced TypeScript\"",
    "createdAt": "2025-07-10T20:04:53.108Z",
    "updatedAt": "2025-07-10T20:05:15.262Z",
    "isShared": false,
    "shareToken": null,
    "messages": [
      {
        "id": "n50jk023b4i2y2p73t1bac40",
        "conversationId": "sf87jjxf99n27vxwm6g5v3kd",
        "userId": "x1sa9esbc7nb1bbhnn5uy9ct",
        "senderType": "USER",
        "provider": "GROK",
        "model": "grok-3",
        "userKeyId": "n2w8hxsdbfphf2pz7oj3mikn",
        "content": "Write a poem about advanced typescript usage",
        "createdAt": "2025-07-10T20:04:53.108Z",
        "updatedAt": "2025-07-10T20:04:53.108Z"
      },
      {
        "id": "ai5hiyc70kf5s54s4z72y291",
        "conversationId": "sf87jjxf99n27vxwm6g5v3kd",
        "userId": "x1sa9esbc7nb1bbhnn5uy9ct",
        "senderType": "AI",
        "provider": "GROK",
        "model": "grok-3",
        "userKeyId": "n2w8hxsdbfphf2pz7oj3mikn",
        "content": "**Ode to Advanced TypeScript**\n\nOh, TypeScript, guardian of code so vast,\nA language of types, both strict and steadfast.\nBeyond the basics, your power unfurls,\nIn advanced realms, where magic swirls.\n\nWith generics, you bend to our will,\nA type for each purpose, a void to fill.\n`T` and `K`, placeholders so fine,\nCrafting functions that dynamically align.\n`Array<T>` or `Promise<string>`, you say,\nEnsuring safety in every array.\n\nUnion types, a crossroads of choice,\n`string | number`, you give us voice.\nDiscriminated unions, with tags to guide,\n`{ kind: \"error\" } | { kind: \"success\" }`, decide!\nNarrowing paths with `if` and `switch`,\nYou guard our logic from every glitch.\n\nIntersection, oh blend of might,\n`Person & Logger`, combined in light.\nA type that’s both, no detail missed,\nProperties merged in a harmonious tryst.\nYet `never` lurks, a type so bare,\nA path impossible, a warning to beware.\n\nConditional types, a puzzle, a game,\n`T extends U ? X : Y`, not quite the same.\nInferring logic, a type to derive,\n`ReturnType<T>`, keeping magic alive.\nMapped types, remapping the keys,\n`Partial<T>`, `Pick<T, K>`, as we please.\n\nUtility types, your gifts abound,\n`Omit`, `Exclude`, solutions found.\nTransforming shapes with elegant ease,\nBuilding new types as if by a breeze.\nAnd `infer`, a keyword of subtle art,\nExtracting types from structures apart.\n\nOh, keyof, index of a type’s domain,\nA union of keys, no need to explain.\nAccessing deeply with dotted paths,\n`type Deep = Nested['a']['b']`, no wrath.\nAnd template literals, types as strings,\n`type Event = `on${string}`;`, such clever things.\n\nWith decorators, though experimental still,\nYou hint at patterns, a future thrill.\nClasses adorned with metadata bright,\nA glimpse of a world where types ignite.\nAnd module augmentation, extending with care,\nAdding to globals, a type to share.\n\nYet challenges rise, as complexity grows,\nType errors perplex, frustration shows.\nBut with `as` assertions, we sometimes cheat,\n`unknown` to `string`, a daring feat.\nStill, you urge caution, to tread with thought,\nFor type safety’s promise must not be bought.\n\nOh, TypeScript advanced, a craft so rare,\nA balance of power, of love, of care.\nYou shape our code with a vigilant eye,\nEnsuring no bug shall silently lie.\nSo here’s to your unions, your generics, your might,\nA coder’s companion in the endless night.",
        "createdAt": "2025-07-10T20:05:15.262Z",
        "updatedAt": "2025-07-10T20:05:15.262Z"
      }
    ]
  }
}

AWS Shell Scripting

Andrew Ross — Thu, 26 Jun 2025 04:24:44 +0000

Intro

I deployed my first two services to AWS Fargate earlier this month --a node/typescript websocket server and a fastapi python microservice. But this post isn't about either service, it's about shell scripting as indicated by the title.

Get information about all configured services in one script

As a sanity measure, I highly recommend using a script similar to the one included below to pull info for all services/instances you have configured with aws. Before doing so, ensure you have the aws cli installed and your credentials stored in ~/.aws/credentials and/or ~/.aws/config if using Mac or Linux, else store them in %USERPROFILE%\.aws\credentials and %USERPROFILE%\.aws\config if using Windows. Tip: If you're using WSL2 like me, you'll likely want to keep this in your WSL2 distro environment (using the linux/mac locations for your credentials and for installing the aws cli, too).

The local shell script I slapped together that I run each time I want to pull information on all of my aws provisioned infra -- handy to use as a starting point for additional shell-based tasks, especially if configuring CI/CD with github or gitlab. Feel free to overhaul it to meet your needs:

#!/usr/bin/env bash
set -euo pipefail

mkdir -p remote/describe/{cluster,service,taskdef,tg,lb,listeners,repository,image,sg,subnets}

REGION=us-east-1

REPO_ARNS=$(
  aws ecr describe-repositories --region "$REGION" |
    jq -r '.repositories[].repositoryArn'
)

for REPO_ARN in $REPO_ARNS; do
  REPO=${REPO_ARN##*/}
  echo "→ Describing ECR repo $REPO"

  aws ecr describe-repositories \
    --repository-names "$REPO" \
    --region "$REGION" \
    >remote/describe/repository/"$REPO".json

  aws ecr describe-images \
    --repository-name "$REPO" \
    --region "$REGION" \
    >remote/describe/image/"$REPO".json
done

CLUSTER_ARNS=$(aws ecs list-clusters \
  --region "$REGION" |
  jq -r '.clusterArns[]')
for CLUSTER_ARN in $CLUSTER_ARNS; do
  CLUSTER_NAME=${CLUSTER_ARN##*/}
  echo "→ Using cluster: $CLUSTER_ARN"

  aws ecs describe-clusters \
    --clusters "$CLUSTER_ARN" \
    --region "$REGION" \
    >remote/describe/cluster/"$CLUSTER_NAME".json

  SERVICE_ARNS=$(aws ecs list-services \
    --cluster "$CLUSTER_ARN" \
    --region "$REGION" |
    jq -r '.serviceArns[]')

  for ARN in $SERVICE_ARNS; do

    NAME=${ARN##*/}
    echo "→ Describing service $NAME ($ARN)"

    aws ecs describe-services \
      --cluster "$CLUSTER_ARN" \
      --services "$NAME" \
      --region "$REGION" \
      >remote/describe/service/"$NAME".json

    TASK_DEF_ARN=$(jq -r '.services[0].taskDefinition' remote/describe/service/"$NAME".json)
    aws ecs describe-task-definition \
      --task-definition "$TASK_DEF_ARN" \
      --region us-east-1 >remote/describe/taskdef/"$NAME".json

    TG_ARN=$(jq -r '.services[0].loadBalancers[0].targetGroupArn' remote/describe/service/"$NAME".json)
    aws elbv2 describe-target-groups \
      --target-group-arns "$TG_ARN" \
      --region us-east-1 >remote/describe/tg/"$NAME".json

    LB_ARN=$(jq -r '.TargetGroups[0].LoadBalancerArns[0]' remote/describe/tg/"$NAME".json)

    aws elbv2 describe-load-balancers \
      --load-balancer-arns "$LB_ARN" \
      --region us-east-1 >remote/describe/lb/"$NAME".json

    aws elbv2 describe-listeners \
      --load-balancer-arn "$LB_ARN" \
      --region us-east-1 >remote/describe/listeners/"$NAME".json

    SECURITY_GROUP=$(jq -r '.services[0].networkConfiguration.awsvpcConfiguration.securityGroups | join(" ")' remote/describe/service/"$NAME".json)

    aws ec2 describe-security-groups \
      --group-ids "$SECURITY_GROUP" \
      --region "$REGION" >remote/describe/sg/"$NAME".json

    SUBNET_IDS=$(jq -r '.services[0].networkConfiguration.awsvpcConfiguration.subnets[]' remote/describe/service/"$NAME".json)

    for SUBNET_ID in $SUBNET_IDS; do
      mkdir -p remote/describe/subnets/"$NAME"

      aws ec2 describe-subnets \
        --subnet-ids "$SUBNET_ID" \
        >remote/describe/subnets/"$NAME"/"$SUBNET_ID".json
    done
  done
done

make sure to run chmod+x filename.sh to make it executable

this will output directories containing files similar to the ones shown in this screenshot

I also strongly recommend adding remote/**/*.json to your gitignore file since you definitely don't want these to be publicly viewable

Resolving code vs cursor command paths for WSL2 & Windows 11 setups

Andrew Ross — Fri, 18 Apr 2025 22:41:26 +0000

For those of you who prefer using a wsl2 distro for your development environment you may be familiar with the periodic configuration quirks that come with having linux live in windows basement (wsl = windows subsystem linux)

I would like to address a simple fix for WSL2 users who want the option to open either vscode or cursor in a single command without the executable files of the latter overwriting the former.

Ideal Setup

Allow me to lay out what I consider to be an ideal "single command" scenario:

to open the cwd in vscode:

code .

to open the cwd in cursor:

cursor .

seems like a reasonable default to aim for, right?

Unfortunately, cursor installs a code . (code.cmd) command along with its cursor . (cursor.cmd) command, effectively overwriting the VSCode code . command in the process.

Solution to cursor overwriting the VSCode `code .` command

Here's the quick fix to ensure that using cursor . only opens cursor and code . only opens vscode in your wsl2 environment:

(1) Open PowerShell with admin permissions

The following command is extremely useful in PS

(Get-Command <command>).Source

(2) determine the file path to the underlying .cmd files powering the cursor and code commands on your machine

PS C:\WINDOWS\system32> (Get-Command cursor).Source
c:\Users\Anthr\AppData\Local\Programs\cursor\resources\app\bin\cursor.cmd
PS C:\WINDOWS\system32> (Get-Command code).Source
c:\Users\Anthr\AppData\Local\Programs\cursor\resources\app\bin\code.cmd

(3) Since it shows that both .cmd files reside in the bin folder of Cursor, target the code.cmd file for deletion using PowerShells Remove-Item "C:\Users\YourUsername\...etc" command

PS C:\WINDOWS\system32> Remove-Item "C:\Users\Anthr\AppData\Local\Programs\cursor\resources\app\bin\code.cmd"

(4) verify that the code command once again points to VSCode, not Cursor

PS C:\WINDOWS\system32> (Get-Command code).Source
C:\Users\Anthr\AppData\Local\Programs\MicrosoftVSCode\Microsoft VS Code\bin\code.cmd

(5) The fix is complete but only until Cursor's next update. Source: having to redo this process 5-10 minutes ago which is why I made this quick write-up.

How to prevent this behavior automatically even with Cursor updates?

One approach would be writing a ps1 script, and while I'm not acutely familiar with PowerShell scripting, o1-pro-gpt suggested the following:

$cursorBin = "C:\Users\Anthr\AppData\Local\Programs\cursor\resources\app\bin"
$cursorCmd = Join-Path $cursorBin "code.cmd"
$cursorExe = Join-Path $cursorBin "code.exe"

if (Test-Path $cursorCmd) {
    Remove-Item $cursorCmd -Force
}
if (Test-Path $cursorExe) {
    Remove-Item $cursorExe -Force
}

In summary, o1-pro suggested creating the above script, naming it something like RemoveCursorCode.ps1, then configuring a Scheduled Task in Windows

here's o1-pro's verbatim response:

"Set up a Scheduled Task in Windows that calls this script:

Open Task Scheduler (Win + R -> taskschd.msc).
Create a new Basic Task named “Remove Cursor Code”.
Trigger: “When I log on” (or “At startup”).
Action: “Start a program” -> powershell.exe with the -File "<path to .ps1>" argument.
Finish.

Then every time you log in, it removes or nukes the code binaries from Cursor’s directory. If a Cursor update reintroduces them, the next time you log on, they get cleaned up again.

Note: Make sure the script is somewhere you won’t delete it by accident, >e.g. C:\scripts\RemoveCursorCode.ps1. Also, ensure your PowerShell >ExecutionPolicy is set to at least RemoteSigned or Bypass so the script can run."

A Next.js 15 Dynamic Route Helper Type

Andrew Ross — Tue, 31 Dec 2024 06:35:12 +0000

The types to use

export type InferGSPRTWorkup<T> =
  T extends Promise<readonly (infer U)[] | (infer U)[]> ? U : T;


export type InferGSPRT<T extends (...args: any) => any> = {
  params: Promise<InferGSPRTWorkup<ReturnType<T>>>;
};

`InferGSPRTWorkup<T>`

export type InferGSPRTWorkup<T> =
  T extends Promise<readonly (infer U)[] | (infer U)[]> ? U : T;

`InferGSPRT<T>`

export type InferGSPRT<T extends (...args: any) => any> = {
  params: Promise<InferGSPRTWorkup<ReturnType<T>>>;
};

Usage

export default async function Example({ params }: InferGSPRT<typeof generateStaticParams>) {
   const { slug } = await params;
   // rest...
};

Summary

Copy-paste the two types defined initially into a file in your code base. Use InferGSPRT within the page file of dynamic routes to infer the params object returned by generateStaticParams effortlessly.

Nextjs versions 13 & 14

Remove the outer Promise in the InferGSPRT type definition. The params object is synchronously resolved by the exported default function prior to version 15.

TypeScript React + Generics Part I — Time-Saving Patterns

Andrew Ross — Tue, 13 Jun 2023 08:17:57 +0000

Time is Money

Using TSX + Generics strategically in any given project helps to establish clean coding patterns and ultimately save time in the long run. I wrote the following definitions earlier this afternoon after becoming frustrated with unorganized typedefs littering a plethora of files across a project codebase. The defs in question happened to be mostly imports from React of the Attribute-Element variety. That said, let's begin

import type React from "react";

export type RemoveFields<T, P extends keyof T = keyof T> = {
  [S in keyof T as Exclude<S, P>]: T[S];
};

export type ExtractPropsTargeted<T> = T extends 
  React.DetailedHTMLProps<infer U, Element>
  ? U
  : T;

export type PropsTargeted<
  T extends keyof globalThis.JSX.IntrinsicElements = 
  keyof globalThis.JSX.IntrinsicElements
> = {
  [P in T]: ExtractPropsTargeted<
    globalThis.JSX.IntrinsicElements[P]
  >;
}[T];

export type PropsExcludeTargeted<
  T extends keyof globalThis.JSX.IntrinsicElements = 
  keyof globalThis.JSX.IntrinsicElements,
  J extends keyof PropsTargeted<T> = 
  keyof PropsTargeted<T>
> = RemoveFields<PropsTargeted<T>, J>;

export type PropsIncludeTargeted<
  T extends keyof globalThis.JSX.IntrinsicElements = 
  keyof globalThis.JSX.IntrinsicElements,
  J extends keyof PropsTargeted<T> = 
  keyof PropsTargeted<T>
> = RemoveFields<
      PropsTargeted<T>, 
      Exclude<keyof PropsTargeted<T>, J>
    >;

The `RemoveFields<T, keyof T>` type

Why bother writing our own RemoveFields helper when we can use the builtin Omit type? Because it is a stricter implementation of Omit; it also provides heightened intellisense

Let's take a look at the definitions for Omit and RemoveFields side-by-side:

type Omit<T, K extends string | number | symbol> = 
{ [P in Exclude<keyof T, K>]: T[P]; }

type RemoveFields<T, P extends keyof T = keyof T> = 
{ [S in keyof T as Exclude<S, P>]: T[S]; }

While the difference may seem trivial at first glance, a real-world example involving the mapping of props in the Nextjs Link Component should provide a clearer distinction

The Link Component in next/link/client/link.d.ts is defined as

declare const Link: React.ForwardRefExoticComponent<Omit<
  React.AnchorHTMLAttributes<HTMLAnchorElement>, 
  keyof InternalLinkProps
> & InternalLinkProps & {
    children?: React.ReactNode;
} & React.RefAttributes<HTMLAnchorElement>>;

However, we're only interested in the definitions within the external React.ForwardRefExoticComponent<P> wrapper, so we can simplify the typedef as follows

type TargetedLinkProps = Omit<
  React.AnchorHTMLAttributes<HTMLAnchorElement>, 
  keyof InternalLinkProps
> & InternalLinkProps & {
    children?: React.ReactNode;
} & React.RefAttributes<HTMLAnchorElement>

With Omit in place in the TargetedLinkProps type and with the strict and always-strict flags turned on in our tsconfig.json file, there are no type errors in the above definition. However, if we swap Omit out in favor of RemoveFields we see errors appear immediately.

// replacing `Omit` with `RemoveFields` results in errors

type TargetedLinkProps = RemoveFields<
  React.AnchorHTMLAttributes<HTMLAnchorElement>, 
  keyof InternalLinkProps
> & InternalLinkProps & {
    children?: React.ReactNode;
} & React.RefAttributes<HTMLAnchorElement>

Why? Omit is forgiving or lenient when it comes to key-discrimination and allows for extraneous keys to be present that do not exist in a given type definition which is a double-edged sword. If precision is your aim, RemoveFields can simply be thought of as a souped-up ever-vigilant version of Omit.

So what about these errors? Not to worry, these errors can be remedied by dissecting the definition for InternalLinkProps and refactoring appropriately

`InternalLinkProps` = `LinkProps`

Nextjs exports a LinkProps type from next/link which has a 1:1 relationship with the InternalLinkProps type. The definition of LinkProps is as follows

type InternalLinkProps = {
    href: Url;
    as?: Url;
    replace?: boolean;
    scroll?: boolean;
    shallow?: boolean;
    passHref?: boolean;
    prefetch?: boolean;
    locale?: string | false;
    legacyBehavior?: boolean;
    onMouseEnter?: React.MouseEventHandler<HTMLAnchorElement>;
    onTouchStart?: React.TouchEventHandler<HTMLAnchorElement>;
    onClick?: React.MouseEventHandler<HTMLAnchorElement>;
};

For absolute clarity, I've included the type definitions for Url, UrlObject, and ParsedUrlQueryInput below

interface ParsedUrlQueryInput extends NodeJS.Dict<
    | string
    | number
    | boolean
    | ReadonlyArray<string>
    | ReadonlyArray<number>
    | ReadonlyArray<boolean>
    | null
>{}

interface UrlObject {
    auth?: string | null | undefined;
    hash?: string | null | undefined;
    host?: string | null | undefined;
    hostname?: string | null | undefined;
    href?: string | null | undefined;
    pathname?: string | null | undefined;
    protocol?: string | null | undefined;
    search?: string | null | undefined;
    slashes?: boolean | null | undefined;
    port?: string | number | null | undefined;
    query?: string | null | ParsedUrlQueryInput | undefined;
}

type Url = string | UrlObject;

What exactly is causing the error?

If we cross-compare all 14 keys within the InternalLinkProps type with all keys defined within the React.AnchorHTMLAttributes<HTMLAnchorElement> entity (which Omit is acting on), we find that only 4 out of 14 keys in keyof InternalLinkProps match keys within the targeted React.AnchorHTMLAttributes<HTMLAnchorElement> type.

The implication?

The Omit type helper fails to detect that 10 out of 14 keys in the keyof InternalLinkProps argument do not exist at all in the React.AnchorHTMLAttributes<HTMLAnchorElement>. The RemoveFields helper does detect the presence of extraneous keys which alerts us of the mismatch to begin with

With that out of the way, we can rewrite our TargetedLinkProps typedef as follows (only the four matching keys being passed in as arguments)

type TargetedLinkProps = RemoveFields<
  React.AnchorHTMLAttributes<HTMLAnchorElement>,
  "href" | "onClick" | "onMouseEnter" | "onTouchStart"
> &
  InternalLinkProps & {
    children?: React.ReactNode;
  } & React.RefAttributes<HTMLAnchorElement>;

Extractor Types

There are a number of commonly used helper types that unwrap or extract internal types by utilizing TypeScripts infer method

For example

type UnwrapPromise<T> = T extends Promise<infer U> ? U : T;

type Unenumerate<T> = T extends Array<infer U> ? U : T;

In fact, we could have taken this extractor route to derive the types contained within the Nextjs Link Component in the previous section instead of eyeballing it and manually pulling the types out

import Link from "next/link";

type InferReactForwardRefExoticComponentProps<T> = T extends 
  React.ForwardRefExoticComponent<infer U> 
   ? U 
   : T;


/**
 * this is equal to the previously defined 
 * `TargetedLinkProps` type
 */

type ExtractedLinkProps = 
InferReactForwardRefExoticComponentProps<typeof Link>

The `ExtractPropsTargeted` Extractor Type

This is the second of five core typedefs defined in the very first code block in this post

type ExtractPropsTargeted<T> = T extends 
  React.DetailedHTMLProps<infer U, Element>
  ? U
  : T;

For context, the React.DetailedHTMLProps type has the following definition

type DetailedHTMLProps<E extends React.HTMLAttributes<T>, T> =
 React.ClassAttributes<T> & E

In practice, this looks something like

React.DetailedHTMLProps<React.HTMLAttributes<HTMLDivElement>, HTMLDivElement>

So what is it that we're trying to pull out exactly? We are targeting the first of two generic arguments within React.DetailedHTMLProps which I usually refer to as the attribute<element> tandem

Using `ExtractPropsTargeted` within the `PropsTargeted` Mapper definition

The Second type, ExtractPropsTargeted, is used to extract all attribute-element tandems that exist in React from the recursively mapped globalThis.JSX.IntrinsicElements entity. This entity contains key-value pairs that each have an outer React.DetailedHTMLProps wrapper

As illustrated below, the ExtractPropsTargeted Extractor type wraps the globalThis.JSX.IntrinsicElements entity to effectively derive each Attribute<Element> tandem. The exact tandem pulled out is a function of the key passed in ("div", "a", "p", etc.).


type PropsTargeted<
  T extends keyof globalThis.JSX.IntrinsicElements = 
  keyof globalThis.JSX.IntrinsicElements
> = {
  [P in T]: ExtractPropsTargeted<
    globalThis.JSX.IntrinsicElements[P]
  >;
}[T];

A simple use case for this type is as follows

export function TextField({
  id,
  label,
  type = "text",
  className,
  ...props
}: PropsTargeted<"input"> & { label: ReactNode }) {
  return (
    <div className={className}>
      {label && <Label htmlFor={id}>{label}</Label>}
      <input id={id} type={type} {...props} className={formClasses} />
    </div>
  );
}

Intellisense when hovering above the spread ...props

The Payoff — `PropsExcludeTargeted` and `PropsIncludeTargeted`

At last we arrive at the payoff. The first three core types (RemoveFields, ExtractPropsTargeted, and PropsTargeted) have provided the workup necessary for writing these truly intuitive helper types

The final two of the initial five core types contained within the first code block of this article each take two arguments; (1) the targeted intrinsic element key such as "div" or "svg" or "li" etc and (2) the keys of targeted fields within a given top-level intrinsic element (as defined by (1)). The second argument, a union of keys, serves to either exclude or include targeted fields appropriately.

The `PropsExcludeTargeted` type

The definition of the PropsExcludeTargeted type is as follows

type PropsExcludeTargeted<
  T extends keyof globalThis.JSX.IntrinsicElements = 
  keyof globalThis.JSX.IntrinsicElements,
  J extends keyof PropsTargeted<T> = 
  keyof PropsTargeted<T>
> = RemoveFields<PropsTargeted<T>, J>;

This is used in practice for example when you have an svg with viewBox, xmlns, and aria-hidden defined in the original component. There's no sense in forwarding props that will do absolutely nothing if populated in a parent component elsewhere.

Therefore, best practice is to preemptively strip known static or unchanging fields from the originating component as follows

const AppleIcon: FC<
  PropsExcludeTargeted<"svg", "viewBox" | "xmlns">
> = ({ fill, ...props }) => (
  <svg
    {...props}
    viewBox='0 0 815 1000'
    fill='none'
    xmlns='http://www.w3.org/2000/svg'>
    <path
      fill={fill ?? "black"}
      d='M788.1 340.9C782.3 345.4 679.9 403.1 679.9 531.4C679.9 679.8 810.2 732.3 814.1 733.6C813.5 736.8 793.4 805.5 745.4 875.5C702.6 937.1 657.9 998.6 589.9 998.6C521.9 998.6 504.4 959.1 425.9 959.1C349.4 959.1 322.2 999.9 260 999.9C197.8 999.9 154.4 942.9 104.5 872.9C46.7 790.7 0 663 0 541.8C0 347.4 126.4 244.3 250.8 244.3C316.9 244.3 372 287.7 413.5 287.7C453 287.7 514.6 241.7 589.8 241.7C618.3 241.7 720.7 244.3 788.1 340.9ZM554.1 159.4C585.2 122.5 607.2 71.3 607.2 20.1C607.2 13 606.6 5.8 605.3 0C554.7 1.9 494.5 33.7 458.2 75.8C429.7 108.2 403.1 159.4 403.1 211.3C403.1 219.1 404.4 226.9 405 229.4C408.2 230 413.4 230.7 418.6 230.7C464 230.7 521.1 200.3 554.1 159.4Z'
    />
  </svg>
);

While fill is defined as none in the top level svg intrinsic element, you can always pass its prop down into a nested intrinsic element if the opportunity presents itself instead of outright omitting it (such as path in this situation). The fill prop is of type string | undefined in svg and path alike.

My Personal Favorite — `PropsIncludeTargeted`

The PropsIncludeTargeted type is defined as follows

type PropsIncludeTargeted<
  T extends keyof globalThis.JSX.IntrinsicElements = 
  keyof globalThis.JSX.IntrinsicElements,
  J extends keyof PropsTargeted<T> = 
  keyof PropsTargeted<T>
> = RemoveFields<
      PropsTargeted<T>, 
      Exclude<keyof PropsTargeted<T>, J>
    >;

Why is this type my personal favorite of the five? Because WYSIWYG. The keys passed in to the second argument of the type are the only fields defined — nothing less, nothing more.

Consider the following simple example with a reusable Label component

function Label({
  htmlFor: id,
  children
}: PropsIncludeTargeted<"label", "htmlFor" | "children">) {
  return (
    <label
      htmlFor={id}
      className='mb-2 block text-sm font-semibold text-gray-900'>
      {children}
    </label>
  );
}

The only two fields derived from the targeted LabelHTMLAttributes<HTMLLabelElement> tandem are children and htmlFor as is expected by the key arguments passed in. This results in the following inferred type def

{
    htmlFor?: string | undefined;
    children?: ReactNode;
}

Wrapping it up

This post is the first of ? in a series of posts about how utilizing typescript and generics can streamline and clean up code. In future articles I intend to cover utilizing generics in other contexts such as the filesystem, the api layer, and more. Thanks for reading along, cheers

Recursively Clone Objects without sacrificing Type Safety

Andrew Ross — Thu, 01 Jun 2023 09:38:49 +0000

What not to do

When writing utilities to recursively clone objects that are passed through to a helper as transient args, you don't need to call a given top level function from within some deeply nested corner of that same function from within an if conditional that's within an if conditional nested within a for loop within a for loop...and so on. That dizzying approach becomes rapidly convoluted usually by the time you're approximately several nested layers of conditionals and/or for-loops deep.

Instead, utilize TypeScript and its generics and break it up into bite-sized pieces which have the added benefit of being reusable throughout your code base for type checking and more.

(1/4) Writing the Base `Depth` type

This recursively mapped generic type traverses any given object and its key-value pairs using static types alone; it also poises us for straightforward type-inference in the following step

export type Depth<
  Y extends { [record: string | symbol | number]: unknown },
  X extends keyof Y = keyof Y
> = {
  [H in keyof Y[X]]: Y[X][H][keyof Y[X][H]];
};

(2/4) Writing the `InferDepth` generic type

The following generic gracefully "unwraps" Depth by inferring each of the two generic types passed through.

export type InferDepth<T> = T extends Depth<infer U, infer X> ? U[X] : T;

The one-liner above may not look like it's doing much, but on ctrl+hover, TS Intellisense informs us that InferDepth is of type

type InferDepth<T> = T extends Depth<infer U extends {
    [record: string]: unknown;
    [record: number]: unknown;
    [record: symbol]: unknown;
}, infer X extends keyof infer U extends {
    [record: string]: unknown;
    [record: number]: unknown;
    [record: symbol]: unknown;
}> ? U[X] : T

All of that from a one liner that "unwraps" Depth by utilizing type inference

(3/4) Defining the `inferObj` and `objInference` tandem

Things are getting functional now, ja?

export const inferObj = <J, T extends InferDepth<J>>(props: T) => props;

export const objInference = <T extends Parameters<typeof inferObj>["0"]>(
  props: T
) => inferObj(props);

Skeptical? That's okay, I was too while writing this code out for the first time late one night from scratch. But it works wonderfully, let's take a look at how with an example.

(4/4) To be non-readonly, or not to be

The following ugly object I slapped together contains one particularly bodacious nesting occurrence for the purpose of showcasing objInference's utility

const devObject = {
  theSimpleKey: "a simple string",
  getDate: (rr: InstanceType<typeof Date>) => new Date(rr.toISOString()),
  nestttt: () => [
    {
      "let's": {
        keep: {
          nesting: true,
          deeper: [
            {
              because: {
                why: {
                  the: {
                    fuck: { not: () => (Date.now() % 2 === 0 ? true : false) }
                  }
                }
              }
            }
          ]
        }
      }
    }
  ]
};

The deeply nested function returns a conditional within an array of objects that's also nested within an array of objects. We can expect the sample code to return true 500 times each second and false 500 times each second, but that's beside the point.

the point is, our objInference function helper seamlessly handles the recursive cloning of this non-readonly object in a one liner -- and it doesn't sacrifice type-safety while also avoiding unnecessary complexity

const intelliCheck = () => objInference(devObj);

which has the following type inferred instantly

declare const intelliCheck: () => {
    theSimpleKey: string;
    getDate: (rr: InstanceType<typeof Date>) => Date;
    nestttt: () => {
        "let's": {
            keep: {
                nesting: boolean;
                deeper: {
                    because: {
                        why: {
                            the: {
                                fuck: {
                                    not: () => boolean;
                                };
                            };
                        };
                    };
                }[];
            };
        };
    }[];
};

Appending an as const on the end of any given objects definition only heightens the type inference precision of these recursively cloning object rippers

const devObject = {
  theSimpleKey: "a simple string",
  getDate: (rr: InstanceType<typeof Date>) => new Date(rr.toISOString()),
  nestttt: () => [
    {
      "let's": {
        keep: {
          nesting: true,
          deeper: [
            {
              because: {
                why: {
                  the: {
                    fuck: { not: () => (Date.now() % 2 === 0 ? true : false) }
                  }
                }
              }
            }
          ]
        }
      }
    }
  ]
} as const; // now it's readonly

Wrapping it up

To provide an insight into how this objInference recursively cloning helper is actually ripping the internals of any given object passed through it, let's take a look at the following tamer object

const numObj = {
  one: 1,
  two: 2,
  three: "3",
  four: "IV"
} as const;

objInference(numObj)

while hovering and holding the "ctrl" key over the objInference cloner wrapping the numObj constant above, its internal workings become evident

const objInference: <{
    readonly one: 1;
    readonly two: 2;
    readonly three: "3";
    readonly four: "IV";
}>(props: {
    readonly one: 1;
    readonly two: 2;
    readonly three: "3";
    readonly four: "IV";
}) => {
    readonly one: 1;
    readonly two: 2;
    readonly three: "3";
    readonly four: "IV";
}

Here's a link to the typescript playground containing pieces of the code used throughout this late-night post; it's worth checking out, especially if you're still apprehensive about this type-first approach to recursively cloning objects.

Cheers

A strongly typed Google Model-Viewer implementation in React

Andrew Ross — Wed, 07 Dec 2022 10:27:06 +0000

Overview

Over the past couple months I've been periodically working with custom hosting solutions for windows 3D vista pro tours. One of these virtual experiences happens to be a 3D tech refresh virtual marketplace where employees can trade in their existing devices for new ones. The idea is that the employees can interact with devices in this experience and project them into their space using Augmented Reality. While refactoring bits and pieces of the virtual-marketplace I once again came across the code used to render these objects -- and I was once again annoyed by the fact that I had been resorting to using dangerouslySetInnerHTML as a workaround for rendering 3D objects in an alwaysStrict Nextjs repo. How hard could it be after all to get the model-viewer element from @google/model-viewer to render as a native JSX.IntrinsicElement?

`@google/model-viewer`

If you're not yet familiar with the @google/model-viewer package you can find the docs here, the examples here, and the github repo here.

The Annoying Workaround

Below is the code used as a workaround for rendering each of the 3d objects used in the virtual marketplace experience. I've omitted the absolute URLs as I'm quite certain my employer would not be thrilled with me making those publicly accessible.

src/pages/assets/glb/[glb].tsx

import type {
  GetStaticPathsResult,
  GetStaticPropsContext,
  GetStaticPropsResult,
  InferGetStaticPropsType,
  PreviewData
} from "next";
import type { ParsedUrlQuery } from "querystring";
import { LoadingDots} from "@virtual-store/ui";
import { Suspense } from "react";
import { useRouter } from "next/router";

const DeviceObj = {
  UnrealMacBookPro14:
    "/v1668589751/VirtualTour/UnrealMacBookPro14_ynw7dg.glb",
  macbookair:
    "/v1668118327/VirtualTour/macbookair_ajugky.glb",
  macbook_pro_2021:
    "/v1668589750/VirtualTour/macbook_pro_2021_dby3mx.glb",
  delllatitude7330ruggedlaptop:
    "/v1668118348/VirtualTour/delllatitude7330ruggedlaptop_ziijbe.glb",
  "Lenovo M80q Tiny 2":
    "/v1668118312/VirtualTour/Lenovo_M80q_Tiny_2_jwtu9h.glb",
  lenovox1:
    "/v1668206027/VirtualTour/lenovox1_pldnaa.glb",
  lenovol13gen2:
    "/v1668206076/VirtualTour/lenovol13gen2_iewiqk.glb",
  genericlenovolaptop:
    "/v1668118314/VirtualTour/genericlenovolaptop_rjkvc8.glb",
  surfacehub:
    "/v1668118332/VirtualTour/surfacehub_epkes8.glb",
  surfacelaptop:
    "/v1668118326/VirtualTour/surfacelaptop_yajji1.glb",
  surfacelaptopstudio:
    "/v1668441368/VirtualTour/surfacelaptopstudio_mopmve.glb",
  SurfacePro7Plus:
    "/v1668118351/VirtualTour/SurfacePro7Plus_lxn8xe.glb",
  surfacestudio2:
    "/v1668118329/VirtualTour/surfacestudio2_tp8dp9.glb",
  thinkcentrem80qtiny:
    "/v1668206530/VirtualTour/thinkcentrem80qtiny_dal7ni.glb",
  thinkstationv2:
    "/v1668206602/VirtualTour/thinkstationv2_o8dxo8.glb"
} as const;

const paths = [
  "UnrealMacBookPro14",
  "macbookair",
  "macbook_pro_2021",
  "delllatitude7330ruggedlaptop",
  "Lenovo M80q Tiny 2",
  "lenovox1",
  "lenovol13gen2",
  "genericlenovolaptop",
  "surfacehub",
  "surfacelaptop",
  "surfacelaptopstudio",
  "SurfacePro7Plus",
  "thinkcentrem80qtiny",
  "thinkstationv2"
];

const posterPath = "/v1668208003/VirtualTour/initial-load_p0yyun-Circle_yzha4d.png";

async function htmlScaffolding(glbData: keyof typeof DeviceObj) {
  const glbPath = DeviceObj[glbData];
  const htmlScaffold = `<!DOCTYPE html>
    <head>
      <meta charset="utf-8" />
      <meta http-equiv="X-UA-Compatible" content="IE=edge" />
      <meta name="viewport" content="width=device-width, initial-scale=1" />
      <style>
        model-viewer {
          width: calc(100vw - 20px);
          height: calc(100vh - 20px);
        };
      </style>
    </head>
    <body>
      <div id="card" class="bg-blend-lighten">
        <model-viewer
          src="${glbPath}"
          id="viewer"
          shadow-intensity="1"
          camera-controls
          auto-rotate
          ar
          ar-modes="webxr scene-viewer quick-look"
          poster="${posterPath}"
          class="modelViewer">
          <button slot="ar-button" id="ar-button" class="font-normal tracking-wide text-white">View in your space</button>
        </model-viewer>
      </div>
      <script
        async
        type="module"
        src="https://unpkg.com/@google/model-viewer/dist/model-viewer.min.js"></script>
    </body> `;

  return htmlScaffold;
}

export const getStaticPaths = async (): Promise<
  GetStaticPathsResult<ParsedUrlQuery>
> => {
  return {
    paths: paths.map(path => `/assets/glb/${path}`),
    fallback: true
  };
};

const queryParamHandler = (props: string | string[] | undefined) => {
  return typeof props !== "undefined"
    ? Array.isArray(props)
      ? props[0]
      : props
    : "";
};

interface StaticPropsResultType {
  device: typeof DeviceObj[keyof typeof DeviceObj];
}

export const getStaticProps = async (
  ctx: GetStaticPropsContext<ParsedUrlQuery, PreviewData>
): Promise<
  GetStaticPropsResult<StaticPropsResultType>
> => {
  const glb = ctx.params ? queryParamHandler(ctx.params.glb) : "lenovol13gen2";
  return {
    props: {
      device: (await htmlScaffolding(
        glb as keyof typeof DeviceObj
      )) satisfies StaticPropsResultType['device']
    }
  };
};

export default function Glb<T extends typeof getStaticProps>({
  device
}: InferGetStaticPropsType<T>) {
  const router = useRouter();
  return (
    <>
      {router.isFallback ? (
        <LoadingDots />
      ) : (
        <Suspense fallback={<LoadingDots />}>
          <div className='min-h-screen min-w-[100vw]'>
            <i
              className='min-h-screen min-w-full'
              dangerouslySetInnerHTML={{ __html: device }}
            />
          </div>
        </Suspense>
      )}
    </>
  );
}

A Quick Type Reference

While we could delve into type definitions, decorators, the shadow dom, and globally accessible bits and pieces of the @google/model-viewer package, I'll spare those details in the spirit of keeping this entry on the shorter side. I will say that the package uses lit, three, and @types/three; the package, once installed and instantiated via a root script import in the src/pages/_app.tsx file (more on that shortly), has a typedef of utility exposed for consumption via an interface in the globalThis module. Specifically, it becomes accessible through the HTMLElementTagNameMap interface which, assuming @google/model-viewer and typescript are both installed if you've made it this far, has two separate definitions in node_modules. The first primary definition for HTMLElementTagNameMap is found in the typescript/lib/lib.dom.d.ts file; the second definition, an augmented global declaration, is housed in the @google/model-viewer/lib/model-viewer.d.ts file. The augmented file contains the following several-dozen lines of code:

import ModelViewerElementBase from './model-viewer-base.js';
export declare const ModelViewerElement: {
    new (...args: any[]): import("./features/annotation.js").AnnotationInterface;
    prototype: import("./features/annotation.js").AnnotationInterface;
} & object & {
    new (...args: any[]): import("./features/scene-graph.js").SceneGraphInterface;
    prototype: import("./features/scene-graph.js").SceneGraphInterface;
} & {
    new (...args: any[]): import("./features/staging.js").StagingInterface;
    prototype: import("./features/staging.js").StagingInterface;
} & {
    new (...args: any[]): import("./features/environment.js").EnvironmentInterface;
    prototype: import("./features/environment.js").EnvironmentInterface;
} & {
    new (...args: any[]): import("./features/controls.js").ControlsInterface;
    prototype: import("./features/controls.js").ControlsInterface;
} & {
    new (...args: any[]): import("./features/ar.js").ARInterface;
    prototype: import("./features/ar.js").ARInterface;
} & {
    new (...args: any[]): import("./features/loading.js").LoadingInterface;
    prototype: import("./features/loading.js").LoadingInterface;
} & import("./features/loading.js").LoadingStaticInterface & {
    new (...args: any[]): import("./features/animation.js").AnimationInterface;
    prototype: import("./features/animation.js").AnimationInterface;
} & typeof ModelViewerElementBase;
export declare type ModelViewerElement = InstanceType<typeof ModelViewerElement>;
export { RGB, RGBA } from './three-components/gltf-instance/gltf-2.0';
declare global {
    interface HTMLElementTagNameMap {
        'model-viewer': ModelViewerElement;
    }
}

The Solution

If you haven't installed the @google/model-viewer package yet, do so now. Then, add the following to your src/pages/_app.tsx file. Note that while the npm package is installed in the project, attempting to reference the file where the module is located in the script components src field (even when using an absolute path) causes Nextjs to throw an error. The quick fix for this is to use the unpkg cdn for the @google/model-viewer package to pull the latest version in

`src/pages/_app.tsx`

import "../styles/index.css";
import Script from "next/script";
import type { AppProps } from "next/app";
import Head from "next/head";

export default function NextApp({
  Component,
  pageProps
}: AppProps) {
// inject the next app with the latest version of `@google/model-viewer`
  return (
    <>
      <Head>
        <title>{"Virtual Marketplace"}</title>
      </Head>
      <Script
        async
        strategy='afterInteractive'
        type='module'
        src='https://unpkg.com/@google/model-viewer@^2.1.1/dist/model-viewer.min.js'
      />
        <Component {...pageProps} />
    </>
  );
}

`src/types/react.d.ts`

In this file we'll be augmenting the JSX namespace's IntrinsicElements interface via a global declaration. Note that all the defs we need are accessible through the globalThis module -- only a single triple-slash directive is required

/// <reference types="@google/model-viewer" />

export declare global {
  namespace JSX {
    interface IntrinsicElements {
      "model-viewer": React.DetailedHTMLProps<
        React.AllHTMLAttributes<
          Partial<globalThis.HTMLElementTagNameMap['model-viewer']>
        >,
        Partial<globalThis.HTMLElementTagNameMap['model-viewer']>
      >;
    }
  }
}

The underlying definition of the globalThis.HTMLElementTagNameMap["model-viewer"] type is as follows

type ModelViewer = AnnotationInterface & SceneGraphInterface & StagingInterface & EnvironmentInterface &  ControlsInterface & ARInterface & LoadingInterface & AnimationInterface & ModelViewerElementBase;

important -- be sure to add src/types/react.d.ts to the include array field in your tsconfig.json for this JSX augmentation to be detected and incorporated

{
  "include": [
    "next-env.d.ts",
    "**/*.ts",
    "**/*.tsx",
    "src/types/react.d.ts"
  ],
}

Confirming Reacts acceptance of `model-viewer` as one of its very own

If you're curious to determine whether or not this somewhat convoluted augmentation file actually did the trick, head to any .tsx file and add a <model-viewer></model-viewer> element in the returned tsx. You'll notice that React has indeed accepted the model-viewer element as one of its very own 🎉

Below is the final code from the same file referenced at the very start of the article (src/pages/assets/glb/[glb].tsx):

import type {
  GetStaticPathsResult,
  GetStaticPropsContext,
  GetStaticPropsResult,
  InferGetStaticPropsType,
  PreviewData
} from "next";
import type { ParsedUrlQuery } from "querystring";
import { LoadingDots} from "@virtual-store/ui";
import { Suspense } from "react";
import { useRouter } from "next/router";

const DeviceObj = {
  UnrealMacBookPro14:
    "/v1668589751/VirtualTour/UnrealMacBookPro14_ynw7dg.glb",
  macbookair:
    "/v1668118327/VirtualTour/macbookair_ajugky.glb",
  macbook_pro_2021:
    "/v1668589750/VirtualTour/macbook_pro_2021_dby3mx.glb",
  delllatitude7330ruggedlaptop:
    "/v1668118348/VirtualTour/delllatitude7330ruggedlaptop_ziijbe.glb",
  "Lenovo M80q Tiny 2":
    "/v1668118312/VirtualTour/Lenovo_M80q_Tiny_2_jwtu9h.glb",
  lenovox1:
    "/v1668206027/VirtualTour/lenovox1_pldnaa.glb",
  lenovol13gen2:
    "/v1668206076/VirtualTour/lenovol13gen2_iewiqk.glb",
  genericlenovolaptop:
    "/v1668118314/VirtualTour/genericlenovolaptop_rjkvc8.glb",
  surfacehub:
    "/v1668118332/VirtualTour/surfacehub_epkes8.glb",
  surfacelaptop:
    "/v1668118326/VirtualTour/surfacelaptop_yajji1.glb",
  surfacelaptopstudio:
    "/v1668441368/VirtualTour/surfacelaptopstudio_mopmve.glb",
  SurfacePro7Plus:
    "/v1668118351/VirtualTour/SurfacePro7Plus_lxn8xe.glb",
  surfacestudio2:
    "/v1668118329/VirtualTour/surfacestudio2_tp8dp9.glb",
  thinkcentrem80qtiny:
    "/v1668206530/VirtualTour/thinkcentrem80qtiny_dal7ni.glb",
  thinkstationv2:
    "/v1668206602/VirtualTour/thinkstationv2_o8dxo8.glb"
} as const;

const paths = [
  "UnrealMacBookPro14",
  "macbookair",
  "macbook_pro_2021",
  "delllatitude7330ruggedlaptop",
  "Lenovo M80q Tiny 2",
  "lenovox1",
  "lenovol13gen2",
  "genericlenovolaptop",
  "surfacehub",
  "surfacelaptop",
  "surfacelaptopstudio",
  "SurfacePro7Plus",
  "thinkcentrem80qtiny",
  "thinkstationv2"
];

interface StaticPropsResultType {
  device: typeof DeviceObj[keyof typeof DeviceObj];
}

const posterPath =
  "/v1668208003/VirtualTour/initial-load_p0yyun-Circle_yzha4d.png";

async function htmlScaffolding(
  glbData: keyof typeof DeviceObj
): Promise<typeof DeviceObj[keyof typeof DeviceObj]> {
  const glbPath = DeviceObj[glbData];
  return glbPath;
}

export const getStaticPaths = async (): Promise<
  GetStaticPathsResult<ParsedUrlQuery>
> => {
  return {
    paths: paths.map(path => `/assets/glb/${path}`),
    fallback: true
  };
};

const queryParamHandler = (props: string | string[] | undefined) => {
  return typeof props !== "undefined"
    ? Array.isArray(props)
      ? props[0]
      : props
    : "";
};

export const getStaticProps = async (
  ctx: GetStaticPropsContext<ParsedUrlQuery, PreviewData>
): Promise<
  GetStaticPropsResult<StaticPropsResultType>
> => {
  const glb = ctx.params ? queryParamHandler(ctx.params.glb) : "lenovol13gen2";
  return {
    props: {
      device: (await htmlScaffolding(
        glb as keyof typeof DeviceObj
      )) satisfies StaticPropsResultType['device']
    }
  };
};

export default function Glb<T extends typeof getStaticProps>({
  device
}: InferGetStaticPropsType<T>) {
  const router = useRouter();
  return (
    <>
      {router.isFallback ? (
        <LoadingDots />
      ) : (
        <Suspense fallback={<LoadingDots />}>
          <div className='min-h-screen min-w-[100vw]' id='card'>
            <model-viewer
              src={device}
              id='viewer'
              shadow-intensity='1'
              camera-controls
              touch-action='pan-y'
              auto-rotate
              data-ar
              ar-status='not-presenting'
              ar-modes='webxr scene-viewer quick-look'
              poster={posterPath}
              className='modelViewer'>
              <button
                slot='ar-button'
                id='ar-button'
                className='bg-takeda-red font-normal tracking-wide text-white'>
                View in your space
              </button>
            </model-viewer>
          </div>
        </Suspense>
      )}
    </>
  );
}

For the sake of thoroughness, I've attached the contents of my global index.css file below. Towards the very bottom of the base layer you'll find model-viewer targeted. I would share the github repo link itself but unfortunately that's under lock and key.

@tailwind base;
@tailwind components;
@tailwind utilities;

@layer base {
  @font-face {
    font-family: "Gotham";
    src: url("/fonts/Gotham-Book.woff2") format("woff2");
    font-weight: 400;
    font-display: swap;
    font-style: normal;
  }
  /*
    Chrome has a bug with transitions on load since 2012!

    To prevent a "pop" of content, you have to disable all transitions until
    the page is done loading.

    https://lab.laukstein.com/bug/input
    https://twitter.com/timer150/status/1345217126680899584
  */
  body.loading * {
    transition: none !important;
  }

  /*
    Create a root stacking context
  */
  #__next {
    isolation: isolate;
  }

  *,
  *::before,
  *::after {
    box-sizing: border-box;
  }

  /*
    remove margin default
  */
  * {
    margin: 0;
  }

  html {
    height: 100%;
    box-sizing: border-box;
    touch-action: manipulation;
  }

  body {
    font-family: Gotham, 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";
    position: relative;
    line-height: calc(1em + 0.5rem);
    min-height: 100%;
    -webkit-font-smoothing: antialiased;
    text-rendering: optimizeLegibility;
    -moz-osx-font-smoothing: grayscale;
  }

  html,
  body {
    background-color: var(--accents-0);
    overscroll-behavior-x: none;
  }

  /*
    sensible media defaults
  */
  img,
  picture,
  video,
  canvas,
  svg,
  pre {
    display: block;
    max-width: 100%;
  }

  /*
    inherit fonts for form controls
  */
  input,
  button,
  textarea,
  select {
    font: inherit;
  }

  li {
    list-style: none;
  }

  a {
    color: inherit;
    text-decoration: none;
  }

  model-viewer {
    width: calc(100% - 1.25rem);
    height: calc(100vh - 1.25rem);
  }
}

@layer components {
  .modelViewer {
    @apply h-[calc(100vh-1.25rem)] w-[100%];
  }
  .tooltip {
    @apply invisible absolute transform-gpu transition-transform ease-in-out;
  }

  .has-tooltip {
    @apply visible z-50 my-auto -mt-1.5 border-collapse translate-x-3
    bg-opacity-75 px-1.5 py-2 text-xxs font-medium text-current;
  }
}

Import a .glb file type from a remote source or as a static asset and give it a try -- it will render near instantly and should have 0 errors both locally and in prod. Feels good to get rid of that dirty dangerouslyEscapeInnerHTML workaround used previously.

Thanks for reading along and please feel free to drop any questions, comments, or concerns below! Cheers

Unwrapping Reacts Core; access JSX.IntrinsicElement props globally (no imports required)

Andrew Ross — Thu, 24 Mar 2022 08:30:33 +0000

Update -- April 1st, 2022

The act of articulating my thoughts from writing this post sparked additional ideas centered around making this into an official npm package. The first iteration of unwrap-react was published on March 28th; one to two dozen iterations later, the package features full support for js-only users and excellent support for typescript users. Check it out here! There will be a part II outlining the ins and outs of using the package in various contexts in weeks to come, but the Readme on GitHub or on the official npm site itself offer a good start in the meantime!

How it Started

While working with forms in a current Next + Headless WordPress build I found myself wanting to access, for example, the props of an <input /> or a <button /> or an <a /> and so on and so forth using as little effort as possible. This resulted in many trial and error attempts at piecing together an intuitive, comprehensive, globally consumable solution (intellisense from the current working versions use with <main /> -- pictured below):

That said, and as one might expect, there were a number of partial-solutions preceding the current singular "one-size-fits-all" solution.

Defining an Objective

The ideal solution in my mind was two-fold: (1) global re-usability, project-agnostic, adhere to native (React namespace) type definition usage; (2) piece something together that even the most "cowabunga" of js-only developers could get behind -- without compromising on type safety at any time.

Phase One -- Generics = <3

If your aim involves tackling bigger picture, project-wide, type-related goals then generics are likely already an integral part of your arsenal. However, if you haven't worked with generics before then you're in luck! The remainder of this post deals with types that heavily rely on generic properties. You could say it's a typeof acquired taste, one that grows on you from the moment your first generic expression "clicks".

Generics -- a brief Primer

If you're already familiar with using generics feel free to skip ahead to the next section. If not, let's dive right in!

A Simple Generic Starter - Unwrapping a Promise

// disambiguation: see line 1482 of node_modules/typescript/lib/lib.es5.d.ts for info on Promise vs PromiseLike
export type UnwrapPromise<T> = T extends
  | PromiseLike<infer U>
  | Promise<infer U>
  ? U
  : T;

You might be asking yourself something along the lines of "When the hell exactly is this type useful? How is it useful? Why is it useful? In What contexts is it most useful?" which are great questions to consider. Scrutiny is a beautiful thing.

To address these hypothetical questions which you may or may not be asking yourself, the UnwrapPromise<T> type is exceedingly useful when it comes to inferring the return type of an async function (a promise)

Think of seeding files that return data with a whole lot going on in the context of types -- often manifesting as a single 1,000+ line async function in practice. Sounds like a royal pain in the ass to statically type out, right? Right. It absolutely would be -- but it can be tackled in a couple lines of clean generic-laced code -- let's approach this using our simple generic from above as the cornerstone (code snippets from another recent project linked here & within this paragraph above):

export async function seed<T extends import("@prisma/client").PrismaClient>(
  prisma: T
) {
// line 5 -- lots of data mimicry unfolds below
// ...
// line 1067 -- the main event
 const seedUser = async () => {
    return await prisma.user.create({
      data: {
       // schema.prisma models/types seeded here
      },
      include: {
        sessions: true,
        accounts: true,
        profile: true,
        entries: true,
        _count: true,
        comments: true
      }
    });
  };
  return seedUser();
} // line 1,193 -- let's unwrap this sizeable beast

// similar to the type we defined previously
type UnwrapPromise<T> = T extends Promise<infer U> ? U : T;

// use built-in ReturnType<T> inside of UnwrapPromise<T>
type SeedInferred = UnwrapPromise<ReturnType<typeof seed>>;

// enhance precision by extending Record<keyof U, infer U>

type SeedPropsInferred<U> = UnwrapPromise<
  typeof seed extends Record<keyof U, infer U>
    ? Record<keyof U, U>
    : UnwrapPromise<typeof seed>
>;

Two of the three generics that we just defined are integral parts of the main function below. The latter function calls on the lengthy seed function when a yarn seed script is executed in the terminal. This prompts the seed function to trigger, generating quasi-random data for a new user which is ultimately persisted by MongoDB Atlas for the particular repo in question.

At any rate, let's see how the return type of seed is inferred via the SeedInferred type which lets us know the exact shape of our data on success:

to circle back, this type

type SeedInferred = UnwrapPromise<ReturnType<typeof seed>>;

Extracts the following definition

Likewise, the "deepening" generic -- SeedPropsInferred -- extracts the type(s) employed by the targeted async function seed.

The SeedPropsInferred<U> type

type SeedPropsInferred<U> = UnwrapPromise<
  typeof seed extends Record<keyof U, infer U>
    ? Record<keyof U, U>
    : UnwrapPromise<typeof seed>
>;

Extracts the following definition for props used in the async seed function:

type SeedPropsInferred<U> = (<T extends PrismaClient<Prisma.PrismaClientOptions, never, Prisma.RejectOnNotFound | Prisma.RejectPerOperation | undefined>>(prisma: T) => Promise<...> extends Record<...> ? Record<...> : <T extends PrismaClient<Prisma.PrismaClientOptions, never, Prisma.RejectOnNotFound | Prisma.RejectPerOperation | undefined>>(prisma: T) => Promise<...>) extends Promise<...> ? U : <T extends PrismaClient<Prisma.PrismaClientOptions, never, Prisma.RejectOnNotFound | Prisma.RejectPerOperation | undefined>>(prisma: T) => Promise<...> extends Record<...> ? Record<...> : <T extends PrismaClient<Prisma.PrismaClientOptions, never, Prisma.RejectOnNotFound | Prisma.RejectPerOperation | undefined>>(prisma: T) => Promise<...>

Both SeedInferred and SeedPropsInferred are of utility when it comes to typing out the main function -- minimal effort, maximal results. Generics are powerful, the tradeoff being embracing additional complexity/abstraction for typesafe codebases and far fewer lines of code written

async function main() {
  const prisma = await import("../server/Context/prisma");
  try {
    await prisma.default
      .$connect()
      .then(() => console.log("[seeding]: db connection opened"));
    const s: SeedPropsInferred<{
      props: typeof prisma;
    }> = async (): Promise<SeedInferred> =>
      await seed(prisma.default).then(data => {
        console.log(
          JSON.stringify(
            `[seeding]: success 🎉 created ${data.role} with id ${data.id} and email ${data.email}`,
            null,
            2
          )
        );
        return data;
      });
    return await s(prisma.default);
  } catch (err) {
    console.error(err);
    process.exitCode = 1;
  } finally {
    return await prisma.default
      .$disconnect()
      .then(() => console.log(`[seeding]: db connection closed`));
  }
}

main();

The seed-invoking function, main, has the following shape according to TS Intellisense:

function main(): Promise<void | (User & {
    profile: Profile | null;
    accounts: Account[];
    sessions: Session[];
    entries: Entry[];
    comments: Comment[];
    _count: Prisma.UserCountOutputType;
})>

That said, the following snippet is arguably the most important to grapple with in the context of understanding type inference:

    const s: SeedPropsInferred<{
      props: typeof prisma;
    }> = async (): Promise<SeedInferred> =>
      await seed(prisma.default).then(data => {
        console.log(
          JSON.stringify(
            `[seeding]: success 🎉 created ${data.role} with id ${data.id} and email ${data.email}`,
            null,
            2
          )
        );
        return data;
      });
    return await s(prisma.default);

Why? Well, we know that the seed function takes prisma: PrismaClient as a prop, so it's only its return type(s) that would otherwise be a mystery. That, and it would be reasonable to assume that the success value returned by the main instantiating function mirrors that of the value returned by the seed function (it does). With the above logic in place intellisense doesn't miss a beat and perfectly infers the shape(s) of the returned data.

To illustrate that this does indeed work as intended, here is the cli output from executing the yarn seed script:

dopamine_driven@LAPTOP-2IH011V4:~/personal/port/next-prisma/next-prisma$ yarn seed
yarn run v1.22.18
$ ts-node src/seeds/seed.ts
[seeding]: db connection opened
"[seeding]: success 🎉 created USER with id 623d0997f9677901309ee6f8 and email kattie.gislason@gmail.com
[seeding]: db connection closed
Done in 5.36s.

This entry now exists on MongoDB -- no Mongo driver or running server required -- just a simple yarn seed to generate data in MongoDB Atlas. An aside, but it is a good idea to have two separate databases if opting into using a cloud service for local development

Upon checking the User collection in the dev database, we can see the seeded data for our most recently created user having email kattie.gislason@gmail.com

    _id: 623d0997f9677901309ee6f8
    imageMeta:
        - id:"623d0997f9677901309ee700"
        - uploadedAt: 2022-03-25T00:15:19.475+00:00
        - fileLastModified: 2022-03-18T18:59:20.314+00:00
        - quality: 100
        - filename: "Katties-fresh-avatar"
        - src: "https://dev-to-uploads.s3.amazonaws.com/uploads/articles/g4apn65eo8acy..."
        - srcSet: ""
        - filetype: "GIF"
        - size: "0.25MB"
        - width: 125
        - height: 125
        - caption: "Voluptatem nisi hic beatae accusantium."
        - description: "Nihil vel aliquid dignissimos quam expedita. Dolore recusandae eum dig..."
        - title: "Kattie Gislason's Avatar"
        - ariaLabel: "Accessibility label"
        - destination: "AVATAR"
    name: "Kattie Gislason"
    email: "kattie.gislason@gmail.com"
    username: "Kattie_Gislason"
    image: "https://dev-to-uploads.s3.amazonaws.com/uploads/articles/g4apn65eo8acy..."
    role: "USER"
    status: "OFFLINE"
    createdAt: 2022-03-25T00:15:19.476+00:00
    updatedAt: 2022-03-25T00:15:19.477+00:00
    email_verified: 2022-03-25T00:15:19.477+00:00

Nice. Now, back to React+JSX for the remainder of the article →

Phase Two: Unwrapping a single JSX.IntrinsicElement

First, let's find the type definition for an <input /> JSX.IntrinsicElement:

declare global {
    namespace JSX {
        // some interesting generic usage happening here 

        interface IntrinsicElements {
            // other elements
            input: React.DetailedHTMLProps<React.InputHTMLAttributes<HTMLInputElement>, HTMLInputElement>;
            // more elements
        }
    }
}

declare global { namespace JSX {} } was intentionally included in the above typedefinition as it's important to think about where types are coming from, where they could go, and how we could use generics to achieve various desired outcomes.

The first method I used when approaching this task was a localized, cut'n'dry, mimicry + mapping approach:

export type UnwrapInputProps<
  T extends keyof DetailedHTMLProps<
    InputHTMLAttributes<HTMLInputElement>,
    HTMLInputElement
  >
> = {
  [P in T]?: DetailedHTMLProps<
    InputHTMLAttributes<HTMLInputElement>,
    HTMLInputElement
  >[P];
};

In the above UnwrapInputProps type definition, T is extending the keyof an exact replica of the inner workings of the official input JSX.IntrinsicElement typedef we looked up at the start of this phase. UnwrapInputProps<T> is used for scaffolding custom input components in practice as follows:

export const InjectNameInput = ({
  ...props
}: UnwrapInputProps<
  | "className"
  | "type"
  | "name"
  | "autoComplete"
  | "id"
  | "required"
  | "value"
  | "onChange"
  | "placeholder"
>) => <input {...props} />;

Upon examining the intellisense it quickly becomes clear that...

...this is hardly an optimized or ideal approach as far as widespread adoption is concerned. Why? It necessitates the manual entering of each desired prop-type which can be annoying to remember and tedious to maintain, especially with multiple devs in a single codebase.

Let's see how InjectNameInput is actually consumed

            <InjectNameInput
              className={cn(
                `gform_${formIdRef.current}_gfield_nameinput_${
                  router.query.slug as string
                }`,
                placeholder.includes("Given Name")
                  ? "visible min-w-full"
                  : placeholder.includes("Surname")
                  ? "visible min-w-full"
                  : ""
              )}
              type='text'
              name={key}
              id={`input_${formIdRef.current}_${id}_${key}`}
              placeholder={placeholder}
              autoComplete={AUTOCOMPLETE_ATTRIBUTES[key]}
              value={nameValues?.[key] || ""}
              onChange={handleChange}
            />

Next, our final phase, phase tres. While there are other interesting intermediates on the way to the current working solution, heightened drowsiness and a desire to return to the code editor before sleep creeps in warrants getting to the point.

If you'd like for me to update this post and expand on one or two additional intermediate solutions that build off of the previous approach and the pros/cons therein please drop a comment letting me know below!

Phase Three -- The Utility of .d.ts files

First, head to your tsconfig.json file to ensure that the following flag is set -- "declaration": true

The contents of my current tsconfig.json (as of 2022-03-24)

{
  "compilerOptions": {
    "module": "esnext",
    "target": "ES2020",
    "lib": ["DOM", "DOM.Iterable", "ESNext"],
    "declaration": true,
    "strict": true,
    "pretty": true,
    "noImplicitAny": true,
    "strictNullChecks": true,
    "noImplicitThis": true,
    "alwaysStrict": true,
    "skipDefaultLibCheck": true,
    "moduleResolution": "Node",
    "sourceMap": true,
    "strictBindCallApply": true,
    "noStrictGenericChecks": false,
    "strictFunctionTypes": true,
    "noUnusedLocals": false,
    "noUnusedParameters": false,
    "jsx": "preserve",
    "downlevelIteration": true,
    "noImplicitReturns": true,
    "noFallthroughCasesInSwitch": true,
    "inlineSources": true,
    "experimentalDecorators": true,
    "strictPropertyInitialization": true,
    "baseUrl": "./",
    "allowJs": true,
    "sourceRoot": "./src",
    "checkJs": false,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "noEmit": true,
    "esModuleInterop": true,
    "resolveJsonModule": true,
    "allowSyntheticDefaultImports": true,
    "isolatedModules": true,
    "incremental": true,
    "paths": {
      "@/apollo/*": ["src/apollo/*"],
      "@/components/*": ["src/components/*"],
      "@/graphql/*": ["src/graphql/*"],
      "@/hooks/*": ["src/hooks/*"],
      "@/lib/*": ["src/lib/*"],
      "@/pages/*": ["src/pages/*"],
      "@/styles/*": ["src/styles/*"],
      "@/types/*": ["src/types/*"],
      "@/utils/*": ["src/utils/*"]
    }
  },
  "include": [
    "next-env.d.ts",
    "index.d.ts",
    "graphqls.d.ts",
    "src/**/*.ts",
    "src/**/*.d.ts",
    "src/**/*.graphqls.d.ts",
    "src/**/*.graphql.d.ts",
    "src/**/*.graphqls",
    "src/**/*.graphql",
    "src/**/*.tsx",
    "src/**/*.js",
    "src/**/*.gql"
  ],
  "exclude": ["node_modules"]
}

Right, on to the good stuff. With the declaration flag set to true, create a root index.d.ts file. Please be sure to "include" the file at the bottom of your tsconfig.json file within the "include": [] array too (for TS to detect it).

index.d.ts

// Recursive Optional Mapping good-good
declare type RecursiveOptional<T> = {
  [P in keyof T]?: RecursiveOptional<T[P]>;
};

// Strip RecursiveOptional wrapper post-recursion for 1:1 alignment with core react typedefs
declare type OmitRecursiveOptionalWrapper<T> = T 
extends RecursiveOptional<
  infer U
>
  ? U
  : T;

// strips the recursively conditional helper type for 1:1 alignment with Reacts internal definitions
declare const ReactRecursiveUnwrapped = ({
  jsxProps
}: {
  jsxProps: Partial<
    OmitRecursiveOptionalWrapper<
      RecursiveOptional<
        JSX.IntrinsicElements
      >
    >
  >;
}) => ({ ...jsxProps });

// TypeDef to use Globally
declare type ReactUnwrapped<
  T extends keyof ReturnType<typeof ReactRecursiveUnwrapped>
> = {
  [P in T]?: ReturnType<typeof ReactRecursiveUnwrapped>[P];
};

Let's break this down:

OmitRecursiveOptionalWrapper and RecursiveOptional are both helper types. RecursiveOptional conditionally maps all the props in <T[P]>.
The [P in keyof T]?: notation indicates that every property mapped is made conditional by the ?: operator. If that were instead [P in keyof T]-?: then every property mapped would be stripped of its conditional status and made required.
If your aim is to avoid manipulating the required vs conditional status for any given mapped property, simply omit the question mark altogether [P in keyof T]:.

OmitRecursiveOptionalWrapper is the yin to RecursiveOptional's yang in this context. How? Why? The Omitting Wrapper strips the transformed (conditionally mapped) output type of the RecursiveOptional typedef, which otherwise clashes with React's typedefs under the hood leading to errors.

The OmitRecursiveOptionalWrapper<T> type declaration may look familiar -- recall the config for the UnwrapPromise<T> type from Phase One:

declare type OmitRecursiveOptionalWrapper<T> = T 
extends RecursiveOptional<
  infer U
>
  ? U
  : T;

Breakdown of what's happening in the Omit Wrapper above:

T extends any RecursiveOptional-Wrapped property U and infers its type
if T does indeed extend or encounter such a configuration, it only returns the inner property U which consequently eliminates the outer RecursiveOptional type in the process
else, if it does not encounter a RecursiveOptional wrapped type, it simply returns T

The Bread'n'Butter

If you've made it this far I extend my thanks, may the force of generics be with you. Now the good stuff -- let's examine the two remaining declarations in question. The first, ReactRecursiveUnwrapped is a const that returns a destructured/spread jsxProps of type Partial<JSX.IntrinsicElements>

// strips the recursively conditional helper type for 1:1 alignment with Reacts internal definitions
declare const ReactRecursiveUnwrapped = ({
  jsxProps
}: {
  jsxProps: Partial<
    OmitRecursiveOptionalWrapper<
      RecursiveOptional<
        JSX.IntrinsicElements
      >
    >
  >;
}) => ({ ...jsxProps });

Let's take a look at the intellisense for this typedef:

But wait -- there are more typedefs assigned to the type of jsxProps initially...but also -- recall the yin/yang dynamic of the two helper types. OmitRecursiveOptionalWrapper wraps the RecursiveOptional wrapper to effectively cancel one another out after the internal JSX.IntrinsicElements interface has already been recursively (and conditionally) mapped out by the RecursiveOptional wrapper! Leaving us with a much friendlier typedef to work with -- Partial<JSX.IntrinsicElements>

Lastly, let's examine the ReactUnwrapped<T extends keyof ReturnType<typeof ReactRecursiveUnwrapped>> type which we will use globally with 0 imports required

declare type ReactUnwrapped<
  T extends keyof ReturnType<typeof ReactRecursiveUnwrapped>
> = {
  [P in T]?: ReturnType<typeof ReactRecursiveUnwrapped>[P];
};

The intellisense for T, which extends keyof ReturnType<typeof ReactRecursiveUnwrapped> -- which is equivalent to keyof ReturnType<Partial<JSX.IntrinsicElements>>-- is as follows:

T extends "symbol" | "object" | "a" | "abbr" | "address" | "area" | "article" | "aside" | "audio" | "b" | "base" | "bdi" | "bdo" | "big" | "blockquote" | "body" | "br" | "button" | "canvas" | ... 155 more ... | "view">

The ReturnType<T> for the declared const ReactRecursiveUnwrapped is equivalent to the definition of the JSX-namespace-residing IntrinsicElements{} interface

{
    a?: React.DetailedHTMLProps<React.AnchorHTMLAttributes<HTMLAnchorElement>, HTMLAnchorElement> | undefined;
    ... 173 more ...;
    view?: React.SVGProps<...> | undefined;
}

The only discernible difference? The recursive optional mapping, indicated by [P in T]?: within the ReactUnwrapped declaration, results in each JSX.IntrinsicElement having a conditionally undefined union type Type |undefined

Ultimately, the globally utilized type has the following general shape:

type ReactUnwrapped<T extends "symbol" | "object" | "a" | "abbr" | "address" | "area" | "article" | "aside" | "audio" | "b" | "base" | "bdi" | "bdo" | "big" | "blockquote" | "body" | "br" | "button" | "canvas" | ... 155 more ... | "view"> = { [P in T]?: {
    a?: React.DetailedHTMLProps<React.AnchorHTMLAttributes<HTMLAnchorElement>, HTMLAnchorElement> | undefined;
    ... 173 more ...;
    view?: React.SVGProps<...> | undefined;
}[P] | undefined; }

Since these types are declared in a root index.d.ts file they are automatically available for global consumption with zero imports required.

To recap, these four declarations are of immediate utility for our purposes:

declare type RecursiveOptional<T> = {
  [P in keyof T]?: RecursiveOptional<T[P]>;
};

declare type OmitRecursiveOptionalWrapper<T> = T 
extends RecursiveOptional<
  infer U
>
  ? U
  : T;

declare const ReactRecursiveUnwrapped = ({
  jsxProps
}: {
  jsxProps: Partial<
    OmitRecursiveOptionalWrapper<
      RecursiveOptional<
        JSX.IntrinsicElements
      >
    >
  >;
}) => ({ ...jsxProps });

declare type ReactUnwrapped<
  T extends keyof ReturnType<typeof ReactRecursiveUnwrapped>
> = {
  [P in T]?: ReturnType<typeof ReactRecursiveUnwrapped>[P];
};

Consuming the `ReactUnwrapped` type in .tsx files

Vercel tends to use a top-level Page component to wrap an apps Layout with. This Page component is adapted from Vercel's new @vercel/examples-ui package, the codebase for which can be found here

Now let's inject a <main /> JSX.IntrinsicElement with all of its native props to effectively make them available for consumption anytime the Page component is used elsewhere in your codebase as follows:

export const Page: FC<ReactUnwrapped<"main">> = ({ children, ...props }) => (
  <main
    {...props.main}
    className={cn(
      "w-full max-w-3xl mx-auto py-16",
      props.main?.className ?? ""
    )}>
    {children}
  </main>
);

Noteworthy mention

Notice how children (aka ReactNode) is passed into props, provided by the outer React Functional Component type wrapper, FC<ReactUnwrapped<"main">>. VFC, or Void Functional Component has become increasingly popular over the past year, being cited as better practice than FC as it doesn't automatically inject ReactNode (children) on each and every use. But what about the children being passed in to this globally significant Page wrapper? That's where ReactUnwrapped<T> comes in!

When using the ReactUnwrapped<"main"> type, all of the <main /> Intrinsic Elements props are injected including children. The above Page component can be rewritten as follows:

export const Page: VFC<ReactUnwrapped<"main">> = ({ ...props }) => (
  <main
    {...props.main}
    className={cn(
      "w-full max-w-3xl mx-auto py-16",
      props.main?.className ?? ""
    )}>
    {props.main?.children ?? <></>}
  </main>
);

This works for <div />, <svg />, <p />, <span />, or just about every other Intrinsic Element. With the global ReactUnwrapped<T> helper you can repurpose its intrinsic children prop to wherever is deemed most suitable.

A GitHub SVG

Example of injecting and using a GitHub Icon:

import type { VFC } from "react";

const GitHubIcon: VFC<ReactUnwrapped<"svg" | "path">> = ({ svg, path }) => (
  <svg
    {...svg}
    className={svg?.className ? svg.className : "h-6 w-6"}
    xmlns='http://www.w3.org/2000/svg'
    fill={svg?.fill ? svg.fill : "none"}
    viewBox='0 0 24 24'
    stroke={svg?.stroke ? svg.stroke : "currentColor"}>
    <path
      {...path}
      d='M12 0C5.374 0 0 5.373 0 12C0 17.302 3.438 21.8 8.207 23.387C8.806 23.498 9 23.126 9 22.81V20.576C5.662 21.302 4.967 19.16 4.967 19.16C4.421 17.773 3.634 17.404 3.634 17.404C2.545 16.659 3.717 16.675 3.717 16.675C4.922 16.759 5.556 17.912 5.556 17.912C6.626 19.746 8.363 19.216 9.048 18.909C9.155 18.134 9.466 17.604 9.81 17.305C7.145 17 4.343 15.971 4.343 11.374C4.343 10.063 4.812 8.993 5.579 8.153C5.455 7.85 5.044 6.629 5.696 4.977C5.696 4.977 6.704 4.655 8.997 6.207C9.954 5.941 10.98 5.808 12 5.803C13.02 5.808 14.047 5.941 15.006 6.207C17.297 4.655 18.303 4.977 18.303 4.977C18.956 6.63 18.545 7.851 18.421 8.153C19.191 8.993 19.656 10.064 19.656 11.374C19.656 15.983 16.849 16.998 14.177 17.295C14.607 17.667 15 18.397 15 19.517V22.81C15 23.129 15.192 23.504 15.801 23.386C20.566 21.797 24 17.3 24 12C24 5.373 18.627 0 12 0Z'
      fill={path?.fill ? path.fill : "currentColor"}
    />
    {svg?.children ? svg.children : <></>}
  </svg>
);

export default GitHubIcon;

Consuming

export const CustomDiv = ({ div }: ReactUnwrapped<"div">) => (
  <div {...div}>
    <GitHubIcon
      svg={{
        "aria-hidden": true,
        "aria-label": "GitHubIcon",
        onChange: e => {
          e.preventDefault();
          e.currentTarget.style.cssText.replace(
            "GitHubIcon",
            "Changing Text Underway"
          );
        }
      }}
      path={{
        name: "GitHubIconPath",
        onMouseOver: e => {
          e.preventDefault();
          // do things
        }
      }}
    />
    {div?.children}
  </div>
);

That's all for now, I'll check back in regularly to answer questions/update and polish this post. Thanks for reading along! You can check out the github repo that the bulk of this code originates from here

PS -- Twice a day🎉

Strongly Typed GA4 with Nextjs Part II - Danger Zone

Andrew Ross — Wed, 08 Sep 2021 06:19:11 +0000

In Part One of this series, prior to the release of Next v11, we covered configuring GA4 with Nextjs.

Since then, Nextjs has rolled out a next/script component which provides an alternative to dangerously escaping inner html -- a previously necessary evil when working with vanilla script tags.

Bonus: it's also more performant

Therefore, it's no longer necessary to live dangerously in the world of HTML -- semantics aside, we'll move the script tags we configured in _document.tsx in the first article over to _app.tsx.

Important Aside: Scripts must be instantiated above the Head (next/head) tag in Next.js pages and must never be used with the head in next/document

This syntactically sexy implementation can be executed as follows:

const Noop: FC = ({ children }) => <>{children}</>;

export default function NextApp({
  Component,
  pageProps
}: AppContext & AppInitialProps) {

  const LayoutNoop = (Component as any).LayoutNoop || Noop;

  const apolloClient = useApollo(pageProps);

  useEffect(() => {
    document.body.classList?.remove('loading');
  }, []);

  const router = useRouter();

  useEffect(() => {

    const handleRouteChange = (url: URL) => {
      gtag.pageview(url);
    };
    router.events.on('routeChangeComplete', handleRouteChange);
    return () => {
      router.events.off('routeChangeComplete', handleRouteChange);
    };
  }, [router.events]);

  return (
    <>
      <Script
        async
        strategy='lazyOnload'
        src={`https://www.googletagmanager.com/gtag/js?id=${GA_TRACKING_ID}`}
      />
      <Script strategy='afterInteractive'>
        {`
          window.dataLayer = window.dataLayer || [];
          function gtag(){dataLayer.push(arguments);}
          gtag('js', new Date());
          gtag('config', '${GA_TRACKING_ID}', {
            page_path: window.location.pathname,
          });
        `}
      </Script>
      <Head nextSeoProps={NextSEO} />
      <ApolloProvider client={apolloClient}>
        <AuthProvider>
          <GoogleFacebookProvider>
            <LayoutNoop pageProps={pageProps}>
              <Component {...pageProps} />
            </LayoutNoop>
          </GoogleFacebookProvider>
        </AuthProvider>
      </ApolloProvider>
    </>
  );
}

For those of you curious about various methods available when leveraging the new <Script /> component, you can read more here

Before eagerly firing up dev or deploying these changes to preview/production, be sure to remove the following XSS honeypot from the Head of _document.tsx

// ...
        <Head>
          <script
            async
            src={`https://www.googletagmanager.com/gtag/js?id=${GA_TRACKING_ID}`}
          />
          <script
            dangerouslySetInnerHTML={{
              __html: `
                  window.dataLayer = window.dataLayer || [];
                  function gtag(){dataLayer.push(arguments);}
                  gtag('js', new Date());gtag('config',
                  '${GA_TRACKING_ID}', {
                      page: window.location.pathname
                  });
              `
            }}
          />
        </Head>
// ...

Real Time Metric Reporting? Yes.

For those of you interested in sending real-time metrics to your google analytics property, you're in luck. Below your default export in _app.tsx, include the following function, and you'll have real-time metrics pinging in your GA4 dashboard before you know it

export function reportGAVitals({
  id,
  name,
  label,
  value
}: NextWebVitalsMetric) {
  if (typeof window !== 'undefined')
    window.gtag('event', name, {
      event_category: label === 'web-vital' ? 'Web Vitals' : 'Next.js custom metric',
      value: Math.round(name === 'CLS' ? value * 1000 : value), // values must be integers
      event_label: id, // id unique to current page load
      non_interaction: true // avoids affecting bounce rate.
    } as Gtag.EventParams);
}

Recall that the Gtag.EventParams type from the @types/gtag.js package is globally available for consumption with 0 imports required -- configured in a root index.d.ts file as follows:

index.d.ts

/// <reference types="gtag.js" />

declare module 'gtag.js';

That's it for now my fellow TypeScript fiends, but expect more strongly typed Nextjs articles to come! Feedback on topics you'd like to see covered with Next + TypeScript would be appreciated -- anything from graphql-codegen to apollo config to api routes to flawlessly typing dynamic routes with fallback set to true in a headless context and so on and so forth.

Cheers

Strongly Typed Google Analytics V4 with Nextjs

Andrew Ross — Fri, 04 Jun 2021 09:21:15 +0000

There are a number of articles out there describing various methods of configuring google analytics with next.js -- all written with untyped JavaScript. This article aims to remedy the absence of a strongly typed reference. The official next.js example serves as a good reference, yet, it too lacks strong types as it is written with JavaScript.

Install `@types/gtag.js` as a dev dependency

Open your terminal and run

yarn add -D @types/gtag.js

We will not be needing the vanilla (non-typed) gtag.js package, the react-ga package, or any other package for that matter. This is where declaration (**/*.d.ts) files really shine! Before getting started, navigate to your tsconfig.json file and ensure that the include flag specifies the **/*.d.ts glob pattern

"include": ["**/*.d.ts", "**/*.ts", "**/*.tsx", "**/*.js"],

Referencing Types in a local declaration file

First, create a root index.d.ts file. This is where we will configure a triple-slash directive types-reference to the @types/gtag.js dev-dependency. Once configured and declared, the types contained within @types/gtag.js will be globally available for consumption -- no imports required. Sure is nice

From typescriptlang.org:

`/// <reference types="..." />`

"Similar to a /// <reference path="..." /> directive, which serves as a declaration of dependency, a /// <reference types="..." /> directive declares a dependency on a package.

The process of resolving these package names is similar to the process of resolving module names in an import statement. An easy way to think of triple-slash-reference-types directives are as an import for declaration packages."

// ..

"Use these directives only when you’re authoring a d.ts file by hand."

As the official TS Docs indicate one should only use these directives when authoring (or extracting from) a .d.ts file by hand -- which fits the bill for our use-case with @types/gtag.js. I like to refer to unpaired or lone dev dependencies as stagpendencies -- they could use an introduction

With the formalities out of the way, add the following code to your index.d.ts file to give this package a proper "intro":

/// <reference types="gtag.js" />

declare module 'gtag.js';

Google Analytics V4 -- Acquire a Tracking ID

Head over to google analytics and sign in. If you don't have an account, create one, then sign in. Once signed in and on the landing page, click on the Admin gear icon in the bottom left corner then select + create property as pictured below

Next, add a property name and do not select create a universal property under advanced options. This writeup does not cover universal properties -- universal properties require the @types/google.analytics dev dependency to be properly typed.

Click next

then provide business information about your new google analytics property. Since the property I'm creating is an example for this article, I've selected other as the property type and only the top three options as being my intended use of google analytics. That said, if you are tracking a commerce site, for example, select additional desired options for your project.

Configure a Data Stream for your Property

Next, let's configure a data stream for our new property to start collecting data. Select web as a platform then fill in the website url and stream-name fields appropriately. The website url field should be the primary url of your production landing page.

Once finished, click "Create stream". This should navigate you to the "Web Stream Details" view. Copy the Measurement ID for your newly created property. We will be using this as an environmental variable. Note: do not use your stream id value. These two key-val pairs are not interchangeable. The measurement ID is always prefixed with G- in version 4 (as opposed to UA- in version 3) followed by a random 10-character-alphanumeric string (e.g., G-ABC4850XYZ)

Back to your code editor

After copying the measurement ID for your new property, open your code editor, create a .env.local file in the root directory, then add the following key-value pair

NEXT_PUBLIC_GA_TRACKING_ID=G-ABC4850XYZ

Next, create a root lib directory and an analytics.ts file therein. It is important to handle your measurement id environmental variable as a conditionally undefined string (process.env.* values always resolve to string | undefined)

@/lib/analytics.ts

 export const GA_TRACKING_ID = process.env.NEXT_PUBLIC_GA_TRACKING_ID ?? '';

Consuming the globalized reference types

As mentioned previously, there is no need to import anything to consume the reference @types/gtag.js types declared in the root index.d.ts file. Let's start with pageview:

export const pageview = (url: URL) => {
    window.gtag('config', GA_TRACKING_ID, {
        page_path: url
    });
};

you should see the following intellisense definition when hovering over the appended gtag of window.gtag

var gtag: Gtag.Gtag
(command: "config", targetId: string, config?: Gtag.ControlParams | Gtag.EventParams | Gtag.CustomParams | undefined) => void (+6 overloads)

if you Ctrl+click while hovering the window-appended gtag, it will take you to the node_modules/@types/gtag.js declaration file where you can view all of the type definitions provided by the @types/gtag.js package.

Let's export one additional function to track events associated with pageviews:

export const event = (
    action: Gtag.EventNames,
    { event_category, event_label, value }: Gtag.EventParams
) => {
    window.gtag('event', action, {
        event_category,
        event_label,
        value
    });
};

The action parameter measures user-initiated events. The destructured { event_category, event_label, value } parameters capture relevant analytics data for each of the action events.

The Gtag.EventNames (user actions) corresponds to the following unions defined by the EventNames type:

  type EventNames =
    | 'add_payment_info'
    | 'add_to_cart'
    | 'add_to_wishlist'
    | 'begin_checkout'
    | 'checkout_progress'
    | 'exception'
    | 'generate_lead'
    | 'login'
    | 'page_view'
    | 'purchase'
    | 'refund'
    | 'remove_from_cart'
    | 'screen_view'
    | 'search'
    | 'select_content'
    | 'set_checkout_option'
    | 'share'
    | 'sign_up'
    | 'timing_complete'
    | 'view_item'
    | 'view_item_list'
    | 'view_promotion'
    | 'view_search_results';

While we only used event_category, event_label, and value in this writeup, the Gtag.EventParams interface has the following shape

  interface EventParams {
    checkout_option?: string;
    checkout_step?: number;
    content_id?: string;
    content_type?: string;
    coupon?: string;
    currency?: string;
    description?: string;
    fatal?: boolean;
    items?: Item[];
    method?: string;
    number?: string;
    promotions?: Promotion[];
    screen_name?: string;
    search_term?: string;
    shipping?: Currency;
    tax?: Currency;
    transaction_id?: string;
    value?: number;
    event_label?: string;
    event_category?: string;
  }

any of these parameters can be used to track user-mediated events.

The contents of your @/lib/analytics.ts file should now look as follows:

export const GA_TRACKING_ID =
    process.env.NEXT_PUBLIC_GA_TRACKING_ID ?? '';

export const pageview = (url: URL) => {
    window.gtag('config', GA_TRACKING_ID, {
        page_path: url
    });
};

export const event = (
    action: Gtag.EventNames,
    { event_category, event_label, value }: Gtag.EventParams
) => {
    window.gtag('event', action, {
        event_category,
        event_label,
        value
    });
};

`pages/_document.tsx`

Nearly finished. Navigate to pages/_document.tsx and import the GA_TRACKING_ID constant that we exported from @/lib/analytics.ts

import Document, {
    Head,
    Html,
    Main,
    NextScript,
    DocumentContext,
    DocumentProps,
    DocumentInitialProps
} from 'next/document';
import { GA_TRACKING_ID } from '@/lib/analytics';

This file is important because it is used to augment the html, head, and body tags for all of the page files in our next.js repo. We will be injecting the Head of _document.tsx with two script tags as follows:

<Head>
    <meta charSet='utf-8' />
    <script
        async
        src={`https://www.googletagmanager.com/gtag/js?id=${GA_TRACKING_ID}`}
    />
    <script
        dangerouslySetInnerHTML={{
            __html: `window.dataLayer = window.dataLayer || [];
                    function gtag(){dataLayer.push(arguments);}
                    gtag('js', new Date());

                    gtag('config', '${GA_TRACKING_ID}', {
                        page: window.location.pathname
                    });`
        }}
    />
</Head>

For a holistic picture of _document.tsx, I'll include the contents of my current working file:

import Document, {
    Head,
    Html,
    Main,
    NextScript,
    DocumentContext,
    DocumentProps,
    DocumentInitialProps
} from 'next/document';
import { GA_TRACKING_ID } from '@/lib/analytics';
export default class FadeDocument extends Document<
    DocumentProps | unknown
> {
    static async getInitialProps(
        ctx: DocumentContext
    ): Promise<DocumentInitialProps> {
        const originalRenderPage = ctx.renderPage;
        const initialProps = await Document.getInitialProps(ctx);
        try {
            ctx.renderPage = () =>
                originalRenderPage({
                    enhanceApp: App => props => <App {...props} />
                });
        } catch (error) {
            console.log(error);
        }
        return {
            ...initialProps,
            styles: <>{initialProps.styles}</>
        };
    }

    render() {
        return (
            <Html lang='en-US'>
                <Head>
                    <meta charSet='utf-8' />
                    <link
                        rel='stylesheet'
                        href='https://rsms.me/inter/inter.css'
                    />
                    <link rel='shortcut icon' href='/meta/favicon.ico' />
                    <script
                        async
                        src={`https://www.googletagmanager.com/gtag/js?id=${GA_TRACKING_ID}`}
                    />
                    <script
                        dangerouslySetInnerHTML={{
                            __html: `window.dataLayer = window.dataLayer || [];
                                    function gtag(){dataLayer.push(arguments);}
                                    gtag('js', new Date());

                                    gtag('config', '${GA_TRACKING_ID}', {
                                        page: window.location.pathname
                                    });`
                        }}
                    />
                </Head>
                <body className='loading'>
                    <Main />
                    <NextScript />
                </body>
            </Html>
        );
    }
}

Wrapping this up in the root `_app.tsx` file

Navigate to the custom pages/_app.tsx file and import gtag as a wildcard (*) from @/lib/analytics. We will also be needing useEffect from React and useRouter from next/router. Add the following code within the default export function but before the returned tsx in your _app.tsx file:

    const router = useRouter();

    useEffect(() => {
        const handleRouteChange = (url: URL) => {
            gtag.pageview(url);
        };
        router.events.on(
            'routeChangeComplete',
            handleRouteChange
        );
        return () => {
            router.events.off(
                'routeChangeComplete',
                handleRouteChange
            );
        };
    }, [router.events]);

This code tracks pageview change events for the entirety of your app. I've included the full contents of my _app.tsx file below to provide a holistic view once more:

import '@/styles/index.css';
import '@/styles/chrome-bug.css';

import { AppProps, NextWebVitalsMetric } from 'next/app';
import { useEffect, FC } from 'react';
import { useRouter } from 'next/router';
import * as gtag from '@/lib/analytics';

const Noop: FC = ({ children }) => <>{children}</>;

export default function NextApp({
    pageProps,
    Component
}: AppProps) {
    const LayoutNoop = (Component as any).LayoutNoop || Noop;
    // remove chrome-bug.css loading class on FCP
    useEffect(() => {
        document.body.classList?.remove('loading');
    }, []);

    const router = useRouter();

    useEffect(() => {
        const handleRouteChange = (url: URL) => {
            gtag.pageview(url);
        };
        router.events.on(
            'routeChangeComplete',
            handleRouteChange
        );
        return () => {
            router.events.off(
                'routeChangeComplete',
                handleRouteChange
            );
        };
    }, [router.events]);

    return (
        <>
            <LayoutNoop pageProps={pageProps}>
                <Component {...pageProps} />
            </LayoutNoop>
        </>
    );
}

export function reportWebVitals(
    metric: NextWebVitalsMetric
): void {
    switch (metric.name) {
        case 'FCP':
            console.log('FCP: ', metric);
            break;
        case 'LCP':
            console.log('LCP: ', metric);
            break;
        case 'CLS':
            console.log('CLS: ', metric);
            break;
        case 'FID':
            console.log('FID: ', metric);
            break;
        case 'TTFB':
            console.log('TTFB: ', metric);
            break;
        case 'Next.js-hydration':
            console.log('Next.js-hydration: ', metric);
            break;
        case 'Next.js-route-change-to-render':
            console.log('Next.js-route-change-to-render: ', metric);
            break;
        case 'Next.js-render':
            console.log('Next.js-render: ', metric);
            break;
        default:
            break;
    }
}

Push - Deploy - Profit

Ensure that your deployment environment is provided with the NEXT_PUBLIC_GA_TRACKING_ID key-value pair, push your changes, successfully deploy, profit.

Check back in on google analytics after navigating around your newly deployed site to see if the data was successfully logged. That's all there is to incorporating strongly typed definitions into your next.js google analytics repo.

Hacking the Font Awesome Library with Next.js & TypeScript for Custom Icon Support

Andrew Ross — Wed, 19 Aug 2020 16:52:21 +0000

Overview

The aim of this article is to outline how to directly incorporate custom Fontawesome icons into your Next.js TypeScript project. For a solid introduction on setting up Fontawesome 5 with Next.js and TypeScript please see Vuong Dang's recent post.

1. Setting up for success

Create a lib directory in the root of your Next.js project. Then, create a fas-custom-integration.ts file where the magic will unfold. There is no tsx returned in the actual customization file itself which is why the library folder serves as its perfect home.

mkdir lib && cd lib && touch fas-custom-integration.ts && cd ..

2. A quick look under the hood

Head to the @fortawesome package in node_modules. Then, open fontawesome-svg-core/index.d.ts to inspect the contents of the declaration file:

import {IconDefinition, IconLookup, IconName, IconPrefix, IconPathData, IconPack } from '@fortawesome/fontawesome-common-types';
export {IconDefinition, IconLookup, IconName, IconPrefix, IconPathData, IconPack } from '@fortawesome/fontawesome-common-types';
export const dom: DOM;
export const library: Library;
export const parse: { transform(transformString: string): Transform };
export const config: Config;
export function noAuto():void;
export function findIconDefinition(iconLookup: IconLookup): IconDefinition;
export function text(content: string, params?: TextParams): Text;
export function counter(content: string | number, params?: CounterParams): Counter;
export function toHtml(content: any): string;
export function toHtml(abstractNodes: AbstractElement): string;
export function layer(
  assembler: (
    addLayerCallback: (layerToAdd: IconOrText | IconOrText[]) => void
  ) => void,
  params?: LayerParams
): Layer;

This is it, the librarians lair 📚. Examine the first two lines of this file. The very same Interfaces imported are exported immediately thereafter. What's important to note when viewing declaration files like this is where Interfaces of potential utility such as IconDefinition and IconLookup reside. So let's head on over to fontawesome-common-types/index.d.ts and view the contents of its declaration file.

3. Structure dictates function

Interfaces serve to describe the "shape" that values have in TypeScript. Personally, I prefer to think of this shape as its structure. If you're familiar with biology you may recall that "structure dictates function" is known as the Central Dogma of Life. This thinking can be carried over to Interface usage in TypeScript; interface structure introduces strict type requirements which breathes life into the code we write. It's do or die. Right, back to the hacking. With the contents of fontawesome-common-types/index.d.ts before us, the key to executing custom icon integration becomes increasingly clear.

export type IconPrefix = "fas" | "fab" | "far" | "fal" | "fad";
export type IconPathData = string | string[]

export interface IconLookup {
  prefix: IconPrefix;
  // IconName is defined in the code that will be generated at build time and bundled with this file.
  iconName: IconName;
}

export interface IconDefinition extends IconLookup {
  icon: [
    number, // width
    number, // height
    string[], // ligatures
    string, // unicode
    IconPathData // svgPathData
  ];
}

export interface IconPack {
  [key: string]: IconDefinition;
}

export type IconName = '500px' | 
  'accessible-icon' | 
  'accusoft' | 
  'acquisitions-incorporated' |
 // ...7,846 lines later...
  'wrench' | 
  'x-ray' | 
  'yen-sign' | 
  'yin-yang';

4. Dissecting Interfaces of utility

Since IconDefinition and IconLookup are of immediate utility for custom icon incorporation let's break each down each individually.

4(a). IconLookup

This Interface describes two values, prefix and iconName. The prefix value is a string corresponding to "faX" as defined by the IconPrefix type above (where X=b, d, l, r, or s). The free version of Fontawesome supports "fab" and "fas" prefixes which denote brand and solid icon styles, respectively. Then there's iconName which is defined by the IconName type. This type describes an array of strings totaling out to 7,854 icon names in length.

export type IconPrefix = "fas" | "fab" | "far" | "fal" | "fad";
export type IconPathData = string | string[]

export interface IconLookup {
  prefix: IconPrefix;
  // IconName is defined in the code that will be generated at build time and bundled with this file.
  iconName: IconName;
}

export type IconName = '500px' | 
  'accessible-icon' | 
  'accusoft' | 
  'acquisitions-incorporated' |
 // ...7,846 lines later...
  'wrench' | 
  'x-ray' | 
  'yen-sign' | 
  'yin-yang';

4(b). IconDefinition

export interface IconDefinition extends IconLookup {
  icon: [
    number, // width
    number, // height
    string[], // ligatures
    string, // unicode
    IconPathData // svgPathData -> string | string[]
  ];
}

Note that the IconDefinition Interface extends the IconLookup interface. This implies that the shape described by the IconLookup interface is extended, or copied, to the IconDefinition Interface. So, while it is evident that the shape of an icon is described by an array of five scalar values, it may not be as straightforward that the prefix and iconName values described by the IconLookup Interface will be prepended to the structure of our derived icon definition. IconDefinition extending IconLookup implies that our custom definition should look as follows:

const CustomIconExample: IconDefinition & IconLookup = {
  prefix: 'fab',
  iconName: 'example-icon',
    icon: [
        64, // (1)viewBox width
        64, // (2)viewBox height
        [], // (3)ligatures
        '#000000', // (4)fill/fillColor
        `M24 22.525H0` // (5)iconPath(s)
    ]
}

With that out of the way, let's break down the five scalar values involved in defining the shape of an icon. The width1 and height2 values derived from an SVG's viewBox correspond to the first two scalars required when defining an icon. The viewBox of an SVG defines the position and dimension of a user viewport. There are always four numerical values in a viewBox which are invariably ordered as follows:

[min-x min-y width height]

The third value involved in defining an icon corresponds to ligatures3 which are not important for our purposes. Read more about ligatures here. The fourth value of an icon denotes the "fill" of the SVG, or fillColor4, as indicated by the presence of a hex-value. Lastly, the iconPath5 data is ordered sequentially on a single line; there is a single space denoting row breaks within a path. If an SVG contains more than one path (d-value) a single space is used to denote the end of one path and the beginning of the next. Therefore both intra- and interpath breaks are denoted by a single space. It is important for paths to always be confined to a single line (horizontal scrolling needs love too).

5. Translating theory to practice

With a plan of attack in mind, let's get to it! Out of the node_modules and back to the fas-custom-integration.ts file in the lib directory we go. To prime the file for custom icon integration, import the library and the previously dissected Interfaces of utility:

import {
    library,
    IconDefinition,
    IconLookup
} from '@fortawesome/fontawesome-svg-core';

Since a real example requires a real SVG to derive values for our icon definition from, an SVG for the Vercel logo ▲ is provided below (formerly ZEIT).

<svg
    xmlns="http://www.w3.org/2000/svg"
    xmlns:xlink="http://www.w3.org/1999/xlink"
    aria-hidden="true"
    focusable="false"
    width="1em"
    height="1em"
    style="-ms-transform: rotate(360deg); -webkit-transform: rotate(360deg); transform: rotate(360deg);"
    preserveAspectRatio="xMidYMid meet"
    viewBox="0 0 24 24"
>
    <path d="M24 22.525H0l12-21.05l12 21.05z" fill="#626262" />
</svg>

You might be asking yourself "Is this a thinly veiled attempt at shamelessly promoting your favorite deployment platform?"

For those interested in utilizing a method that produces consistently formatted SVGs, save the SVG snippet above in a .svg file. Then, navigate to Figma, enter a workspace, and press Ctrl+Shift+k (or Cmnd+Shift+k for MacOS users out there). This opens your local filesystem allowing you to import the SVG as an image into the workspace. Then, right-click the newly added SVG image, hover over "copy", and select "copy as SVG". Paste the copied contents into your text editor and voila! The SVG from above is refactored as follows:

<svg
    width="1"
    height="1"
    viewBox="0 0 24 24"
    fill="none"
    xmlns="http://www.w3.org/2000/svg"
>
    <g clip-path="url(#clip0)">
        <path d="M1 0.938607H0L0.5 0.0615234L1 0.938607Z" fill="#626262" />
    </g>
    <defs>
        <clipPath id="clip0">
            <rect width="1" height="1" fill="white" />
        </clipPath>
    </defs>
</svg>

With a standardized SVG obtained via Figma, let the excising begin. Your custom icon const should resemble the following:

export const faCustomVercelIcon: IconDefinition & IconLookup = {
    prefix: 'fab',
    iconName: 'vercel-icon',
    icon: [
        24, 
        24, 
        [], 
        'none', 
        'M24 22.525H0l12-21.05l12 21.05z'
    ]
};

Now, pass the faCustomVercelIcon into the library

library.add(faCustomVercelIcon);

But wait, a TSLint error?! Not to worry, this is easily rectified. Navigate back to the @fortawesome package in node_modules and open fontawesome-common-types/index.d.ts once more. Simply add "vercel-icon" to the beginning of the IconName type.

export type IconName = 'vercel-icon' | '500px' | 
  'accessible-icon' | 
  'accusoft' | 
  'acquisitions-incorporated' | // ...

Looking good, IconName is now 7,855 icons strong. While we're here, let's tweak one additional type for clarity's sake. At the very top of the index.d.ts file, add "fac" to the IconPrefix type:

export type IconPrefix = "fas" | "fab" | "fac" | "far" | "fal" | "fad";

This prefix type denotes custom styled icons, or conquered, or whatever your heart desires. As long as you adhere to the faX notation for IconPrefix, Fontawesome is happy. With the TSLint error resolved, back to the fas-custom-integration.ts file in the lib directory we go. First, update the prefix to "fac". See? The library is more malleable than one might anticipate after all. There is one last modification to make but thankfully it does not involve returning to node_modules for a third time. Utilizing the extends property of TypeScript interfaces, the file should resemble the following:

import {
    library,
    IconDefinition,
    IconLookup
} from '@fortawesome/fontawesome-svg-core';

export interface CustomIconConstruct extends IconDefinition, IconLookup {}


export const faCustomVercelIcon: CustomIconConstruct = {
    prefix: 'fac',
    iconName: 'vercel-icon',
    icon: [
        24, 
        24, 
        [], 
        'none', 
        'M24 22.525H0l12-21.05l12 21.05z'
    ]
};

library.add(faCustomVercelIcon);

While it is best practice to define all custom icons in one file, the CustomIconConstruct interface that extends IconDefinition & IconLookup can now be imported throughout your project without having to go through the hastle of importing the two Interfaces of utility once more. So, how does this look in practice?

6. Importing to a tsx file to run locally

To test your custom icon out, open a file that ultimately renders to a pages directory file and import the following:

import { FontAwesomeIcon } from '@fortawesome/react-fontawesome';
import { faCustomVercelIcon } from '../lib/fas-custom-integration';

The following snippet is from a project that's currently under construction using Next, TypeScript, and Tailwindcss as frameworks.

<a
aria-label='react'
target='__blank'
href={vercel}
className='bg-customGray text-white hover:text-white hover:bg-iconHover transition-colors leading-normal duration-500 text-lg inline-block text-center items-center align-middle justify-center w-8 h-8 mx-1 my-2 pt-1 rounded-full focus:outline-none'
>

<FontAwesomeIcon
icon={faCustomVercelIcon}
className='flex align-middle text-center font-extrabold text-1xl pb-1'
size='lg'
/>

</a>

If you aren't familiar with tailwindcss don't worry about the className inline-styling above. That said, do note how the faCustomVercelIcon was received as props by the <FontAwesomeIcon /> JSX.Element. Success!

7. Priming for production

In order for custom icons to successfully deploy to a production environment, the following package(s) must be installed:

yarn

yarn add patch-package postinstall-postinstall

npm i patch-package

Then, execute the following command:

npx patch-package @fortawesome/fontawesome-common-types

This generates a patches folder in your directory that contains a file outlining local updates made to the targeted package. In our case, it's the library in which we added "vercel-icon" to type IconName and "fac" to type IconPrefix. Then, add the following postinstall script in package.json:

{
    "scripts": {
        "dev": "next",
        "build": "next build",
        "start": "next start",
        "postinstall": "npx patch-package"
    }
}

The postinstall script persists local changes made to node_modules even when package version updates are made.
Update: postinstall-postinstall is only necessary to install for yarn. But why? While the postinstall script does run after yarn and yarn add <package>, it does not run after yarn remove <package>. Therefore, running yarn remove <package> in the absence of postinstall-postinstall renders the .patch file containing module modifications ineffective since the postinstall script isn't executed (which I just learned firsthand). Fortunately, with postinstall-postinstall installed, the "postinstall" script is executed after running yarn remove <package>. However, the "postinstall" script will now be executed twice for yarn and yarn add <package> which implies that the "postinstall" script itself must be idempotent in nature (its value remaining unchanged when multiplied or otherwise operated on). End Update. The patch file generated after executing the aforementioned npx command should resemble the following:

diff --git a/node_modules/@fortawesome/fontawesome-common-types/index.d.ts b/node_modules/@fortawesome/fontawesome-common-types/index.d.ts
index b70b000..b6b2429 100644
--- a/node_modules/@fortawesome/fontawesome-common-types/index.d.ts
+++ b/node_modules/@fortawesome/fontawesome-common-types/index.d.ts
@@ -1,4 +1,4 @@
-export type IconPrefix = "fas" | "fab" | "far" | "fal" | "fad";
+export type IconPrefix = "fas" | "fab" | "fac" | "far" | "fal" | "fad";
 export type IconPathData = string | string[]

 export interface IconLookup {
@@ -21,7 +21,9 @@ export interface IconPack {

 }

-export type IconName = '500px' | 
+export type IconName = 'vercel-icon' | 
+'heroku-icon' |
+'500px' | 
   'accessible-icon' | 
   'accusoft' | 
   'acquisitions-incorporated' |

In summary, this process can be performed with any SVG file. That said, I do recommend utilizing Figma (or a similar tool) to standardize SVGs before excising the essential bits required to define custom icons. This concludes my first ever tech post. Thanks for following along and feel free to drop any questions/comments/concerns in the comments below. Happy coding!

DEV Community: Andrew Ross

Taming the Interactions API in the @google/genai SDK

Fixing TypeScript Inference in Google's Gemini Interactions API

The Problem isn't Verbosity, it's Impossibility

The Patch: Removing unknown From Union Types

Applying the Patch

Verifying the Patch

What the Patch Fixes

The Full Patch File

Bonus: Generic HttpResponse.json()

The Type Utilities: From Patched to Pleasant

UnionToRecord: The Core Transformation

CTR (Conditional to Required)

Putting It Together — GeminiEventMap

The Handler Pattern: Type-Safe Event Dispatch

Registering Handlers

Dispatch

Before vs. After

Before: Manual Narrowing Hell

After: Declarative, Composable, Typed.

Troubleshooting

MCP SDK Import Resolution

Bonus: Deep Research Config Reference

Closing Thoughts

"Ode to Advanced TypeScript", a poem by Grok

Backstory

Poetry

JSON Receipts

AWS Shell Scripting

Intro

Get information about all configured services in one script

Resolving code vs cursor command paths for WSL2 & Windows 11 setups

Ideal Setup

Solution to cursor overwriting the VSCode code . command

How to prevent this behavior automatically even with Cursor updates?

A Next.js 15 Dynamic Route Helper Type

The types to use

InferGSPRTWorkup<T>

InferGSPRT<T>

Usage

Summary

Nextjs versions 13 & 14

TypeScript React + Generics Part I — Time-Saving Patterns

Time is Money

The RemoveFields<T, keyof T> type

InternalLinkProps = LinkProps

What exactly is causing the error?

Extractor Types

The ExtractPropsTargeted Extractor Type

Using ExtractPropsTargeted within the PropsTargeted Mapper definition

The Payoff — PropsExcludeTargeted and PropsIncludeTargeted

The PropsExcludeTargeted type

My Personal Favorite — PropsIncludeTargeted

Wrapping it up

Recursively Clone Objects without sacrificing Type Safety

What not to do

(1/4) Writing the Base Depth type

(2/4) Writing the InferDepth generic type

(3/4) Defining the inferObj and objInference tandem

(4/4) To be non-readonly, or not to be

Wrapping it up

A strongly typed Google Model-Viewer implementation in React

Overview

@google/model-viewer

The Annoying Workaround

A Quick Type Reference

The Solution

src/pages/_app.tsx

src/types/react.d.ts

Confirming Reacts acceptance of model-viewer as one of its very own

Unwrapping Reacts Core; access JSX.IntrinsicElement props globally (no imports required)

Update -- April 1st, 2022

How it Started

Defining an Objective

Phase One -- Generics = <3

Generics -- a brief Primer

A Simple Generic Starter - Unwrapping a Promise

Phase Two: Unwrapping a single JSX.IntrinsicElement

Phase Three -- The Utility of .d.ts files

index.d.ts

The Patch: Removing `unknown` From Union Types

Bonus: Generic `HttpResponse.json()`

Solution to cursor overwriting the VSCode `code .` command

`InferGSPRTWorkup<T>`

`InferGSPRT<T>`

The `RemoveFields<T, keyof T>` type

`InternalLinkProps` = `LinkProps`

The `ExtractPropsTargeted` Extractor Type

Using `ExtractPropsTargeted` within the `PropsTargeted` Mapper definition

The Payoff — `PropsExcludeTargeted` and `PropsIncludeTargeted`

The `PropsExcludeTargeted` type

My Personal Favorite — `PropsIncludeTargeted`

(1/4) Writing the Base `Depth` type

(2/4) Writing the `InferDepth` generic type

(3/4) Defining the `inferObj` and `objInference` tandem

`@google/model-viewer`

`src/pages/_app.tsx`

`src/types/react.d.ts`

Confirming Reacts acceptance of `model-viewer` as one of its very own

Consuming the `ReactUnwrapped` type in .tsx files

Install `@types/gtag.js` as a dev dependency

`/// <reference types="..." />`

`pages/_document.tsx`

Wrapping this up in the root `_app.tsx` file