Prerequisites

1. AWS account

2. Github account

Launch EC2 Instance

Steps to follow:

1. Launch EC2 instance with Ubuntu AMI.

2. Select a Key Pair or generate a new one for ssh access.

3. Create a Security Group or select an existing one. You must allow ssh and http traffic.

4. Under the Advanced Details > User Data, add scripts for installing Nginx.

#!/bin/bash
# Update the package list
sudo apt update
sudo apt upgrade -y
# Install nginx
sudo apt install nginx -y
# Start and enable nginx
sudo systemctl start nginx
sudo systemctl enable nginx

Once the instance goes to running state, copy the public IPV4 address and open in a browser tab. You should be able to see default Nginx page.

Connect to EC2 Instance

You can connect to EC2 instance either using ssh or EC2 instance connect (3 in the image above). For simplicity, I recommend using EC2 instance connect. Click connect button in the next page.

Install Node.js and PM2

Run these command to install Node.js and PM2.

# Install Node.js and npm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
source ~/.bashrc
nvm install --lts

# Install pm2 globally
npm i pm2 -g

Clone Project from GitHub

If you clone any public repository then you can simply clone using https web URL without any issue.

git clone https://github.com/<username>/<project>.git

If your repository is private, then you need to use username and password for authentication. However, Github do not support password based authentication. Therefore you will need to create a personal access token.

Follow this link to learn how to create github personal access token.

Once you create your token, you can use that token instead of your password.

Run The Project

Now move to the project folder, install dependencies, build the project, and run the project using PM2.

cd your-project
# Install dependencies using ci command
npm ci
# Optional build step
npm run build
# Run project using pm2
pm2 start dist/index.js --name my-nodejs-api

pm2 command will run your project at the specified port for example 8080. Though the API is running at 8080 port, we can not use it yet. Because, our security group only allows requests at port 80 for http and 22 for ssh. Therefore, we update our Nginx configuration to forward all the requests at port 80 to port 8080.

Configure NGINX

Move to the nginx sites-available directory. Then duplicate the default file and give a custom name. This custom file will be the configuration file for our nodejs API.

cd /etc/nginx/sites-available
# Copy default file and name it my-nodejs-api.conf
sudo cp default my-nodejs-api.conf
# Open configuration file for editing
sudo nano my-nodejs-api.conf

Replace the location configuration with the following one and save the file.

location / {
        proxy_pass http://localhost:8080;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_cache_bypass $http_upgrade;
}

Now enable this configuration and disable the default configuration using the following commands.

# Disable default config
sudo unlink /etc/nginx/sites-enabled/default
# Enable our custom config
sudo ln -s /etc/nginx/sites-available/my-nodejs-api.conf /etc/nginx/sites-enabled/my-nodejs-api.conf

Now test the nginx configuration using the following command and look for the success message.

sudo nginx -t

If the configuration test passed then restart the nginx to start with the updated configuration.

sudo service nginx restart

Now test your API endpoint at the public IPV4 address using curl or postman.

Congratulations, you have successfully deployed your Node.js API in the EC2 instance.

Deploy New Builds

After pushing new codes into github repository, you have to connect to your EC2 instance either by using EC2 Connect or ssh. Then navigate to your project directory on the server and run below commands.

# Pull new codes from github (use your username and access token)
git pull
# Install dependencies
npm ci
# Optional build step
npm run build
# Restart your project with new build
pm2 restart my-nodejs-api

Conclusion

We have successfully deployed a NodeJS API project to AWS EC2 instance.

This deployment process is fully manual. In the next article of this series I will show how to setup CI/CD using Github Actions.

Bootstrap The Project

Generate a new Nextjs project and accept all the default settings, then install necessary dependencies.

npx create-next-app@latest contact-form
cd contact-form
yarn add nodemailer zod
yarn add -D @types/nodemailer

We have installed nodemailer for sending email and zod for validation.

Now install shadcn-ui and add some necessary UI components using their CLI.

npx shadcn-ui@latest init
npx shadcn-ui@latest add button card input label textarea toast

Shadcn should already generate its UI components into /src/components/ui directory. Now we are ready to implement our form.

Implement ContactForm component

// src/components/forms/ContactForm.tsx
import React from "react";
import { Label } from "../ui/label";
import { Button } from "../ui/button";
import { Input } from "../ui/input";
import { Textarea } from "../ui/textarea";
import { sendEmail } from "@/actions/sendEmail";

function ContactForm() {
  return (
    <form action={sendEmail} className="flex flex-col space-y-4">
      <div className="flex flex-col space-y-1.5">
        <Label htmlFor="name">Name</Label>
        <Input id="name" name="name" type="text" placeholder="John Doe" />
      </div>
      <div className="flex flex-col space-y-1.5">
        <Label htmlFor="email">Email</Label>
        <Input
          id="email"
          name="email"
          type="email"
          placeholder="john@example.com"
        />
      </div>
      <div className="flex flex-col space-y-1.5">
        <Label htmlFor="message">Message</Label>
        <Textarea
          id="message"
          name="message"
          placeholder="Your message here..."
          className="input"
        />
      </div>
      <Button type="submit">Submit</Button>
    </form>
  );
}

export default ContactForm;

Notice, in the form element we are using action attribute instead of onSubmit. Another important thing is, we do not need any useState hooks for storing form field values. Instead, we are using built-in html features for handling forms. Therefore the code is much simpler and less verbose.

Now look at the form element, <form action={sendEmail}>. Here, sendEmail is our Server Action (async function that runs on the server only) which is not implemented yet. Let's do implement that.

Implement sendEmail Server Action

// src/actions/sendEmail.ts
"use server";
import { createTransport } from "nodemailer";

// read environment variables
const RECEIVING_EMAIL = process.env.RECEIVING_EMAIL as string;
const SENDING_EMAIL = process.env.SENDING_EMAIL as string;
const SENDING_EMAIL_PASSWORD = process.env.SENDING_EMAIL_PASSWORD as string;

// create nodemailer transport for sending email
const transporter = createTransport({
  host: "smtp.gmail.com",
  port: 465,
  secure: true,
  auth: {
    user: SENDING_EMAIL,
    pass: SENDING_EMAIL_PASSWORD,
  },
});

