DEV Community: James Shopland

Using SVG Sprites with NextJS 13

James Shopland — Sun, 15 Oct 2023 00:00:00 +0000

Most of the popular icon libraries for React load the icons in an inefficient way, directly to JSX. There is a great twitter thread about the performance of this here, as well as a great article explaining the different methods and their trade-offs.

Today I'm going to show you how we can utilize svg sprite sheets in NextJs.

https://www.youtube.com/watch?v=_Xrz7FeOtC0

Credit

The code I will be using is slightly modified from Kent C. Dodds Epic Stack implementation. His is for Remix.js. I have modified a few parts to make it work on NextJs.

Getting Started

1. Create a folder to hold our icons

In the root level of your NextJs project, create a folder called /other/svg.

This is where we store our SVGs files. If you are using different icon libraries, its also good to create subfolders for those, such as /other/svg/lucide.

Now to add a icon, you can just copy its svg into a .svg file, but I'm going to show you a great tool to automate this for the popular React icon libraries.

Sly-cli is a tool that adds code from dependencies, but not the dependencies themselves. This will let us get the icon libraries svg file without all the React layers.

For example, to add the avatar and bell icon for radix icons, we would do this:

npx @sly-cli/sly add @radix-ui/icons camera card-stack --yes --directory ./other/svg/radix

You can also use:

npx @sly-cli/sly add

To use interactive mode to set this up easily from the terminal, as well as see the icons you can use listed, to easily select the ones you want. I will show you my sly.json later for a good starter configuration

2. Compiling the icons into a sprite

An SVG sprite utilizes the <symbol> for each of our icons, to become an element in one SVG. To generate this, we are going to utilise a script. You will have to run this each time you add a icon. If you used sly, you can set this up to run automatically after you add them. You can see this in my example sly.json I will leave in this blog.

First we need to install some dependencies:

npm install fs-extra glob node-html-parser @types/fs-extra --save-dev

Then we need the script. For NextJs, you want to create a file at the root level called build-icons.mts (Note: the .mts file extension is needed for the default NextJs app, unless you are running your app in module mode)

Link to script on GitHub, or copy and paste below

import * as path from "node:path";
import fsExtra from "fs-extra";
import { glob } from "glob";
import { parse } from "node-html-parser";

const cwd = process.cwd();
const inputDir = path.join(cwd, "other", "svg");
const inputDirRelative = path.relative(cwd, inputDir);
const typeDir = path.join(cwd, "types");
const outputDir = path.join(cwd, "public", "icons");
await fsExtra.ensureDir(outputDir);
await fsExtra.ensureDir(typeDir);

const files = glob
  .sync("**/*.svg", {
    cwd: inputDir,
  })
  .sort((a, b) => a.localeCompare(b));

const shouldVerboseLog = process.argv.includes("--log=verbose");
const logVerbose = shouldVerboseLog ? console.log : () => {};

if (files.length === 0) {
  console.log(`No SVG files found in ${inputDirRelative}`);
} else {
  await generateIconFiles();
}

async function generateIconFiles() {
  const spriteFilepath = path.join(outputDir, "sprite.svg");
  const typeOutputFilepath = path.join(typeDir, "name.d.ts");
  const currentSprite = await fsExtra
    .readFile(spriteFilepath, "utf8")
    .catch(() => "");
  const currentTypes = await fsExtra
    .readFile(typeOutputFilepath, "utf8")
    .catch(() => "");

  const iconNames = files.map((file) => iconName(file));

  const spriteUpToDate = iconNames.every((name) =>
    currentSprite.includes(`id=${name}`)
  );
  const typesUpToDate = iconNames.every((name) =>
    currentTypes.includes(`"${name}"`)
  );

  if (spriteUpToDate && typesUpToDate) {
    logVerbose(`Icons are up to date`);
    return;
  }

  logVerbose(`Generating sprite for ${inputDirRelative}`);

  const spriteChanged = await generateSvgSprite({
    files,
    inputDir,
    outputPath: spriteFilepath,
  });

  for (const file of files) {
    logVerbose("✅", file);
  }
  logVerbose(`Saved to ${path.relative(cwd, spriteFilepath)}`);

  const stringifiedIconNames = iconNames.map((name) => JSON.stringify(name));

  const typeOutputContent = `// This file is generated by npm run build:icons

export type IconName =
\t| ${stringifiedIconNames.join("\n\t| ")};
`;
  const typesChanged = await writeIfChanged(
    typeOutputFilepath,
    typeOutputContent
  );

  logVerbose(`Manifest saved to ${path.relative(cwd, typeOutputFilepath)}`);

  const readmeChanged = await writeIfChanged(
    path.join(inputDir, "README.md"),
    `# Icons

This directory contains SVG icons that are used by the app.

Everything in this directory is made into a sprite using \`npm run build:icons\`. This file will show in /public/icons/sprite.svg
`
  );

  if (spriteChanged || typesChanged || readmeChanged) {
    console.log(`Generated ${files.length} icons`);
  }
}

