Forem: Barigbue Nbira

TypeScript CI/CD Pipeline using Docker, GitHub Actions, Kubernetes, ArgoCD, Trivy and ESLint

Barigbue Nbira — Mon, 14 Apr 2025 11:50:55 +0000

Security is a continuous part of the development lifecycle rather than an afterthought. It goes beyond just securing CI/CD pipelines and extends to all aspects of development, from infrastructure to application deployment.

Why is Security Important?

AI-Assisted Development: Developers are increasingly using AI assistants to write code, which can lead to issues like hardcoded secrets, outdated packages, etc.
Increasing Cyber Threats: Cyber attacks and CVEs are on the rise, making it more important than ever to integrate security from the start.

Before building a CI/CD pipeline, take the time to understand the application:

Fork the repo, run the application, and review the codebase. Basically, try to have an idea of what is going on. Assuming you did not build the application yourself.

For this project, we will be building a CI/CD pipeline for a React frontend application that uses TypeScript and Vite.

Containerization

To containerize the application, start by creating a Dockerfile in the root of your project with the following contents:

# Step 1: Use an official Node.js image as the base 
FROM node:20-alpine AS build

# Step 2: Set the working directory inside the container
WORKDIR /app

# Step 3: Copy package.json and package-lock.json to the container
COPY package*.json ./

# Step 4: Install project dependencies
RUN npm install

# Step 5: Copy the rest of your application code to the container
COPY . .

# Step 6: Build the application using Vite
RUN npm run build

# Step 7: Use a lightweight web server like 'nginx' to serve the built files
FROM nginx:alpine

# Step 8: Copy the built files from the build stage into the nginx container image
COPY --from=build /app/dist /usr/share/nginx/html

# Step 9: Expose port 80 to the outside world
EXPOSE 80

# Step 10: Start nginx server
CMD ["nginx", "-g", "daemon off;"]

Why Copy Dependencies First?
Docker images are built in layers, where each command in the Dockerfile creates a new layer. These layers are cached, meaning that if a layer hasn't changed, Docker will reuse the cached version of that layer rather than rebuilding it. This significantly speeds up the build process because Docker doesn't need to repeat operations that haven't changed since the last build.

It's essential to exclude files and directories that aren't needed in the Docker image, such as node_modules, which are typically reinstalled during the build process, and log files like npm-debug.log or any .log files that are generated during development. Sensitive information, such as environment files (.env), should also be ignored to prevent accidental exposure. You can ignore these files by including them in a .dockerignore file in the root of your project.

node_modules
npm-debug.log
.git
.github
.gitignore
README.md
.vscode
*.md
*.log
.env
.env.local
.env.development.local
.env.test.local
.env.production.local
kubernetes

Build the Docker image: docker build -t your-app-name:v1 .
Run the container locally to confirm: docker run -d -p 8080:80 your-app-name:v1

CI/CD Pipeline overview


Developer pushes code/raises a PR → GitHub Actions triggers → Workflow starts

Workflow Jobs:

Run Unit Tests : Executes the test suite using Vitest to verify code correctness.
Lint Codebase: Performs static analysis with ESLint to catch syntax issues and enforce code standards.
Build Application: Generates a production-ready version of the app.
Create Docker Image: Packages the application into a Docker image using a multi-stage Dockerfile.
Scan Docker Image: Checks the built image for security vulnerabilities using Trivy.
Push to Container Registry: Uploads the image to GitHub Container Registry.
Update Kubernetes Deployment: Applies the new image tag to the Kubernetes deployment configuration
Kubernetes Manifest Update:
- Use a shell script to update the image tag in k8s/deployment.yml
- Commit and push the change back to the repository
ArgoCD:
- Watches the repo for changes in the manifest
- Automatically deploys to Kubernetes when image tag is updated

Each job only runs if the previous one is successful to ensure stability and security throughout the pipeline.

Considerations

Since the pipeline updates the container image tag in the Kubernetes manifest (deployment.yml) after the Docker job is successful, we need to prevent this update from re-triggering the same pipeline. We avoid the infinite loop by ignoring changes in specific paths like so:

paths-ignore:
  - 'kubernetes/deployment.yaml'