export async function sendEmail(formData: FormData) {
  const name = formData.get("name") as string;
  const email = formData.get("email") as string;
  const message = formData.get("message") as string;

  const mailOptions = {
    from: { name: "Contact Me", address: SENDING_EMAIL },
    to: RECEIVING_EMAIL,
    replyTo: email,
    subject: `${name} <${email}>`,
    text: message,
    html: `
      <div>${message.replace(/\n/g, "<br>")}</div>
    `,
  };

  try {
    const sentMessageInfo = await transporter.sendMail(mailOptions);
    console.log("Message sent: %s", JSON.stringify(sentMessageInfo, null, 2));
    return {
      success: true, // let the client know the action was succeeded
      message: "Thank you for the message!", // message to display in the UI
    };
  } catch (err) {
    console.error(err);
    return {
      success: false, // let the client know the action was failed
      error: "Something went wrong!", // error description
      message: "Something went wrong!", // message to display in the UI
    };
  }
}

We have read three environment variables in the top.

• RECEIVING_EMAIL: your primary email address where you want to receive all emails.

• SENDING_EMAIL: this one is a no-reply email address, which is used only for sending emails.

• SENDING_EMAIL_PASSWORD: app specific password for your sending email.

App password is different from your regular password that you use for logging into gmail account. App password is used for accessing your gmail account programmatically.

To generate an app password go to https://myaccount.google.com and search for App Passwords. Then follow the instructions in the screen.

Insert all these three environment variables into the .env file.

SENDING_EMAIL=no-reply@gmail.com
SENDING_EMAIL_PASSWORD=secret_app_password
RECEIVING_EMAIL=primaryemail@example.com

Notice how we created nodemailer transport and use that to send the email. We always return success, message and error from the server action. So, the client component can use these values to update its UI, i.e. display the message using a toast or alert.

Show the form in the page

Now our ContactForm and the Server Action is ready to use. So, update the page component and display the contact form there.

// src/app/page.tsx
import ContactForm from "@/components/forms/ContactForm";
import {
  Card,
  CardContent,
  CardDescription,
  CardHeader,
  CardTitle,
} from "@/components/ui/card";

export default function Home() {
  return (
    <main className="flex  flex-col items-center justify-center p-24">
      <h1 className="text-4xl mb-24">Contact Me</h1>
      <Card>
        <CardHeader>
          <CardTitle>Get in touch</CardTitle>
          <CardDescription>
            Fill out the form below to get in touch with me.
          </CardDescription>
        </CardHeader>
        <CardContent>
          <ContactForm />
        </CardContent>
      </Card>
    </main>
  );
}

If you run the project now, hopefully you'll be able to see the contact form working. Good thing is, our form component is very concise, because we do not need to use useState hooks for storing form values. Another good thing is, we do not need to setup API route for Server Action. However, there are few things to consider,

• Submit button does not have a loading state.

• No success/error message showing in the UI.

• Our form does not cleanup when the mail is sent successfully.

• There is no form validation.

We will fix all these in next few steps.

Submit button loading state

We can use the useFormStatus hook to monitor current form submission status. The hook returns information like the pending property which tells you if the form is actively submitting.

However, there is a gotcha, the hook only works if it is called from a component which is rendered inside a <form>. This means, it will not work if we call the hook from our ContactForm component, because it is not rendered inside <form>, rather it is rendering the form. To solve this problem, we will extract the Submit button into a separate component and call the hook from there.

Create SubmitButton component like below:

// src/components/forms/SubmitButton.tsx
"use client";
import React from "react";
import { useFormStatus } from "react-dom";
import { ReloadIcon } from "@radix-ui/react-icons";
import { Button, ButtonProps } from "../ui/button";

type SubmitButtonProps = ButtonProps & { children?: React.ReactNode };

function SubmitButton({ children, ...rest }: SubmitButtonProps) {
  const { pending } = useFormStatus();

  return (
    <Button {...rest} disabled={pending}>
      {pending && <ReloadIcon className="animate-spin mr-2" />}
      {children}
    </Button>
  );
}

export default SubmitButton;

Now, use this SubmitButton component inside the ContactForm component.

// src/components/forms/ContactForm.tsx
...
-import { Button } from "../ui/button";
+import SubmitButton from "./SubmitButton";
...
function ContactForm() {
  return (
    <form action={sendEmail} className="flex flex-col space-y-4">
      ...
-      <Button type="submit">Submit</Button>
+      <SubmitButton type="submit">Submit</SubmitButton>
    </form>
  );
}
...

You should be able to see beautiful loading state when you submit the form now.

Display toast message

Our server action returns a response with success status, error if any, and message to display in the UI. But we are not using any of these informations yet.

We can use the useFormState hook to update the UI based on the result from our Server Action. Let's update the ContactForm component and show toast message based on the result from the Server Action.

// src/components/forms/ContactForm.tsx
...
import { toast } from "../ui/use-toast";
import { useFormState } from "react-dom";

// initial state for the useFormState hook
const initialState = {
  success: null,
  error: null,
  message: null,
};

function ContactForm() {
  const [{ success, message, error }, formAction] = useFormState(
    sendEmail,
    initialState
  );

  // display toast based on the success status
  if (success === true) {
    toast({ title: "Success", description: message, variant: "default" });
  } else if(success ===false) {
    toast({ title: "Error", description: message, variant: "destructive" });
  }

  return (
    // instead of using the sendEmail function,
    // we use the formAction function as the action
    <form action={formAction} className="flex flex-col space-y-4">
    ...
    </form>
  );
}

As we are passing the sendEmail action to the useFormState hook, the sendMail action will get a new first argument called current state. We need to make a small change into our action to allow this first argument.