function iconName(file: string) {
  return file.replace(/\.svg$/, "").replace(/\\/g, "/");
}

/**
 * Creates a single SVG file that contains all the icons
 */
async function generateSvgSprite({
  files,
  inputDir,
  outputPath,
}: {
  files: string[];
  inputDir: string;
  outputPath: string;
}) {
  // Each SVG becomes a symbol and we wrap them all in a single SVG
  const symbols = await Promise.all(
    files.map(async (file) => {
      const input = await fsExtra.readFile(path.join(inputDir, file), "utf8");
      const root = parse(input);

      const svg = root.querySelector("svg");
      if (!svg) throw new Error("No SVG element found");

      svg.tagName = "symbol";
      svg.setAttribute("id", iconName(file));
      svg.removeAttribute("xmlns");
      svg.removeAttribute("xmlns:xlink");
      svg.removeAttribute("version");
      svg.removeAttribute("width");
      svg.removeAttribute("height");

      return svg.toString().trim();
    })
  );

  const output = [
    `<?xml version="1.0" encoding="UTF-8"?>`,
    `<!-- This file is generated by npm run build:icons -->`,
    `<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" width="0" height="0">`,
    `<defs>`, // for semantics: https://developer.mozilla.org/en-US/docs/Web/SVG/Element/defs
    ...symbols,
    `</defs>`,
    `</svg>`,
    "", // trailing newline
  ].join("\n");

  return writeIfChanged(outputPath, output);
}

async function writeIfChanged(filepath: string, newContent: string) {
  const currentContent = await fsExtra
    .readFile(filepath, "utf8")
    .catch(() => "");
  if (currentContent === newContent) return false;
  await fsExtra.writeFile(filepath, newContent, "utf8");
  return true;
}

Next, we want to add the command to run this script to out package.json.

  "scripts": {
    //...
    "build:icons": "npx tsx ./build-icons.mts"
  },

Now if we run npm run build:icons, you should see a sprite.svg file appear in /public/icons. It will also create a name.d.ts file in types. This is for TypeScript and helps us ensure we are referencing the correct icon.

3. Using SVG Sprites in NextJs

We can begin to use our icons within an SVG like below, where name is the icon name. If you used subfolder in the icon folder, the name will be folder/icon such as radix/camera.

    <svg {...props}>
      <use href={`/icons/sprite.svg}#${name}`} />
    </svg>

To create a reusable, typesafe and extensible Icon component, we can do something like this:

import { type SVGProps } from "react";
import { cn } from "@/lib/cn";
import { type IconName } from "@/types/name";

export { IconName };

export function Icon({
  name,
  childClassName,
  className,
  children,
  ...props
}: SVGProps<SVGSVGElement> & {
  name: IconName;
  childClassName?: string;
}) {
  if (children) {
    return (
      <span
        className={cn(`inline-flex items-center font gap-1.5`, childClassName)}
      >
        <Icon name={name} className={className} {...props} />
        {children}
      </span>
    );
  }
  return (
    <svg
      {...props}
      className={cn("inline self-center w-[1em] h-[1em]", className)}
    >
      <use href={`./icons/sprite.svg#${name}`} />
    </svg>
  );
}

This component uses the cn tailwind helper function. If you do not already have it you can create that in lib/cn.ts

import { clsx, type ClassValue } from "clsx"
import { twMerge } from "tailwind-merge"