When executing the jobs, we want to avoid downloading dependencies repeatedly
on each run. By caching the npm packages, the job skips the download process
each time the CI pipeline runs

steps:
  - name: Setup Node.js
    uses: actions/setup-node@v4
    with:
      node-version: '20'
      cache: 'npm'

In some cases, developers may want to download from Nexus and run the build artifact locally without having to deal with Docker. By separating the build job into two: a regular build, and a Docker build. The goal is to give developers the flexibility to choose the approach that best suits their needs.

Writing the GitHub Actions CI Pipeline

In professional environments, protecting the main branch is a standard practice. Most organizations implement branch protection rules that require pull requests with code reviews before merging. It would usually trigger when a pull request is opened, edited, reopened, etc.

on:
  pull_request_target:
    types: ['opened', 'synchronize', 'reopened', 'edited']
    branches: [main]

Since this is a personal project, we’ll keep things simple. In the root directory of your project, create a .github folder. Inside it, add a subfolder named workflows. Within the workflows folder, create a YAML file: let’s call it react-typescript-prod-release.yml

Let’s begin writing our CI pipeline.

We want our pipeline to get triggered on pull request and push to the main branch of our repository.

name: react-typescript-prod-release

on:
  push:
    branches: [ main ]
    paths-ignore:
      - 'kubernetes/deployment.yaml'  
  pull_request:
    branches: [ main ]

jobs:

In a GitHub Actions workflow, all individual jobs are defined under the top-level jobs key. Each job is a separate task or phase in our pipeline.

The first job in the workflow is responsible for unit testing the application. It begins by checking out the source code using an action. Then, it sets up a Node.js environment and cache dependency to speed up the workflow by reusing previously downloaded dependencies. Once the environment is ready, it installs the project dependencies using npm ci, which ensures a clean install. Finally, it runs the test suite with npm test to validate the code.

test:
    name: Unit Testing
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'

      - name: Install dependencies
        run: npm ci

      - name: Run tests
        run: npm test

The next job performs static code analysis using ESLint. This step ensures that the code follows defined style guidelines and best practices. It shares a similar setup with the unit testing job: it checks out the repository, sets up Node.js with caching to improve performance, and installs the project dependencies. The main difference is in the final step, where it runs the linting command npm run lint to analyse the code for any syntax or formatting issues.

lint:
    name: Static Code Analysis
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'

      - name: Install dependencies
        run: npm ci

      - name: Run ESLint
        run: npm run lint

In the Build job, the linting and testing jobs are set as dependencies (needs: [test, lint]). This ensures that the application will only be built if it passes both the tests and linting checks. The build process creates a dist folder, which contains the production-ready version of the application. It's a best practice to store these build artifacts in a reliable storage solution such as Nexus or GitHub storage. For this project, we’ll upload the artefact to GitHub’s storage.

build:
    name: Build
    runs-on: ubuntu-latest
    needs: [test, lint]
    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'

      - name: Install dependencies
        run: npm ci

      - name: Build project
        run: npm run build

      - name: Upload build artifacts
        uses: actions/upload-artifact@v4
        with:
          name: build-artifacts
          path: dist/

The next step involves building, scanning, and pushing the Docker image to GitHub Container Registry. Before writing the YAML code, here are the required setup steps:

Generate a GitHub Personal Access Token by navigating to Settings → Developer settings → Personal access tokens (classic). Create a new token with write:packages and read:packages permissions only, and copy it.
Go to your project repository → Settings → Secrets and variables → Actions → Repository secrets, and create a secret named TOKEN, where you’ll paste the token you just generated.

It begins by checking out the code and retrieving the build artifacts created in the previous build job. It then sets up Docker Buildx and logs into GitHub Container Registry using the secret token we created.

It then extracts metadata to generate consistent image tags using the commit SHA, branch name, and a latest tag.

Containerization is performed in two steps. First, the Docker image is built using the project’s Dockerfile. Then, the image undergoes a security scan using Trivy, which checks for vulnerabilities in the base image and application dependencies. The scan is configured to fail the pipeline if any high or critical vulnerabilities are detected, ensuring only secure images are allowed to proceed.