// src/actions/sendEmail.ts
-export async function sendEmail(formData: FormData) {
+export async function sendEmail(currentState: any, formData: FormData) {

To make this toast function work properly we need to render the Toaster component from shadcn in a parent component (typically in the root layout component). Let's update the root layout component like below.

// src/app/layout.tsx
...
import { Toaster } from "@/components/ui/toaster";
...
export default function RootLayout({
  children,
}: Readonly<{
  children: React.ReactNode;
}>) {
  return (
    <html lang="en">
      <body className={inter.className}>
        {children}
        <Toaster />
      </body>
    </html>
  );
}

If you try sending a message now, you should be able to see a nice toast message.

Cleanup the form

Form is submitted successfully but it is still remains populated with the entered data. To cleanup the form, we need a reference to the <form> element. Update the ContactForm component like below.

// src/components/forms/ContactForm.tsx
"use client";
import React, { useRef } from "react";
...
function ContactForm() {
  const ref = useRef<HTMLFormElement>(null);
  ...
  if (success === true) {
    toast({ title: "Success", description: message, variant: "default" });
    ref.current?.reset(); // cleanup the form here
  }
  ...
  return (
    <form action={formAction} ref={ref} className="flex flex-col space-y-4">
    ...
  )
}
...

If the form action succeeded then the form will be cleaned up from now.

Form validation

Validation can be done in two places, client side and server side validation. We are going to focus on the server side validation in this article. Our goal is to display error message for each fields separately.

At first, install zod for validation.

yarn add zod

Now create a validator using zod.

// src/actions/validators/ContactFormValidator.ts
import { z } from "zod";

// zod schema for contact form
export const ContactFormSchema = z.object({
  name: z.string().min(2, { message: "Name must be at least 2 characters" }),
  email: z.string().email({ message: "Please provide a valid email address" }),
  message: z.string().min(10, { message: "Please elaborate your message" }),
});

export type ContactFormFlattenedErrors = z.inferFlattenedErrors<
  typeof ContactFormSchema
>;

// error types we are going to return from the sendEmail server action
export enum ContactFormErrorType {
  Internal = "Internal",
  ZodFieldErrors = "ZodFieldErrors",
}

// return type of sendEmail server action
export type SendEmailResponse = {
  success: boolean | null; // Whether the email was sent successfully
  error?: string | ContactFormFlattenedErrors["fieldErrors"] | null; // If success is false, this will be the error object or string
  errorType?: ContactFormErrorType | null; // If success is false, this will be the type of error
  message?: string | null; // Message (success/failure) should be displayed to the user
};

Let's update our sendEmail action and utilise the zod validator there.

// src/actions/sendEmail.ts
"use server";
import { createTransport } from "nodemailer";
import {
  SendEmailResponse,
  ContactFormSchema,
  ContactFormFlattenedErrors,
  ContactFormErrorType,
} from "./validators/ContactFormValidator";

// read environment variables
const RECEIVING_EMAIL = process.env.RECEIVING_EMAIL as string;
const SENDING_EMAIL = process.env.SENDING_EMAIL as string;
const SENDING_EMAIL_PASSWORD = process.env.SENDING_EMAIL_PASSWORD as string;

// create nodemailer transport for sending email
const transporter = createTransport({
  host: "smtp.gmail.com",
  port: 465,
  secure: true,
  auth: {
    user: SENDING_EMAIL,
    pass: SENDING_EMAIL_PASSWORD,
  },
});

export async function sendEmail(
  currentState: SendEmailResponse,
  formData: FormData
): Promise<SendEmailResponse> {
  const name = formData.get("name") as string;
  const email = formData.get("email") as string;
  const message = formData.get("message") as string;

  // validate using zod schema here
  const validatedData = ContactFormSchema.safeParse({ name, email, message });

  if (!validatedData.success) {
    // return early if validation failed
    const flattenedErrors: ContactFormFlattenedErrors =
      validatedData.error.flatten();
    return {
      success: false,
      error: flattenedErrors.fieldErrors,
      errorType: ContactFormErrorType.ZodFieldErrors,
    };
  }

  const mailOptions = {
    from: { name: "Contact Me", address: SENDING_EMAIL },
    to: RECEIVING_EMAIL,
    replyTo: email,
    subject: `${name} <${email}>`,
    text: message,
    html: `
      <div>${message.replace(/\n/g, "<br>")}</div>
    `,
  };

  try {
    const sentMessageInfo = await transporter.sendMail(mailOptions);
    console.log("Message sent: %s", JSON.stringify(sentMessageInfo, null, 2));
    return {
      success: true,
      message: "Thank you for the message!",
    };
  } catch (err) {
    console.error(err);
    return {
      success: false,
      error: "Something went wrong!",
      errorType: ContactFormErrorType.Internal,
      message: "Something went wrong!",
    };
  }
}

Notice that, when zod validation failed, we are sending

errorType = ContactFormErrorType.ZodFieldErrors and attach the flattened error fields in the error property of the returned object. This flattened field errors will be used to display error messages under corresponding input element in the ContactForm component.

For any other errors we are sending errorType = ContactFormErrorType.Internal with a generic error i.e. Something went wrong!. This generic error will be displayed in the toast message.

Our goal is to display error messages in red colour under corresponding input element. Let's create a separate component for this.

// src/components/ui/typography.tsx
import React from "react";
import { VariantProps, cva } from "class-variance-authority";
import { cn } from "@/lib/utils";

const typographySmallVariants = cva("text-sm font-light leading-none", {
  variants: {
    variant: {
      default: "text-primary",
      destructive: "text-destructive",
    },
  },
  defaultVariants: {
    variant: "default",
  },
});

export interface TypographySmallProps
  extends React.HTMLAttributes<HTMLSpanElement>,
    VariantProps<typeof typographySmallVariants> {}

export const TypographySmall = React.forwardRef<
  HTMLSpanElement,
  TypographySmallProps
>(function TypographySmall({ className, variant, ...props }, ref) {
  return (
    <small
      className={cn(typographySmallVariants({ variant, className }))}
      ref={ref}
      {...props}
    />
  );
});

We exported TypographySmall component which renders HTML <small> element. This component also have two variants, default and destructive. We'll use the destructive variant for displaying error message in red colour.

Now, let's update the ContactForm component. Here is the updated ContactForm component.

// src/components/forms/ContactForm.tsx
"use client";
import React, { useRef } from "react";
import { Label } from "../ui/label";
import { Input } from "../ui/input";
import { Textarea } from "../ui/textarea";
import { sendEmail } from "@/actions/sendEmail";
import { type SendEmailResponse } from "@/actions/validators/ContactFormValidator";
import SubmitButton from "./SubmitButton";
import { toast } from "../ui/use-toast";
import { useFormState } from "react-dom";
import { TypographySmall } from "../ui/typography";
import { isObject } from "@/lib/isObject";
import clsx from "clsx";

// initial state of the form
const initialState: SendEmailResponse = {
  success: null,
  error: null,
  errorType: null,
  message: null,
};

function ContactForm() {
  const ref = useRef<HTMLFormElement>(null);
  // success, message, error, errorType will get the returned values from the sendEmail action
  const [{ success, message, error, errorType }, formAction] = useFormState(
    sendEmail,
    initialState
  );

  if (success === true) {
    // show success toast
    toast({ title: "Success", description: message, variant: "default" });
    // cleanup the form
    ref.current?.reset();
  } else if (success === false && errorType === "Internal") {
    // if error type is Internal then show toast message
    toast({
      title: "Error",
      description: message,
      variant: "destructive",
    });
  }

  return (
    <form action={formAction} ref={ref} className="flex flex-col space-y-4">
      <div className="flex flex-col space-y-1.5">
        <Label htmlFor="name">Name</Label>
        <Input
          id="name"
          name="name"
          type="text"
          placeholder="John Doe"
          className={clsx({
            "border-destructive": isObject(error) && error.name,
          })}
        />
        {isObject(error) && error.name && (
          <TypographySmall variant="destructive">{error.name}</TypographySmall>
        )}
      </div>
      <div className="flex flex-col space-y-1.5">
        <Label htmlFor="email">Email</Label>
        <Input
          id="email"
          name="email"
          type="email"
          placeholder="john@example.com"
          className={clsx({
            "border-destructive": isObject(error) && error.email,
          })}
        />
        {isObject(error) && error.email && (
          <TypographySmall variant="destructive">{error.email}</TypographySmall>
        )}
      </div>
      <div className="flex flex-col space-y-1.5">
        <Label htmlFor="message">Message</Label>
        <Textarea
          id="message"
          name="message"
          placeholder="Your message here..."
          className={clsx({
            input: true,
            "border-destructive": isObject(error) && error.message,
          })}
        />
        {isObject(error) && error.message && (
          <TypographySmall variant="destructive">
            {error.message}
          </TypographySmall>
        )}
      </div>
      <SubmitButton type="submit">Submit</SubmitButton>
    </form>
  );
}

export default ContactForm;

We have conditionally render <TypographySmall> component under each input/textarea emelents. You might be noticed that we are using isObject utility function. It basically checks whether the error field is object or not. Code of this function is given below.

// src/lib/isObject.ts
export function isObject(value: any): value is Record<string, unknown> {
  return typeof value === "object" && value !== null;
}

That's it. Hopefully you'll be able to see field level errors now.

Conclusion

Complete code of this project can be found here: https://github.com/mazid1/contact-form-with-server-actions

If you have any concern, let me know in the comment section.

I'm open for a remote full-time/contract/freelance job for the position of Full-stack Software Engineer. If you are hiring, ping me at mazidmailbox@gmail.com

Imagine, we have a nodejs server and we have got a requirement, the API needs to send a welcome message to the logged-in user. This is very simple, right?

type Message = { title: string; body: string; };

function getWelcomeMessage(): Message {
    const welcomeMessage: Message = {
        title: "Welcome",
        body: "Welcome to the Fun World!"
    };
    return welcomeMessage;
}

Now we can call this getWelcomeMessage function from the /login route handler when login succeeded.

app.post('/login', authMiddleware, (req, res) => {
    // Run other logics here, maybe set auth token in cookie.
    const message = getWelcomeMessage();
    res.send(message);
});

The client will want to change the message once they get a better welcome message for sure. Instead of hardcoding the message in the source code, it will be better to move it to a file or environment variable.

# .env file
WELCOME_MESSAGE_TITLE="Welcome"
WELCOME_MESSAGE_BODY="Welcome to the Fun World!"

type Message = { title: string; body: string; };

function getWelcomeMessage(): Message {
    const welcomeMessage: Message = {
        title: process.env.WELCOME_MESSAGE_TITLE,
        body: process.env.WELCOME_MESSAGE_BODY
    };
    return welcomeMessage;
}

Now the client do not need to change the source code just for changing the welcome message. Cool!

Very soon another requirement comes, we need to support another language. For this case, we need to support Bangla and English. So, lets update the .env file and getWelcomeMessage function like below.

# .env file
WELCOME_MESSAGE_TITLE_EN="Welcome"
WELCOME_MESSAGE_BODY_EN="Welcome to the Fun World!"
WELCOME_MESSAGE_TITLE_BN="স্বাগতম"
WELCOME_MESSAGE_BODY_BN="মজার বিশ্বে স্বাগতম!"

type Language = 'en' | 'bn';
type Message = { title: string; body: string; };

function getWelcomeMessage(language: Language): Message {
    let welcomeMessage: Message;
    switch(language) {
        case 'en':
            welcomeMessage = {
                title: process.env.WELCOME_MESSAGE_TITLE_EN,
                body: process.env.WELCOME_MESSAGE_BODY_EN
            }
            break;
        case 'bn':
            welcomeMessage = {
                title: process.env.WELCOME_MESSAGE_TITLE_BN,
                body: process.env.WELCOME_MESSAGE_BODY_BN
            }
            break;
        default:
            // Set default message in English
            welcomeMessage = {
                title: process.env.WELCOME_MESSAGE_TITLE_EN,
                body: process.env.WELCOME_MESSAGE_BODY_EN
            }
    }
    return welcomeMessage;
}

This function works fine. However, notice that, this function will read from environment each time it will be executed. Reading from file or environment is costly. It is a good practice to load environment variables in memory. Let's do that.

type Language = 'en' | 'bn';
type Message = { title: string; body: string; };
type WelcomeMessages = Record<Language, Message>;

// When the file first executed the environment variables will be
// loaded and stored into "welcomeMessages" variable.
const welcomeMessages: WelcomeMessages = {
    en: {
        title: process.env.WELCOME_MESSAGE_TITLE_EN,
        body: process.env.WELCOME_MESSAGE_BODY_EN
    },
    bn: {
        title: process.env.WELCOME_MESSAGE_TITLE_BN,
        body: process.env.WELCOME_MESSAGE_BODY_BN
    }
}

function getWelcomeMessage(language: Language): Message {
    // Read from the cached variable, no need to read from .env again
    return welcomeMessages[language];
}

Looks very simple and easy right? But we have already made a mistake. If you did not notice that, don't worry, we'll figure it out soon.

A few weeks later, a new requirement came. Client wanted to display current user's name in the welcome message body. That means, we need a placeholder in the welcome message body and we need to be able to replace the placeholder with the name of the current user. To do that, I added a placeholder like this <name>.

# .env file
WELCOME_MESSAGE_TITLE_EN="Welcome"
WELCOME_MESSAGE_BODY_EN="Hi <name>, welcome to the Fun World!"
WELCOME_MESSAGE_TITLE_BN="স্বাগতম"
WELCOME_MESSAGE_BODY_BN="<name>, মজার বিশ্বে স্বাগতম!"

Now, once we get the message, we can replace the placeholder in our route handler.

app.post('/login', authMiddleware, (req, res) => {
    const message = getWelcomeMessage(req.user.language);
    // You may argue we should implement this replace logic inside
    // getWelcomeMessage function. For the sake of this example we
    // are doing this here.
    message.body.replace('<name>', req.user.name);
    res.send(message);
});

Did you notice the mistake this time? Let's say we test our project locally with our test user account. We will get expected response from our login route. However, once we deploy this project in server, and many users started to login, everyone will get only one name is there. Seems like the name is hardcoded.

So the summary is, when the login route handler function executed for the first time it will work fine. But it will not work for the subsequent executions.

const message = getWelcomeMessage('en');
message.body.replace('<name>', 'Mazedul');
// message.body == "Hi Mazedul, welcome to the Fun World!"
const message2 = getWelcomeMessage('en');
message.body.replace('<name>', 'Hashnode');
// message2.body == "Hi Mazedul, welcome to the Fun World!"
// Name did not changed for the second execution!!!

Why it is not working for the subsequent executions? Well the bug is very simple, our getWelcomeMessage function is buggy. Let's have a closer look.

// When the file first executed the environment variables will be
// loaded and stored into "welcomeMessages" variable.
const welcomeMessages: WelcomeMessages = {
    en: {
        title: process.env.WELCOME_MESSAGE_TITLE_EN,
        body: process.env.WELCOME_MESSAGE_BODY_EN
    },
    bn: {
        title: process.env.WELCOME_MESSAGE_TITLE_BN,
        body: process.env.WELCOME_MESSAGE_BODY_BN
    }
}

function getWelcomeMessage(
    language: Language,
    userName: string
): Message {
    // Read from the cached variable, no need to read from .env again.
    const message = welcomeMessages[language];
    // message variable is now pointing to the cached variable
    // welcomeMessages.en or welcomeMessages.bn depending on the
    // language.
    return message;
}

When we replace the placeholder in the route handler function it mutate the cached welcomeMessages variable. Therefore, subsequent executions do not get any <name> placeholder to replace.

In this small example project it is very easy to understand the bug. However, in a complex large project with several level of abstractions it can be very difficult to debug this issue.

The fix is very easy. Instead of mutating the cached object, we need to create a copy and then modify it. The getWelcomeMessage function should not return the reference to the cached object, instead it should return a copy object.

function getWelcomeMessage(
    language: Language,
    userName: string
): Message {
    const message = { ...welcomeMessages[language] };
    return message;
}

Now the function creates a new object each time it is executed. So the bug is fixed. You can also consider using Lodash cloneDeep function for a complex object.

Moral: Never return reference of a private object to the function caller.

It is often required to seed a database with initial data during development. In a NestJS + TypeORM project, we can do that with the help of typeorm-extension.

Initial project setup

Let's initialize our project using Nest CLI.

nest new nest-typeorm

Navigate to the project folder and install the necessary dependencies. In this example, I am using PostgreSQL, therefore I have added pg as a dependency.

cd nest-typeorm
npm install --save @nestjs/typeorm typeorm pg

Database connection

Let's create a separate Nest module for handling database-related tasks.

nest g module db

Create the data-source.ts file inside the src/db directory. This file will contain database connection configurations.

// src/db/data-source.ts
import { config } from 'dotenv';
import { DataSourceOptions } from 'typeorm';

config();

export const dataSourceOptions: DataSourceOptions = {
  type: 'postgres',
  host: process.env.DB_HOST,
  port: +process.env.DB_PORT,
  username: process.env.DB_USER,
  password: process.env.DB_PASSWORD,
  database: process.env.DB_NAME,
  entities: ['dist/resources/**/*.entity.js'],
  synchronize: true, // do not set it true in production application
};

Setting synchronize: true shouldn't be used in production - otherwise you can lose production data. You should use migration instead. I have an article on How to setup TypeORM migrations in a NestJS project.

Use this dataSourceOptions for setting up TypeOrmModule inside the DbModule that we generated using Nest CLI.

// src/db/db.module.ts
import { Module } from '@nestjs/common';
import { TypeOrmModule } from '@nestjs/typeorm';
import { dataSourceOptions } from './data-source';

@Module({
  imports: [TypeOrmModule.forRoot(dataSourceOptions)],
})
export class DbModule {}

Now if you run the project using npm run start:dev command, it should be able to connect to the database. However, you have to make sure the database server is up and running and the database with the name that we specified in the data-source file is already created.

Generate an entity

Generate users resource using the CLI.

nest g resource resource/users

It will generate the users module, controller, service, DTOs and entity file inside src/resource/users directory.

Let's update the user.entity.ts file and add some columns there.

// src/resources/users/entities/user.entity.ts
import { Column, Entity, PrimaryGeneratedColumn } from 'typeorm';

@Entity()
export class User {
  @PrimaryGeneratedColumn()
  id: number;

  @Column({ name: 'first_name' })
  firstName: string;

  @Column({ name: 'last_name' })
  lastName: string;
}

Since we set synchronize: true in our datasource options, if we run this project using npm start command, it should create the user table in our database.

The database should already be running in the specified host and port before running the app.

If the user table is created successfully then we can start working on the seeding part.

Seeding

We are going to use typeorm-extension for seeding our database. Let's install it first.

npm install typeorm-extension --save

Now we need a seeder class for seeding the user entity. Seeder interface is exported from typeorm-extension, we just need to implement it. Let's create the class in src/db/seeds/user.seeder.ts file.

// src/db/seeds/user.seeder.ts
import { Seeder, SeederFactoryManager } from 'typeorm-extension';
import { DataSource } from 'typeorm';
import { User } from '../../resources/users/entities/user.entity';

export default class UserSeeder implements Seeder {
  public async run(
    dataSource: DataSource,
    factoryManager: SeederFactoryManager,
  ): Promise<void> {
    await dataSource.query('TRUNCATE "user" RESTART IDENTITY;');

    const repository = dataSource.getRepository(User);
    await repository.insert({
      firstName: 'Mazedul',
      lastName: 'Islam',
    });
  }
}

We have implemented the run method from the Seeder interface. When we execute the seed command using the typeorm-extension CLI, this run function will be executed. The run method has access to the DataSource and SeederFactoryManager instances, as they are passed as arguments.

At first, we truncate the user table and restart the identity sequence to make sure the first record will get ID 1. Then we get the user repository from the dataSource and insert our first user object into the table using the repository.

Now we need to tell the dataSource that we have this seeder class. To do that, let's update our src/db/data-source.ts file.

// src/db/data-source.ts
import { SeederOptions } from 'typeorm-extension';
...
export const dataSourceOptions: DataSourceOptions & SeederOptions = {
  ...
  seeds: ['dist/db/seeds/**/*.js'],
};

We have added seeds array into our dataSourceOptions object. Notice, we are using the glob pattern for pointing to the seeds directory inside the dist/db/ directory. The glob pattern will not work if you point to the typescript files inside src/db/seeds/ directory. Since our build command will generate the dist directory anyway, there is no harm using the .js files from there.

Now, add a script for seeding in the package.json.

// package.json
{
  ...
  "scripts": {
    ...
    "seed": "npm run build && ts-node ./node_modules/typeorm-extension/dist/cli/index.js seed -d ./src/db/data-source.ts"
  }
}

In this command, we build the project first, then run the seed command from typeorm-extension with the help of ts-node.

Note: using the -d ./src/db/data-source.ts we are passing the path to the datasource file to the seed command.

Let's invoke the script.

npm run seed

Once we execute the command the user table in the database should be populated with one user.

Factories to generate bulk data

To generate random data for an entity, create a factory for the desired entity.

The factory callback provides an instance of the faker library as a function argument, to populate the entity with random data.

Create a factory function in src/db/factories/user.factory.ts file.

// src/db/factories/user.factory.ts
import { setSeederFactory } from 'typeorm-extension';
import { User } from '../../resources/users/entities/user.entity';

export default setSeederFactory(User, (faker) => {
  const user = new User();

  const sexFlag = faker.number.int(1);
  const sex: 'male' | 'female' = sexFlag ? 'male' : 'female';

  user.firstName = faker.person.firstName(sex);
  user.lastName = faker.person.lastName(sex);

  return user;
});

Now update the user.seeder.ts file and utilize this factory function for generating random users.

// src/db/seeds/user.seeder.ts
...
export default class UserSeeder implements Seeder {
  public async run(
    dataSource: DataSource,
    factoryManager: SeederFactoryManager,
  ): Promise<void> {
    ...
    const userFactory = factoryManager.get(User);
    // save 1 factory generated entity, to the database
    await userFactory.save();

    // save 5 factory generated entities, to the database
    await userFactory.saveMany(5);
  }
}

Since we are using SeederFactoryManager instance to get the user factory, we need to update our dataSourceOptions and make it aware of the factory files.

// src/db/data-source.ts
...
export const dataSourceOptions: DataSourceOptions & SeederOptions = {
  ...
  factories: ['dist/db/factories/**/*.js'],
};

Our factory setup is done. Run the seed command again.

npm run seed

Check the user table, it should have 1 hardcoded user and 6 more random users.

Seed programmatically

It is also possible to seed the database from the codebase, without using the CLI commands. To do that, we need to get access to the DataSource instance. There is a function called runSeeders exported from typeorm-extension which can be used to seed data programmatically. This is especially useful in e2e tests. You can seed your in-memory test database on-the-fly before each test. Probably I'll cover this in another article for testing a NestJS application.

Conclusion

We have successfully configured SQL database seeding functionality using TypeORM and typeorm-extension package. We also get some insights on how to seed programmatically using runSeeders function provided by typeorm-extension.

You can find the full project here: https://github.com/mazid1/nestjs-typeorm/tree/feature/seed

In the next article, I'll write about how to test a NestJS application.

I'm open for a remote full-time/contract/freelance job for the position of Full-stack Software Engineer. If you are hiring, ping me at mazidmailbox@gmail.com

TypeORM is the most mature Object Relational Mapper (ORM) for TypeScript and JavaScript. Since it's written in TypeScript, it integrates well with the NestJS framework. For integrating with SQL and NoSQL databases, Nest provides the @nestjs/typeorm package. Here the official documentation of NestJS has clear instructions on how to integrate TypeORM with it. However, they skipped the details on how to setup the migrations and forwarded them to the TypeORM documentation for migration, which is very generic and not aligned with NestJS. That is the motivation of this article. In this article, I'll show how to setup migrations in a NestJS project using TypeORM. Buckle up and let's get started.

Initial project setup

Let's initialize our project using Nest CLI.

nest new nest-typeorm

Navigate to the project folder and install the necessary dependencies. In this example, I am using PostgreSQL, therefore I have added pg as a dependency.

cd nest-typeorm
npm install --save @nestjs/typeorm typeorm pg

Database connection

Let's create a separate Nest module for handling database-related tasks.

nest g module db

Create the data-source.ts file inside the src/db directory. This file will contain database connection configurations.

// src/db/data-source.ts
import { config } from 'dotenv';
import { DataSourceOptions } from 'typeorm';

config();

export const dataSourceOptions: DataSourceOptions = {
  type: 'postgres',
  host: process.env.DB_HOST,
  port: +process.env.DB_PORT,
  username: process.env.DB_USER,
  password: process.env.DB_PASSWORD,
  database: process.env.DB_NAME,
  entities: [],
};

Use this dataSourceOptions for setting up TypeOrmModule inside the DbModule that we generated using Nest CLI.

// src/db/db.module.ts
import { Module } from '@nestjs/common';
import { TypeOrmModule } from '@nestjs/typeorm';
import { dataSourceOptions } from './data-source';

@Module({
  imports: [TypeOrmModule.forRoot(dataSourceOptions)],
})
export class DbModule {}

Now if you run the project using npm run start:dev command, it should be able to connect to the database. However, you have to make sure the database server is up and running and the database with the name that we specified in the data-source file is already created.

Generate an entity

Generate users resource using the CLI.

nest g resource resource/users

It will generate the users module, controller, service, DTOs and entity file inside src/resource/users directory.

Let's update the user.entity.ts file and add some columns there.

// src/resources/users/entities/user.entity.ts
import { Column, Entity, PrimaryGeneratedColumn } from 'typeorm';

@Entity()
export class User {
  @PrimaryGeneratedColumn()
  id: number;

  @Column({ name: 'first_name' })
  firstName: string;

  @Column({ name: 'last_name' })
  lastName: string;
}

Now we need to create the migration for creating the user table with the id, first_name, last_name columns.

Generate the migration

Migration in TypeORM is just a class that implements MigrationInterface from the typeorm package. It needs to implement the up and down methods. The up method executes the query for applying new changes in the database. On the other hand, down method executes the query to revert the changes that was applied by the up method.

It is possible to implement a migration by manually implementing the MigrationInterface. However, TypeORM provides a nice CLI to generate that automatically based on the data-source and entity.

Now the first thing is, we need to make TypeORM aware that we have an entity called user. To do that, we need to update the entities array in the data-source file. The entities array accepts both entity classes and directories from where entities need to be loaded. Directories support glob pattern. In our case, we want every entity from our resources directory to be loaded.

// src/db/data-source.ts
...
export const dataSourceOptions: DataSourceOptions = {
  ...
  entities: ['src/resources/**/*.entity.ts'],
};

Though we are working with typescript, the above code will throw Cannot use import statement outside a module error. To make it work smoothly it is safe to use .js files. Our build command will generate the javascript files during build time and put them into /dist directory. We can simply use that path here.

// src/db/data-source.ts
...
export const dataSourceOptions: DataSourceOptions = {
  ...
  entities: ['dist/resources/**/*.entity.js'],
};

At this point, our project is ready for generating the first migration. We will use TypeORM CLI to generate the migration file. The command for generating a migration file from a data-source is like this.

npx typeorm migration:generate -d path/to/datasource path/to/Migration

However, we are using entity path from dist directory. That means, we need to run the build command before using the typeorm command. We can combined those commands like this.

npm run build && npx typeorm migration:generate -d path/to/datasource path/to/Migration

Let's add a script in our package.json file combining these commands.

// package.json
{
  ...
  "scripts": {
    ...
    "migration:generate": "npm run build && npx typeorm migration:generate -d ./dist/db/data-source.js",
  }
}

Notice that, we have added the path to data-soure file in the script but we omitted the path to migration file. We want to pass that dynamically from the command line when we invoke the script.

Let's invoke the script.

npm run migration:generate src/db/migrations/create-user-table

Once we execute this command in the terminal it will generate the migration file in the src/db/migrations directory. The file name will be something like <timestamp>-create-user-table.ts

If you open the migration file you can see the code like below.

// src/db/migrations/<timestamp>-create-user-table.ts
import { MigrationInterface, QueryRunner } from "typeorm";

export class CreateUserTable1690462207991 implements MigrationInterface {
    name = 'CreateUserTable1690462207991'

    public async up(queryRunner: QueryRunner): Promise<void> {
        await queryRunner.query(`CREATE TABLE "user" ("id" SERIAL NOT NULL, "first_name" character varying NOT NULL, "last_name" character varying NOT NULL, CONSTRAINT "PK_cace4a159ff9f2512dd42373760" PRIMARY KEY ("id"))`);
    }

    public async down(queryRunner: QueryRunner): Promise<void> {
        await queryRunner.query(`DROP TABLE "user"`);
    }

}

Run the migration

The migration file is generated. Now we need to execute it to update our database structure.

Before using the migration:run command from TypeORM CLI we need to update the dataSourceOptions and add migrations array to tell TypeORM from where it should read the migration files.

// src/db/data-source.ts
...
export const dataSourceOptions: DataSourceOptions & SeederOptions = {
  ...
  migrations: ['dist/db/migrations/*.js'],
};

We have used the glob pattern to pick migration files from the dist directory (similar to entities array that we added before). Therefore, we must build the project before running the migration command. Same as before, we can combine the build and migration commands in the package.json file.

Let's add the script to run the migration in our package.json file.

// package.json
{
  ...
  "scripts": {
    ...
    "migration:run": "npm run build && npx typeorm migration:run -d ./dist/db/data-source.js",
  }
}

Run the script through the terminal.

npm run migration:run

If you check your database now, you can see the user table is created.

Conclusion

We have learned how to set up migration in a NestJS project using TypeORM.

You can find the full project here:
https://github.com/mazid1/nestjs-typeorm/tree/feature/migration

In the next article, I will write about how to seed test data using TypeORM.

I'm open for a remote full-time/contract/freelance job for the position of Full-stack Software Engineer. If you are hiring, ping me at mazidmailbox@gmail.com

Last month we initialized a new project with Angular and Angular Material. As time goes on, I have noticed that some of my colleagues are often writing inline styles for margin and padding.

<div style="margin-top: 5px; margin-bottom: 5px">
  With inline style
</div>

Some of them (including me) are creating similar CSS classes for almost every component wherever needed.

.set-padding {
  padding: 10px 0;
}
.left-spacer {
  margin-left: 10px;
}

Then I realized that we are missing bootstrap-like margin and padding classes. One of my colleagues suggested using Tailwind CSS. However, as we are already using Angular Material for our component library, installing a CSS framework only for some spacing classes will be overkill for sure. So, I decided to write these classes on my own.

Bootstrap Classes: A Closer Look

According to the documentation of Bootstrap 4 its spacing classes have the following format:

The classes are named using the format {property}{sides}-{size} for xs and {property}{sides}-{breakpoint}-{size} for sm, md, lg, and xl.

Where property is one of the:

• m - for classes that set margin

• p - for classes that set padding

Where sides is one of the:

• t - for classes that set margin-top or padding-top

• b - for classes that set margin-bottom or padding-bottom

• l - for classes that set margin-left or padding-left

• r - for classes that set margin-right or padding-right

• x - for classes that set both *-left and *-right

• y - for classes that set both *-top and *-bottom

• blank - for classes that set a margin or padding on all 4 sides of the element

Where size is one of the:

• 0 - for classes that eliminate the margin or padding by setting it to 0

• 1 - (by default) for classes that set the margin or padding to $spacer * .25

• 2 - (by default) for classes that set the margin or padding to $spacer * .5

• 3 - (by default) for classes that set the margin or padding to $spacer

• 4 - (by default) for classes that set the margin or padding to $spacer * 1.5

• 5 - (by default) for classes that set the margin or padding to $spacer * 3

• auto - for classes that set the margin to auto

Define Our Requirements

Our focus is to generate all the CSS classes of the format {property}{sides}-{size}.

For example:

1. m-0 to m-5 and m-auto

2. p-0 to p-5

3. mt-0, mb-0, ml-0, mr-0 to mt-5, mb-5, ml-5, mr-5 and mt-auto, mb-auto, ml-auto, mr-auto

4. pt-0, pb-0, pl-0, pr-0 to pt-5, pb-5, pl-5, pr-5

5. mx-0 to mx-5 and my-0 to my-5 and mx-auto, my-auto

6. px-0 to px-5 and py-0 to my-5

Notice, we are omitting {property}{sides}-{breakpoint}-{size} pattern, which is not in the scope of this article.

SASS Implementation

I am going to use SCSS syntax, you can also use the original SASS if you find that easier to use.

Let's create a new file _spaces.scss. The filename starts with _ because I want to make it a partial sass file. You can check the Sass guide if you do not know what a partial Sass file means.

Create a variable $spacer with the default value for space.

// _spaces.scss
$spacer: 1rem !default;

Then create a sass:map with keys from 0 to 5 and auto and set the calculated value for each key.

$spacers: (
  0: 0,
  1: $spacer * 0.25,
  2: $spacer * 0.5,
  3: $spacer,
  4: $spacer * 1.5,
  5: $spacer * 3,
  auto: auto,
) !default;

Now, let's loop through the map and generate classes from m-0 to m-5 and m-auto.

@each $key, $value in $spacers {
  // generate m-* classes
  .m-#{$key} {
    margin: #{$value} !important;
  }
}

We can also generate padding classes inside this loop. Let's generate classes from p-0 to p-5.

@each $key, $value in $spacers {
  // generate m-* classes
  .m-#{$key} {
    margin: #{$value} !important;
  }

  // generate p-* classes
  .p-#{$key} {
    padding: #{$value} !important;
  }
}