export function cn(...inputs: ClassValue[]) {
  return twMerge(clsx(inputs))
}

Now to use our Icon component, we simply do:

<Icon className="h-4 w-4" name="radix/camera" />

Where name is the icon name. If you want the icon to appear to the left of text and be aligned, the component above can do that for you if you pass the text in as a child:

<Icon className="h-4 w-4" name="radix/pencil-1" childClassName="text-red-600">
  Auto aligned text, with icon on left
</Icon>

Note that you can pass in classNames to the child element using childClassName, or just use your own nested element.

4. Preload the sprite

To repload the sprite so its loaded and ready to use on page load, we need to create a client component for the NextJs App Router, called preload-resources.tsx

"use client";

import ReactDOM from "react-dom";

export function PreloadResources() {
  ReactDOM.preload("/icons/sprite.svg", {
    as: "image",
  });

  return null;
}

Then we want to use this at our top most layout.tsx

    <html lang="en">
      <PreloadResources />

5. Sly configuration

If you have used sly to help with creating the SVG files, here is my example configuration for Lucide and Radix Icons.

This will run the build script for you after adding icons.

{
  "$schema": "https://sly-cli.fly.dev/registry/config.json",
  "libraries": [
    {
      "name": "@radix-ui/icons",
      "directory": "./other/svg/radix",
      "postinstall": [
        "pnpm",
        "run",
        "build:icons"
      ],
      "transformers": []
    },
    {
      "name": "lucide-icons",
      "directory": "./other/svg/lucide",
      "postinstall": [
        "pnpm",
        "run",
        "build:icons"
      ],
      "transformers": []
    }
  ]
}

Wrapping Up

Hopefully the above helps you get started with using SVG sprites in NextJs and React. Its a great approach with good performance compared to alternatives. You can view the example repo, as well as the components and scripts here

One drawback to sprites is you don't typically install a library of icons and then use them like regular components, we have to use the build script. Further, there is no "tree-shaking" for sprites, all the icons you add will be added to it. So make sure you only add the ones you use.

The Easiest Way to Make Emails in JavaScript

James Shopland — Thu, 12 Oct 2023 00:00:00 +0000

If you have ever had to write and style an email using code, you know the pain of the email HTML. Its a mess of different compatibility and not as simple as just making a webpage. React email aims to solve this in JavaScript (not just React) and is one of the easiest ways I have seen to make a styled email with great compatibility, and even supports some of Tailwind.

Don't I need React?

No. While the package sounds like it was made for React projects only, its more complex than that. React wasn't just built for the web and Theo has a great explainer of this here.
Essentially, React is the underlying technology to make things composable and React-Dom is the layer that renders to HTML, React Email is the renderer to email HTML, which can be annoyingly difficult.

Getting Started

1. Installing React Email

To start, we need to install react-email and its components. You can install all the components separately, but for now I will install a package with all of them.

npm install react-email @react-email/components @react-email/render -E

2. Add a script to your package.json

Next, react-email has a preview mode to easily test your emails design. We are going to add a script to our package.json to easily run this. You can run the command manually if wanted.

{
  "scripts": {
    //...
    "dev": "email dev"
  }
}

If you are using NextJs I recommend making the script email dev --port 3001. This is because the email preview site also uses next, so it defaults to port 3000 which could conflict with your dev server.

3. Create an emails folder

By default, React-Email looks for a folder called emails for its email templates. You can change this by appending --dir [FOLDER] if wanted.

Once created we can add our first email template. This can have any name but must be a jsx or tsx.

import * as React from "react";
import { Html, Button } from "@react-email/components";

export default function Email() {
  return (
    <Html>
      <Button
        href="https://example.com"
        style={{ background: "#000", color: "#fff", padding: "12px 20px" }}
      >
        Click me
      </Button>
    </Html>
  );
}

See here for more complex examples.

4. Run the email preview site

If you added the script to your package.json above, all we have to do is:

npm run email

Now visit localhost:3000 to preview your emails.

5. React email to Html

Now that you have your template working, how do you utilize this in your email sender, such as nodemailer?

For this we need to make use of the render function. The example below is built using nodemailer, in a NextJS API Route.