Once the image passes the security scan, it’s pushed to GitHub Container Registry along with its tags and metadata. Additionally, a shortened version of the commit SHA is extracted and stored as a job output to serve as a simplified image tag, useful in later deployment steps.

docker:
    name: Docker Build and Push
    runs-on: ubuntu-latest
    needs: [build]
    env:
      REGISTRY: ghcr.io
      IMAGE_NAME: ${{ github.repository }}
    outputs:
      image_tag: ${{ steps.set_output.outputs.image_tag }}
    steps:
      - name: Checkout code
        uses: actions/checkout@v4
      # Retrieve the build artifacts created in the build job  
      - name: Download build artifacts
        uses: actions/download-artifact@v4
        with:
          name: build-artifacts
          path: dist/

      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v3
        # Authenticate with GitHub Container Registry
      - name: Login to GitHub Container Registry
        uses: docker/login-action@v3
        with:
          registry: ${{ env.REGISTRY }}
          username: ${{ github.actor }}
          password: ${{ secrets.TOKEN }}
       # Generate appropriate tags and metadata for the Docker image
      - name: Extract metadata 
        id: meta
        uses: docker/metadata-action@v5
        with:
          images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
          tags: |
            type=sha,format=long
            type=ref,event=branch
            latest
      # Build the Docker image locally without pushing to registry
      - name: Build Docker image
        uses: docker/build-push-action@v5
        with:
          context: .
          push: false
          tags: ${{ steps.meta.outputs.tags }}
          labels: ${{ steps.meta.outputs.labels }}
          load: true
      # Scan the built image for security vulnerabilities
      - name: Trivy vulnerability scanner
        uses: aquasecurity/trivy-action@master
        with:
          image-ref: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:sha-${{ github.sha }}
          format: 'table'
          exit-code: '1'
          ignore-unfixed: true
          vuln-type: 'os,library'
          severity: 'CRITICAL,HIGH'
       # Push the scanned and approved image to the registry
      - name: Push Docker image
        uses: docker/build-push-action@v5
        with:
          context: .
          push: true
          tags: ${{ steps.meta.outputs.tags }}
          labels: ${{ steps.meta.outputs.labels }}
      # Create a shortened version of the commit SHA for easier reference
      - name: Set image tag output
        id: set_output
        run: echo "image_tag=$(echo ${{ github.sha }} | cut -c1-7)" >> $GITHUB_OUTPUT

Once we have a new image, using a shell script defined in the update-k8s job, the deployment.yml file will be automatically updated to use the new image.

update-k8s:
    name: Update Kubernetes Deployment
    runs-on: ubuntu-latest
    needs: [docker]
    if: github.ref == 'refs/heads/main' && github.event_name == 'push'
    steps:
      - name: Checkout code
        uses: actions/checkout@v4
        with:
          token: ${{ secrets.TOKEN }}

      - name: Setup Git config
        run: |
          git config user.name "GitHub Actions"
          git config user.email "actions@github.com"

      - name: Update Kubernetes deployment file
        env:
          IMAGE_TAG: sha-${{ github.sha }}
          GITHUB_REPOSITORY: ${{ github.repository }}
          REGISTRY: ghcr.io
        run: |
          NEW_IMAGE="${REGISTRY}/${GITHUB_REPOSITORY}:${IMAGE_TAG}"

          # Update the deployment file directly
          sed -i "s|image: ${REGISTRY}/.*|image: ${NEW_IMAGE}|g" kubernetes/deployment.yaml

          # Verify the change
          echo "Updated deployment to use image: ${NEW_IMAGE}"
          grep -A 1 "image:" kubernetes/deployment.yaml

      - name: Commit and push changes
        run: |
          git add kubernetes/deployment.yaml
          git commit -m "Update Kubernetes deployment with new image tag: ${{ needs.docker.outputs.image_tag }} [skip ci]" || echo "No changes to commit"
          git push

To test if our CI pipeline is working as expected, make changes to the codebase and push it. This should trigger the workflow.

Setting Up Kubernetes with Kind on an EC2 Instance for Continuous Delivery