However, this code will also generate .p-auto { padding: auto !important; } which is incorrect. So, we need to exclude the auto key when generating .p-* classes.

@each $key, $value in $spacers {
  // generate m-* classes
  .m-#{$key} {
    margin: #{$value} !important;
  }

  // generate p-* classes excluding key = auto
  @if $key != auto {
    .p-#{$key} {
      padding: #{$value} !important;
    }
  }
}

Till now, we have covered the following cases:

1. m-0 to m-5 and m-auto

2. p-0 to p-5

Let's focus on the next two cases:

1. mt-0, mb-0, ml-0, mr-0 to mt-5, mb-5, ml-5, mr-5 and mt-auto, mb-auto, ml-auto, mr-auto

2. pt-0, pb-0, pl-0, pr-0 to pt-5, pb-5, pl-5, pr-5

Now we need to generate classes that can target specific sides. Therefore create a sass:list containing all the sides.

$sides: (top, bottom, left, right);

For each key presents in the $spacers map we need to generate classes combining each direction/side. Therefore, we need a nested loop like this.

@each $key, $value in $spacers {
  @each $side in $sides {
    // generate m* classes
    .m#{str-slice($side, 0, 1)}-#{$key} {
      margin-#{$side}: #{$value} !important;
    }
  }
}

Same as before, we can generate padding classes (excluding auto key) inside this loop.