import type { NextApiRequest, NextApiResponse } from "next";
import Email from "@/emails/example-email";
import { render } from "@react-email/render";

export default async function handler(
  req: NextApiRequest,
  res: NextApiResponse
) {
  await sendEmail({
    to: "hello@world.com",
    subject: "Hello",
    html: render(Email()),
  });

  return res.status(200).json({ message: "Success" });
}

This render function will return a string of the HTML of your email. You can pass in props to the Email() function too, for example if you needed to address someone by name, it would look like this Email({ name }), and the Email template would just have name as a React prop.

Tailwind?

React-Email has some support for tailwind. See their docs. Its worth noting it will only work with basic styling needs as email css support varies.

Emails, made simple

That is all you need to get started writing email easily in JavaScript. The react-email docs have lots of example, and show you how to integrate with things such as Nodemailer, SendGrid, Postmark, AWS SES, MailerSend, Plunk and more.

Its also worth checking out Resend. They are the maintainers of React-Email and have made a service to send messages with easy-to-use APIs/SDKs without having to worry about emails going to the spam folder.

Using Firebase Admin SDK with Next.js 13

James Shopland — Mon, 09 Oct 2023 00:00:00 +0000

I recently had to use Firestore Database and Firebase Storage for the backend of a NextJs application. This is a guide on how you can set this up. We will look at how to pull in a list of collections and their data, get a specific document by its ID, and lastly get an image from storage using the public download url.

I also show you how you can hide this public download url behind an API route for another level of obfuscation for your front-end.

Firebase Admin SDK

It's crucial to note that the Firebase Admin SDK and the Firebase SDK serve different purposes. The Firebase Admin SDK is designed for server-side environments, providing privileged access to your Firebase project's resources, such as Firebase Authentication, Realtime Database, Cloud Firestore, and more. On the other hand, the Firebase SDK is aimed at client-side development, enabling interaction with Firebase features directly from client applications. This guide is for the Admin SDK

Getting Started

The first thing you are going to need is a Firebase Project. To set this up start here. I go through this in the video above, if you do not already have one set up.

Once you have created the project, create a new web app within that project.

Once that is created, go ahead to the project settings. Here we need to download a service account private key. Go to the service accounts tab and click Generate new private key. This should download a JSON file we will use later

1. Add your environment variables

We will need to add four values to our environment variables. If you dont already have a .env file create one now. If you have one add these values in to the file:

NEXT_PUBLIC_FIREBASE_PROJECT_ID=
NEXT_PUBLIC_FIREBASE_STORAGE_BUCKET=
FIREBASE_PRIVATE_KEY=
FIREBASE_CLIENT_EMAIL=

Fill these values in with the respective values from the JSON you downloaded earlier. Storage bucket by default will be the project ID plus .appspot.com at the end. You can also find this in your project settings, under the web app configuration.

Warning:

Its worth reiterating, you do not want the contents of that JSON file to leak as someone could get access to your database with admin permissions, this is why we utilise the environment variables.
The ProjectID and Storage Bucket can be on the front-end however as they are not private. This is why they are prefixed with NEXT_PUBLIC.

2. Install npm packages

We will need the firebase-admin package, so go ahead and install that.

I also reccommend installing server-only, I will explain this in section 3.

npm install firebase-admin
npm install server-only --save-dev

3. Initialise Firebase Admin

Now that we have our configuration values, we need to create a function to utilise these. Create a file called firebaseAdmin.ts. This is the file we will use to store the configuration for firebase admin.

Populate the file with the code below, I'll explain the key points:

import "server-only";
import admin from "firebase-admin";

interface FirebaseAdminAppParams {
  projectId: string;
  clientEmail: string;
  storageBucket: string;
  privateKey: string;
}

function formatPrivateKey(key: string) {
  return key.replace(/\\n/g, "\n");
}

export function createFirebaseAdminApp(params: FirebaseAdminAppParams) {
  const privateKey = formatPrivateKey(params.privateKey);

  if (admin.apps.length > 0) {
    return admin.app();
  }

  const cert = admin.credential.cert({
    projectId: params.projectId,
    clientEmail: params.clientEmail,
    privateKey,
  });

  return admin.initializeApp({
    credential: cert,
    projectId: params.projectId,
    storageBucket: params.storageBucket,
  });
}