The focus is on the CI, so, instead of provisioning a full AWS EKS cluster, we’ll create a lightweight Kubernetes environment using Kind (Kubernetes IN Docker) on an EC2 instance.

Steps

Create an Ubuntu EC2 instance

Use Ubuntu AMI
Allocate at least 4GB of RAM for Kind to run smoothly.

SSH into the instance

ssh -i /path/key-pair-name.pem instance-user-name@instance-IPAddress

Switch to Root User and Update the APT Repository

sudo -i
apt update

Install Docker

apt install docker.io -y

Add the Ubuntu User to the Docker Group

usermod -aG docker ubuntu

Install kind

# For AMD64 / x86_64
[ $(uname -m) = x86_64 ] && curl -Lo ./kind https://kind.sigs.k8s.io/dl/v0.27.0/kind-linux-amd64
# For ARM64
[ $(uname -m) = aarch64 ] && curl -Lo ./kind https://kind.sigs.k8s.io/dl/v0.27.0/kind-linux-arm64
chmod +x ./kind
mv ./kind /usr/local/bin/kind

Create a Kubernetes Cluster

kind create cluster --name < name of your cluster >

Install Kubectl

curl -LO "https://dl.k8s.io/release/$(curl -L -s https://dl.k8s.io/release/stable.txt)/bin/linux/amd64/kubectl"

install -o root -g root -m 0755 kubectl /usr/local/bin/kubectl

Verify Your Kubernetes Context

kubectl config current-context

This confirms which cluster kubectl is connected to. You should see the name of the cluster you created earlier.

An extra step of verification is running:

kubectl get nodes

Create the ArgoCD Namespace and Install the Components

kubectl create namespace argocd
kubectl apply -n argocd -f https://raw.githubusercontent.com/argoproj/argo-cd/stable/manifests/install.yaml

This sets up all the necessary ArgoCD resources inside the argocd namespace.

Verify the ArgoCD pods

kubectl get pods -n argocd -w

The -w flag keeps the output live, so you can watch each pod's status in real time.

Wait until all pods are in the Running state before moving on. This ensures that ArgoCD has been successfully installed and is ready to use.

Access ArgoCD from the UI
To access the ArgoCD dashboard in your browser, we’ll use kubectl port-forwarding at the service level. This approach exposes the ArgoCD server.

List available services in the argocd namespace:
```
kubectl get svc -n argocd
```
This will list available services in the argocd namespace. Look for the service named argocd-server in the list.
Forward traffic from your EC2 instance to your local machine:
```
kubectl port-forward svc/argocd-server 9000:80 -n argocd --address 0.0.0.0
```
This exposes the ArgoCD UI on port 9000.

Make sure your EC2 security group allows inbound traffic on port 9000 only from your IP address.
In your browser, go to:
```
http://< EC2_PUBLIC_IP >:9000
```
You should see the ArgoCD login page.

ArgoCD stores the initial admin password in a Kubernetes secret. To access it:

# lsit available secrets
kubectl get secrets -n argocd

#Edit the argocd-initial-admin-secret 
kubectl edit secret argocd-initial-admin-secret -n argocd

Find the password field in the YAML that opens, it's base64-encoded.

Copy the value of the password field and decode it:
```
echo <paste-encoded-password-here> | base64 --decode
```
This will output the plain text admin password. If it ends with the EC2 instance name or extra metadata, only copy the actual password.
Use admin as the username and the decoded password to log into the ArgoCD UI.

Deploy Application to Kubernetes Cluster

To deploy your application using ArgoCD, follow these steps:

On the ArgoCD UI, click on “Create Application.”
Fill out the form with the following details:
- Application Name: Choose any name you prefer.
- Project: Select default.
- Sync Policy: Set this to “Automatic” so ArgoCD can detect changes and sync them automatically.
Repository URL:
Navigate to your project’s GitHub repository, click the green “Code” button, and copy the HTTPS URL.
Path:
Specify the folder where your Kubernetes manifests are located.

For example, if your manifests are in a folder named Kubernetes at the root of your repository, enter:
```
Kubernetes
```
Cluster URL:

Leave this as the default: it points to the local Kubernetes cluster created by kind.
Namespace:

You can use the default namespace unless your app is configured for a different one.
Once everything is filled out, click “Create” to deploy the application.

Fixing Private Container Registry Access in ArgoCD

Your deployment would fail with an error related to pulling the image. ArgoCD is trying to pull the image from the GitHub Container Registry (GHCR), which is private by default. This means only authenticated users with the proper credentials can access it.

To resolve this, you need to configure image pull secrets.

Update your deployment.yaml to include the following field under “spec”:

imagePullSecrets:
  - name: github-container-registry

Create secret for pulling images from GitHub Container Registry on your EC2 instance

kubectl create secret docker-registry github-container-registry \
  --docker-server=ghcr.io \
  --docker-username=YOUR_GITHUB_USERNAME \
  --docker-password=YOUR_GITHUB_TOKEN \
  --docker-email=YOUR_EMAIL

Make sure to replace YOUR_GITHUB_USERNAME, YOUR_GITHUB_TOKEN, and YOUR_EMAIL with your credentials.

Once you've created the secret, go back to ArgoCD and delete the old failed pods. ArgoCD will automatically attempt to redeploy the application, and this time, it should successfully pull the image using the newly configured credentials.

Make a change to your codebase, commit, and push. This should trigger the CI and CD.

Accessing Application

To access your application running on the Kubernetes cluster:

List the available pods to get the name of the pod running your application:
```
kubectl get pods
```
Port forward traffic from your local machine to the pod using the pod name from the previous command. Replace <your-pod-name> with the actual name:
```
kubectl port-forward <your-pod-name> 5173:80 --address=0.0.0.0
```

You can access the app from your browser by http://<YOUR-EC2-PUBLIC-IP>:5173

Don’t forget to update your EC2 security group rules to allow inbound traffic on port 5173 from your IP address.

Conclusion

And that’s a wrap! You’ve just learned how to integrate security into your CI/CD workflow. As you follow along, if you encounter a few bumps, don’t worry, that’s part of the process. If you run into any errors, feel free to drop them in the comments, and we’ll tackle them together.

Thanks for reading, and until next time—happy coding!

From Localhost to Production: Problem-First SRE Journey with One2N Bootcamp

Barigbue Nbira — Sun, 27 Oct 2024 12:12:17 +0000

I came across a problem-first SRE bootcamp (where you get to build an application, and scale it from localhost to production) by One2N on X (formerly Twitter) and thought, “Heck yeah! I’ll give this a try.” This blog post kicks off a journey where I’ll document my experience tackling each exercise in the bootcamp.

This introductory post will link to other entries detailing my solutions to the different exercises and stages. I chose this bootcamp for its problem-first approach. It provides just enough guidance to set you in the right direction, but everything else? That’s up to you to research, experiment, and figure out on your own. This is NOT a cohort-based bootcamp, rather, it is a self-paced one.

The Learning Journey

This bootcamp is divided into two main parts/responsibilities:

Getting your application/service from local to production.
Managing the application/service in production.

Each part includes milestones with clear goals, learning outcomes, problem statements, expectations, and recommended resources. The second part is still a WIP, so it is unavailable for now.

Responsibilities

Create a simple REST API Webserver
Containerise REST API
Setup one-click local development setup
Setup a CI pipeline
Deploy REST API & its dependent services on bare metal
Setup Kubernetes cluster
Deploy REST API & its dependent services in K8s
Deploy REST API & its dependent services using Helm Charts
Setup one-click deployments using Argo CD
Setup an observability stack
Configure dashboards & alerts

Linking Plan for Future Articles

I’ll update this article with links to each stage or milestone article as I make progress, along with the relevant GitHub links. I’ll also share the challenges I encounter and how I overcome them along the way.

Improving the Speed of Software Delivery from Development to End Users

Barigbue Nbira — Mon, 22 Jul 2024 12:33:25 +0000

Delivering value through a technology-enabled service to the end user, fast, isn't just a competitive advantage—it is a necessity.

To deliver value fast, workflow needs to be hitch-free—work must move swiftly and efficiently through each stage of the development and post-development pipeline. Minimizing interruptions, reducing waste, and optimizing processes can lead to faster, more reliable software delivery.