@each $key, $value in $spacers {
  @each $side in $sides {
    // generate m* classes
    .m#{str-slice($side, 0, 1)}-#{$key} {
      margin-#{$side}: #{$value} !important;
    }

    // generate p* classes excluding key = auto
    @if $key != auto {
      .p#{str-slice($side, 0, 1)}-#{$key} {
        padding-#{$side}: #{$value} !important;
      }
    }
  }
}

Now we are only left with the following two cases to generate:

1. mx-0 to mx-5 and my-0 to my-5 and mx-auto, my-auto

2. px-0 to px-5 and py-0 to my-5

To generate classes for x and y axes let's create a new sass:list.

$axises: (x, y);

Same as before, for each key value present in $spacers combining each axis present in $axis list we need to generate classes. So, we need to use nested loops again.

@each $key, $value in $spacers {
  @each $axis in $axises {
    @if $axis == x {
      // generate classes for x axis

      // generate mx-* classes
      .m#{$axis}-#{$key} {
        margin-left: #{$value} !important;
        margin-right: #{$value} !important;
      }

      // generate px-* classes excluding key = auto
      @if $key != auto {
        .p#{$axis}-#{$key} {
          padding-left: #{$value} !important;
          padding-right: #{$value} !important;
        }
      }
    } @else if $axis == y {
      // generate classes for y axis

      // generate my-* classes
      .m#{$axis}-#{$key} {
        margin-top: #{$value} !important;
        margin-bottom: #{$value} !important;
      }

      // generate py-* classes excluding key = auto
      @if $key != auto {
        .p#{$axis}-#{$key} {
          padding-top: #{$value} !important;
          padding-bottom: #{$value} !important;
        }
      }
    } @else {
      @error "Unknown axis #{$axis}.";
    }
  }
}

Usage

If your project setup supports a Scss file, then you can import this file into your root style file using @use rule.

// styles.scss file, in the same directory of _spaces.scss
@use "./spaces";

If you need compiled css, then you can install SASS on your machine and use the following command to generate spaces.css file.

sass _spaces.scss spaces.css

After adding this, now we can use bootstrap-like CSS classes in our HTML code.

<div class="my-2 px-2">
  Styled with bootstrap like classes!
</div>

Conclusion

The complete source code is available here.

Thank you for reading. Your appreciation is my motivation!

Follow me on social media:

• Linkedin: mazedul-islam

• Twitter: @mazedul__islam

• Github: mazid1

• Website: mazedulislam.com

I'm open for a remote full-time/contract/freelance job for the position of Full-stack Software Engineer. If you are hiring, ping me at mazidmailbox@gmail.com