export async function initAdmin() {
  const params = {
    projectId: process.env.NEXT_PUBLIC_FIREBASE_PROJECT_ID as string,
    clientEmail: process.env.FIREBASE_CLIENT_EMAIL as string,
    storageBucket: process.env.NEXT_PUBLIC_FIREBASE_STORAGE_BUCKET as string,
    privateKey: process.env.FIREBASE_PRIVATE_KEY as string,
  };

  return createFirebaseAdminApp(params);
}

At the top of the file we import server-only. This adds a build time check to our project, that ensures any function run in this file is run in a server environment. This helps catch leaks into client components. Read more here.

The function initAdmin() will need to be called wherever we want to access firestore/storage. This ensures an application has been initialised. If its called and one is already initialised, it will return that instance and not create a new one.

4. Fetch data from firestore

To fetch some data from firestore, I am again going to create a new file to house our functions, with the server-only header as well. Mine will be called firebase.ts

I am going to add some example functions in here to fetch some data I have stored in the database, as well as a public download URL for a file I have stored in storage.

import "server-only";
import { getFirestore } from "firebase-admin/firestore";
import { getDownloadURL, getStorage } from "firebase-admin/storage";

export const getLinks = async () => {
  const firestore = getFirestore();
  const linkSnapshot = await firestore.collection("links").get();
  const documents = linkSnapshot.docs.map((link) => ({
    url: link.data().url,
    title: link.data().title,
    desc: link.data().desc,
  }));

  return documents;
};

export const getLogo = async () => {
  const firestore = getFirestore();
  const logoSnapshot = await firestore.collection("images").doc("logo").get();
  const logoData = logoSnapshot.data() as { url: string } | undefined;
  if (!logoSnapshot.exists || !logoData) {
    return null;
  }
  return logoData.url;
};

export const getLogoFromStorage = async () => {
  const bucket = getStorage().bucket();
  const file = bucket.file("logo.png");
  const imageUrl = await getDownloadURL(file);
  console.log(imageUrl);
  return imageUrl;
};

In the function getLogoFromStorage its worth noting the logo.png is the path to the file in firebases storage. So if you had it nested in a folder it would look something like this images/logo.png.

Further, the getLogoFromStorage function uses the firebase public download url. In Firebase, a public download URL is a unique link generated for a file stored in Firebase Cloud Storage, which allows the file to be accessed, provided they have the correct access token. The access token is a random UUIDv4 string that makes the URL hard to guess, thereby providing a level of security against unauthorized access. In a section below I explain how you can further hide this url from your users.

Lastly, these functions will not work unless we call the initAdmin function we defined earlier. Before you call these, make sure you do await initAdmin().

5. Using in Server Components

To use these in a server component, make sure the default export is an async function.

After that we need to make sure we call await initAdmin() to initalise the application set-up if it has not been already.

Then it is as simple as calling the functions to get the data we need.

export default async function Home() {
  await initAdmin();
  const links = await getLinks();
  const logo = "/api/image";
  return (
    // ...your react component
  )
}

6. Hiding Firebase Public Download URLs

To hide the public download URL, we are going to utilise a NextJS API route. This route will be used as the new url for the file. You could pass it additional parameters in the body to handle a range of files. For this example we are simply going to hide the URL of an image. You could also do this in any server environment that you can make requests in, such as Cloud Functions.

First create the API route, this will be a folder structure like this app/api/image/route.ts,

Next, add the following:

import { getLogoFromStorage } from "@/db/firebase";
import { initAdmin } from "@/db/firebaseAdmin";

export async function GET(request: Request) {
  await initAdmin();

  const imageUrl = await getLogoFromStorage();

  const response = await fetch(imageUrl);

  return new Response(response.body, { headers: response.headers });
}

Again, we are calling the initAdmin function to ensure the application is initialised.

Next we are simply using the same method to get the URL, but this time it will only occur on the server.

Lastly, we fetch the URL from within the function, and we return its response as a new one.

Now when you go to /api/image it will load in the image, but with a clean URL, and the public download URL with the access token has only been exposed to the server.