In software development, bottlenecks and inefficiencies can hinder progress, leading to longer lead time and increased frustration for the stakeholders, teams, and users.

In this article, we will explore strategies for improving workflow and reducing lead time.

Minimize Work-in-Progress

“When you have competing sources of attention, your task performance is often going to be reduced” (Madore et al., 2020).

Work-in-Progress (WIP) refers to tasks that have been started but are not yet finished. In technology-focused workflows, managing WIP is important due to the cognitive demands of work. Switching between multiple tasks requires re-establishing context and goals, which can significantly reduce productivity. Reducing the number of concurrent tasks improves efficiency while allowing teams to lighten their workload, and have a clear focus on current tasks.

Teams can actively reduce WIP by making work visible and enforcing an upper limit on tasks. For example, a team struggling with context switching and feature bloat can utilize WIP limits, the team can set a WIP limit of 3 tasks in the "In Development" column of the Kanban board. This ensures only three features are actively being worked on at any given time.

The key lies in striking the right balance with WIP limits. Setting them too low can stall productivity, while excessively high limits can lead to scattered focus and hinder productivity. Teams should actively analyze their workflow and team capacity to determine the optimal WIP limits that unlock their peak performance.

Visualize the Workflow

(Source: Andrey P., 2023, Agile Business Team Using Kanban Task Board, Unsplash, https://www.istockphoto.com/photo/agile-business-team-gm1458140561-492776632)

In technology, work can often be invisible, so making tasks as visible as possible is necessary. This transparency helps teams pinpoint roadblocks and identify areas where work is accumulating.

Visibility's power lies in its immediate impact on team dynamics. When tasks are made visible on a shared board such as a Kanban, teams gain instant clarity: everyone readily sees what needs to be done and who's assigned to which task.

Naturally, our brain excels at processing visual information, Kanban capitalizes on this, by creating a visual representation of workflows. It maps different work stages to columns on a Kanban board (physical or electronic), and work items are tracked as they progress through them.

Work (represented by cards) progresses from the left of the kanban through the workstations (columns) to the last column on the right, usually marked as "done". Your definition of "done" should be when the service is safely running in production and delivering value to the customer, not just when development is complete.

Shrink Batch Sizes

In any process, a batch refers to a group of tasks or work items that move through different stages together. The size of a batch determines how many items are processed at once. Large batch sizes automatically mean more WIP.

Let's take a look at the negative effects of working with large batch sizes. For example, imagine a team that is developing enterprise software. They gather features and bug fixes throughout an entire sprint before releasing them all at once as a major update. This approach of handling a substantial batch size brings about several challenges:

Complexity and Risks: Integrating numerous changes simultaneously increases complexity and makes it harder to pinpoint problems when they occur.
Delayed Feedback: Feedback on individual features is delayed until the entire batch is released, postponing the identification of potential issues.
Increased WIP and Lead Time: Working with large batch sizes means more WIP and longer lead time.

Why work in small batches?

Faster Feedback: Smaller batches allow for quicker deployments, enabling earlier feedback on features and improvements.
Reduced Risk: With smaller batches, issues are easier to identify and isolate, reducing the overall risk of the project.
Fewer Conflicts: Smaller batches naturally lead to fewer conflicts between different parts of the work. If conflicts do arise, they are easier to pinpoint and resolve.
Other Benefits: Faster code reviews, reduced cycle time, quicker learning from failures, and more.

Continuous deployment is a strategy that perfectly complements small batch sizes. In this approach, each code commit is automatically tested, staged, and deployed to production. This allows for frequent deployments and near-instantaneous feedback.

Decrease the Number of Handoffs

A handoff refers to transferring ownership or responsibility for a task from one team to another.

Excessive handoffs can slow down the development process, as teams must wait for other teams to complete their tasks. When one team makes a request, the receiving team adds it to their backlog, until they are able to attend to it. This can delay progress.

To remedy this, create a cross-functional team of Developers, Designers, QA, InfoSec, Operations etc. This team shares responsibility for a feature from its design, development, and testing, all the way through to when it is safely running in production. This reduces the number of handoffs between different teams and fosters a sense of shared ownership.

Conclusion

By visualizing your workflow, limiting work-in-progress, reducing batch sizes, and minimizing handoffs, you can create a more efficient, productive, and harmonious development environment. These practices not only accelerate the speed of delivery but also improve the overall quality of your product and team performance.

References

Madore, K.P., Khazenzon, A.M., Backes, C.W. et al. Memory failure predicted by attention lapsing and media multitasking. Nature 587, 87–91 (2020). https://doi.org/10.1038/s41586-020-2870-z

Scroll-Driven Image Sequence Animation

Barigbue Nbira — Mon, 29 Apr 2024 16:14:42 +0000

I came across this interesting animation on the polaroid's i2 camera website recently.

This technique involves rendering a sequence of images on a canvas at different scroll positions. As you scroll up or down the page, different images are rendered on the canvas to create a sense of motion (it feels like playing a video on scroll). This animation can be seen on the Apple, Samsung, and lots of creative websites out there.

Here's the same animation for the Apple airpod.

This technique adds visual interest and interactivity to your website. It can tell a story, showcase product(s), or simply enhance the visual appeal of your website

Prerequisites

Basic understanding of React and JavaScript.
A sequence of images (use online tools to convert a short video into individual frames).
Optimized images in WebP format (convert the image sequence to WebP for faster loading).

Getting Started

JSX Markup and Styling

First, create the component that will serve as a container for our animation:


function ScrollSequence(){


    return(
    <section className="png__sequence">
    <canvas  width = {window.innerWidth} height={window.innerHeight} className = "png__sequence__canvas"  id="canvas"> </canvas> 
    </section>)
}

In this component, we have:

A element that serves as a wrapper for our animation.
A element where our images will be rendered. The width and height of the canvas are set to the current width and height of the browser window using window.innerWidth and window.innerHeight.

Styling with SCSS

N/B: Don't forget to do your resets.

.png__sequence{
  width: 100%;
  height: 500vh;
  position: relative;

  &__canvas{
  top: 0;
  bottom: 0;
  left: 0;
  right: 0;
  max-width: 100vw;
  max-height: 100vh;
  position: sticky;
  z-index: 1;
}
}

The png__sequence has a height of 500vh to ensure that our page has enough scroll length for the animation to work.

Creating the Canvas and Context

We want our animation to start as soon as the component mounts. To do this, we will use the useEffect hook to wrap our animation code, and get the canvas element and its 2D rendering context.

import "./scrollSequence.scss";
import {useEffect, useRef} from  "react";


function ScrollSequence(){
const canvasRef = useRef(null);

useEffect(() => {
// Get the canvas element and its 2D context
const canvas = canvasRef.current;
const context = canvas.getContext("2d");
}

return (<section className="png__sequence">
<canvas ref={canvasRef} width = {window.innerWidth} height={window.innerHeight} className = "png__sequence__canvas"  id="canvas"> </canvas> 
</section> 
    );
}

Preparing Images

The images in our animation would be rendered on the canvas in sequence, based on the user's scroll position.

Name the images in in a sequence that matches their intended order, for example, image001.jpg, image002.jpg, image003.jpg, and so on. Don’t worry about this, the tool you used in creating the image sequence will handle this automatically.

Naming them this way will help us keep track of the current image being rendered on the canvas.

// number of images to be sequenced
const frameCount = 147;

// Generates the filename of the image based on the current index
const currentFrame = (index) => {
      return `/src/assets/xioami-watch-3-hero-asset/Home_${index
        .toString()
        .padStart(3, "0")}.jpg`;
    };
}

The value of the frameCount variable represents the total number of images that will be included in the PNG sequence.

Drawing Images on Canvas

The next step is to load the images and draw them on the canvas.

// Drawing the initial image on the canvas
const img = new Image();
    img.src = currentFrame(0);
    img.onload = function () {
      context.drawImage(img, 0, 0, canvas.width, canvas.height);
    };

The drawImage method takes 5 arguments:

The image
The x and y axis coordinate at which to place the top-left corner of the image on the canvas
canvas.width specifies The width to draw the image in the destination canvas
canvas.height specifies The height to draw the image in the destination canvas

Preloading Images

Preloading images ensures that they are downloaded and cached by the browser, so that they are ready to be displayed when needed. This can help to ensure a smoother animation experience, as the images will not need to be loaded while the animation is running.

To preload all the images before starting the animation, we can create a new Image object for each image and set its src property to the corresponding image filename. Once the images have been created, we can start the animation.

const preloadImages = () => {
      Array.from({ length: frameCount }, (_, i) => {
        const img = new Image();
        img.src = currentFrame(i);
      });
    };

Updating Images

Update the current image, so it can be drawn on the canvas as the user scrolls.

const updateImage = (index) => {
      img.src = currentFrame(index);
      context.drawImage(img, 0, 0, canvas.width, canvas.height);
    };

Tracking Scroll Position

The animation is driven by the user's scroll position. As the user scrolls down or up the page, we calculate the scroll position and map it to the appropriate frame index.

The canvas is then updated with the image corresponding to the calculated frame index, giving the illusion of movement.

window.addEventListener("scroll", () => {
      const html = document.documentElement;
          const wrap = document.querySelector(".png__sequence");
      const scrollTop = html.scrollTop;
      const maxScrollTop = wrap.scrollHeight - window.innerHeight;
      const scrollFraction = scrollTop / maxScrollTop;
      const frameIndex = Math.min(
        frameCount - 1,
        Math.floor(scrollFraction * frameCount)
      );
      requestAnimationFrame(() => updateImage(frameIndex + 1));
    });

    preloadImages();

html is the document.documentElement object, which represents the HTML document itself.
scrollTop is the current scroll position of the HTML document.
maxScrollTop is the maximum scroll position of the .png__sequence element.
scrollFraction is the ratio of the current scroll position to the maximum scroll position.
frameIndex is the index of the current frame, based on the scroll fraction.
The requestAnimationFrame function requests a new animation frame.
The updateImage function updates the image on the canvas to the image corresponding to the current frame index.
The window.addEventListener function listens for the scroll event and updates the frame index accordingly.

Putting it all together:

import { useEffect, useRef } from "react";


function scrollSequence() {
 const canvasRef = useRef(null);
 useEffect(() => {
    const canvas = canvasRef.current;
    const context = canvas.getContext("2d");

// number of images to be sequenced
    const frameCount = 147;

// Function to generate the filename of the image based on the current index
    const currentFrame = (index) => {
      return `/src/assets/xioami-watch-3-hero-asset/Home_${index
        .toString()
        .padStart(3, "0")}.jpg`;
    };

// Drawing the initial images on the canvas
    const img = new Image();
    img.src = currentFrame(0);
    img.onload = function () {
      context.drawImage(img, 0, 0, canvas.width, canvas.height);
    };

//preloading images 
     const preloadImages = () => {
      Array.from({ length: frameCount }, (_, i) => {
        const img = new Image();
        img.src = currentFrame(i);
      });
    };

//update images
     const updateImage = (index) => {
      img.src = currentFrame(index);
      context.drawImage(img, 0, 0, canvas.width, canvas.height);
    };

// Tracking the user scroll position
     window.addEventListener("scroll", () => {
      const html = document.documentElement;
      const wrap = document.querySelector(".png__sequence");
      const scrollTop = html.scrollTop;
      const maxScrollTop = wrap.scrollHeight - window.innerHeight;
      const scrollFraction = scrollTop / maxScrollTop;
      const frameIndex = Math.min(
        frameCount - 1,
        Math.floor(scrollFraction * frameCount)
      );
      requestAnimationFrame(() => updateImage(frameIndex + 1));
    });
    preloadImages();

  }, []);
  return (
<div className="png__sequence">
<canvas ref={canvasRef} width = {window.innerWidth} height={window.innerHeight} className = "png__sequence__canvas"  id="canvas"> </canvas> 
</div>

  );
}

This is my result.

Conclusion

That's it folks, thank you for getting to this point. You can go crazy with this by implementing smooth scrolling using the Lenis smooth scroll library, or add text at different scroll positions using GSAP animation library. Until next time, Happy coding!