DEV Community: Menard Maranan

Why Alt Text Matters for Shopify Seo

Menard Maranan — Mon, 09 Mar 2026 11:04:45 +0000

Most Shopify merchants spend hours obsessing over the right keywords, building backlinks, and tweaking meta descriptions — yet they leave one of the easiest SEO wins completely untouched: image alt text.

If your store has dozens or hundreds of product images with no alt text, you're leaving rankings, traffic, and sales on the table. Here's why alt text matters more than most merchants realize, and what you can do about it.

What Is Alt Text?

Alt text (short for "alternative text") is a short written description attached to an image. It lives in the HTML behind your storefront and is invisible to shoppers under normal circumstances — but it's read by search engines and screen readers.

In Shopify, you can add alt text to product images directly from the product editor.

In HTML, it looks like this:

<img src="blue-running-shoes.jpg" alt="Men's blue lightweight running shoes with cushioned sole" />

Simple enough. But that small attribute has a surprisingly large impact.

Why Google Cares About Alt Text

Google can't see images the way humans do. Instead, it relies on text signals to understand what an image contains — and alt text is the most direct signal available.

When Google crawls your Shopify store, it reads the alt text on every image to:

Understand the content of the page. Alt text reinforces the topic of the surrounding page, adding relevance context for your target keywords.
Index images in Google Image Search. Product images that rank in image search can drive significant discovery traffic — especially in fashion, home decor, and lifestyle categories.
Determine ranking relevance. Pages with well-optimized alt text tend to rank better for their target queries because the text signals align with what the page is about.

In short, every untagged image is a missed opportunity to communicate with Google about what your page is selling.

The Shopify-Specific Opportunity

Here's something worth knowing: the majority of Shopify stores have incomplete or entirely missing alt text across their product catalog.

That's not an insult — it's just the reality of how stores are built. When you upload product photos, Shopify doesn't automatically generate alt text. The default is either blank or pulled from the image filename (more on why that's a problem shortly). Most merchants never go back to fix it.

This creates a real competitive edge for the stores that do. If you sell running shoes and your product images have descriptive, keyword-relevant alt text while your competitors' images are blank, your pages have a meaningful advantage in Google's eyes.

Beyond product images, there are other alt text fields merchants often overlook:

Collection page images — often set once and forgotten
Blog post images — a missed opportunity on an already SEO-focused asset
Homepage banners and lifestyle images — high-visibility images that frequently go untagged

Every image on your store is an opportunity. Most stores leave them all blank.

Alt Text and Accessibility — A Bonus Win

Alt text wasn't originally invented for SEO. It was created for accessibility — specifically, to help visually impaired shoppers who use screen readers navigate the web.

When a screen reader encounters an image with no alt text, it might read out the filename ("IMG_4823.jpg") or skip it entirely. For a visually impaired shopper trying to evaluate your product, that's a frustrating and exclusionary experience.

Writing descriptive alt text means those shoppers can understand what your product looks like, which builds trust and increases the likelihood of a purchase.

There's also a growing connection between accessibility and SEO. Google has indicated that user experience signals matter for rankings, and an accessible store is a better experience for everyone. Beyond rankings, accessibility is increasingly a legal and ethical consideration for online businesses.

Good alt text serves your SEO and your shoppers at the same time.

Common Mistakes Shopify Merchants Make

If you've started thinking about alt text, here are the pitfalls to avoid:

Leaving it blank. The most common mistake. No alt text means no signal — Google and screen readers get nothing useful from your images.

Using raw file names. Shopify will sometimes use the image filename as a fallback. "DSC_00142.jpg" or "product-image-v3-FINAL.png" tells Google absolutely nothing about your product.

Keyword stuffing. Cramming as many keywords as possible into alt text ("buy cheap blue running shoes men running shoes discount free shipping") looks spammy to Google and is a poor experience for screen reader users. Google can and does penalize this.

Generic descriptions. "A shoe" or "product image" technically isn't blank, but it's nearly as useless. Vague descriptions don't help Google understand what's unique about your product.

What Good Alt Text Looks Like

Good alt text is descriptive, specific, and naturally includes relevant keywords without forcing them. Here are some before-and-after examples:

Image	Bad Alt Text	Good Alt Text
A pair of blue running shoes	(blank)	Men's blue lightweight running shoes with cushioned sole
A ceramic coffee mug	"mug"	Handmade ceramic coffee mug in matte terracotta glaze, 12oz
A floral summer dress	"IMG_8821.jpg"	Women's floral wrap midi dress in yellow and white, sleeveless
A leather wallet	"product"	Slim minimalist leather bifold wallet in tan, holds 6 cards

The formula is straightforward: what it is + key descriptive details + material or context where relevant. Write it the way a customer would describe the product to someone who can't see it. Keywords tend to appear naturally when you do this well.

The Scale Problem — Why Most Stores Don't Do This

Here's the honest reality: if you understand why alt text matters, you probably want to fix it across your entire store. But that's easier said than done.

A Shopify store with 200 products, each with 4–5 images, means 800–1,000 images to write alt text for. Doing that manually — opening each product, writing a description, saving, moving to the next — would take days of tedious, repetitive work. And that's before you consider new products being added regularly.

This is exactly why most stores never get it done, even when the owner knows they should. The intent is there; the bandwidth isn't.

This is the problem Syncor Alt was built to solve: AI-powered bulk alt text generation for Shopify stores, so merchants can optimize their entire image catalog in minutes rather than days.

Conclusion

Alt text is one of the highest-leverage, lowest-effort SEO improvements available to Shopify merchants.

Your alt texts — properly written, SEO-optimized, and WCAG-compliant is an easy and quick SEO win. Syncor Alt takes the manual work off your plate, generating SEO-optimized and WCAG compliant alt text that is loved by Search Engines.

Get started with 50 free credits — enough to see the difference on 50 of your product images right away. Syncor Alt doesn’t have subscriptions, so it’s 100% risk free.

Try Syncor Alt - https://apps.shopify.com/syncor-alt

Or watch this demo to see how it works: 🎥 https://www.youtube.com/watch?v=09YwpX8VCnc

Traffic Light - vanilla HTML, CSS, & JavaScript

Menard Maranan — Thu, 05 Mar 2026 03:47:10 +0000

I created this fun little project as a refresher.

🌐 Demo: https://menard-codes.github.io/traffic-light/
👨‍💻 Code: https://github.com/menard-codes/traffic-light

I haven't touched pure vanilla HTML, CSS, and JavaScript for a while.

React, Tailwind, and TypeScript is what I use everyday in the frontend, so I want to challenge myself if I still got the basics right without relying on modern conveniences of frameworks and tools.

And since there's no React to help me manage component state, I have to rely on the observer pattern if I want a similar functionality.

So I decided to try and build a Traffic Light simulator, only using HTML, CSS, and JavaScript.

Markpup

<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Document</title>
    <link rel="stylesheet" href="style.css" />
  </head>
  <body>
    <main>
      <div class="traffic-light">
        <div class="timer-box">
          <p id="timer"></p>
        </div>
        <div class="box">
          <div class="light red"></div>
          <div class="light yellow"></div>
          <div class="light green"></div>
        </div>
      </div>
    </main>

    <script src="./script.js" defer></script>
  </body>
</html>

Stylesheet

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

main {
  min-height: 100vh;
  display: grid;
  place-items: center;
}

.traffic-light {
  display: grid;
  gap: 1rem;
}

.traffic-light .box {
  width: 8rem;
  height: 20rem;
  background-color: #1d1e22;
  border-radius: 1.5rem;
  display: flex;
  flex-direction: column;
  gap: 1.2rem;
  justify-content: center;
  align-items: center;
}

.light {
  width: 5rem;
  aspect-ratio: 1 / 1;
  border-radius: 50%;
}

.red {
  background-color: #500;
}

.red.on {
  background-color: #f00;
}

.yellow {
  background-color: #550;
}

.yellow.on {
  background-color: #ff0;
}

.green {
  background-color: #050;
}

.green.on {
  background-color: #0f0;
}

.timer-box {
  background-color: #555;
  border: 5px solid #333;
  border-radius: 1rem;
  padding: 0.5rem 1rem;
  text-align: center;
}

#timer {
  font-family: "Courier New", Courier, monospace;
  font-weight: 700;
  color: #0f0;
  font-size: 4rem;
}

#timer.warn {
  color: #f00;
}

Traffic Light logic

I created 3 classes:

Timer
Light
TrafficLight

The TrafficLight and Light classes follow the observer pattern.

The TrafficLight.run() method handles switching the currently active light, notifying the subscribers, and running/resetting the timer on every light switch.

document.addEventListener("DOMContentLoaded", () => {
  class Timer {
    _currentCount = 0;
    _interval = null;
    _timer = document.querySelector("#timer");

    constructor() {
      this._timer.textContent = this._currentCount;
    }

    /**
     * @param {{ maxCount: number; currentColor: TrafficLightColor }}
     */
    start({ maxCount, currentColor }) {
      // Reset count and clear any existing interval before starting fresh
      this._currentCount = maxCount;
      this._setTimerDisplay({ currentColor });

      if (this._interval !== null) {
        clearInterval(this._interval);
      }

      this._interval = setInterval(() => {
        this._currentCount--;

        if (this._currentCount <= 0) {
          this.stop();
        }

        this._setTimerDisplay({ currentColor });
      }, 1000);
    }

    stop() {
      if (this._interval !== null) {
        clearInterval(this._interval);
        this._interval = null;
        this._currentCount = 0;
        this._timer.classList.remove("warn");
      }
    }

    /**
     * @param {{ currentColor: TrafficLightColor }} param0
     */
    _setTimerDisplay({ currentColor }) {
      this._timer.textContent = String(this._currentCount).padStart(2, "0");
      switch (currentColor) {
        case "green": {
          this._timer.classList.add("go");
          this._timer.classList.remove("wait");
          this._timer.classList.remove("stop");
          break;
        }
        case "red": {
          this._timer.classList.add("stop");
          this._timer.classList.remove("wait");
          this._timer.classList.remove("go");
          break;
        }
        case "yellow": {
          this._timer.classList.add("wait");
          this._timer.classList.remove("go");
          this._timer.classList.remove("stop");
          break;
        }
      }
    }
  }

  /**
   * @typedef {'red' | 'yellow' | 'green'} TrafficLightColor
   */
  class Light {
    /**
     * @param {TrafficLightColor} color
     */
    constructor(color) {
      this.color = color;
      this._dom = document.querySelector(`.${color}`);
    }

    /**
     * @param {TrafficLightColor} currentColor
     */
    notify(currentColor) {
      if (currentColor === this.color) {
        this._turnOn();
      } else {
        this._turnOff();
      }
    }

    _turnOn() {
      this._dom.classList.add("on");
    }

    _turnOff() {
      this._dom.classList.remove("on");
    }
  }

  class TrafficLight {
    _listeners = [new Light("red"), new Light("yellow"), new Light("green")];

    /**
     *
     * @param {{ timeInterval: number }} {timeInterval} - Time interval in seconds for switching the lights.
     */
    constructor({ timeInterval } = {}) {
      this._timeInterval = timeInterval ?? 60;
    }

    async run() {
      const timer = new Timer();
      const listenersLength = this._listeners.length;
      let currentPointer = listenersLength;
      while (true) {
        const nextPointer = currentPointer - 1;
        currentPointer = nextPointer < 0 ? listenersLength - 1 : nextPointer;
        const colors = this._listeners.map((listener) => listener.color);
        const currentColor = colors[currentPointer];

        this._listeners.forEach((listener) => listener.notify(currentColor));

        // Start timer AFTER switching the light, so count is in sync with current light

        const sleepInMS =
          currentColor === "yellow"
            ? Math.max(this._timeInterval - (this._timeInterval - 6), 6) * 1000
            : this._timeInterval * 1000;

        timer.start({ maxCount: sleepInMS / 1000, currentColor });

        await this._sleep(sleepInMS);

        timer.stop();
      }
    }

    async _sleep(time = 1000) {
      await new Promise((res) => setTimeout(res, time));
    }
  }

  const trafficLight = new TrafficLight({ timeInterval: 15 });
  trafficLight.run();
});

Final thoughts

Unintentionally, I also had to refresh my understanding of the browser event loop. I ran through several bugs because of improper use of intervals, timeouts, and promises. That reminded me of the time when I was first learning about the event loop, pulling my hair out of frustration trying to understand it, lol.

Developer-Focused Resume Builder: An MVP in Progress

Menard Maranan — Tue, 08 Apr 2025 16:38:40 +0000

I've been thinking about a problem I've noticed in the tech job search process.

Well, there are a lot of problems in that matter, but something that I've always wanted is a more developer-focused resume builder.

I don't really build my resumes manually. It's time-consuming, tedious, and too boring for me so I just use a resume builder.

While there are plenty of resume builders out there, most are designed for any profession giving you a generic, cookie-cutter resume.

I just don't like how they don't really cater to the unique aspects of showcasing developer skills.

The Problem I'm Trying to Solve

Generic resume builders often miss what makes developers stand out. Some things I noticed:

Many aren't structured to showcase technical skills effectively
Rarely highlights developer-specific achievements (PRs, commits, hackathons)
Don't emphasize GitHub contributions and open-source work
Many of them don't even optimize for technical ATS systems

It's just hard to make it appear on a resume how well you know a certain technology is. Sometimes those pesky algorithms and HRs who don't have much technical background just dump your resume just because it appears to them that you're not fit enough for the job (arrgghh).

On the flip side, I've seen other people's resumes and what I often take an interest in is the skills section. You'll often see it sprinkled with a variety of languages, frameworks, and tools, without giving any context on how much expertise or experience they have on each of those technologies.

Have they just created a Hello World program with this language or actually use it on a day-to-day basis?

Anyway... We're moving away from the topic but I hope you get the idea. So going back...

My Idea: A Developer-Focused Resume Builder

I'm working on a specialized resume builder that's designed specifically for developers. The goal is to help you create resumes that better represent your technical background and increase your chances of landing dev jobs.

Some features I'm considering:

Github integration to get to know your projects, PRs, commits, etc. and generate parts of the resume from that (skills and expertise, achievements, projects, soft skills, etc.).
Templates designed with developer roles in mind
Sections for GitHub projects, Stack Overflow contributions, and open-source work. Maybe with dev.to hackathons too?
ATS optimization specific to tech job applications
Quick skills section that understands the difference between "proficient in" vs "familiar with"
And moar...

The MVP Is Live!

I've built a stupidly simple MVP (without any of the feature I mentioned, just yet) to get an idea if the dev community would even take an interest in this.

It's very basic right now - just a multi-step form that collects your information and generates a downloadable PDF. No fancy templates and all those cool features I've thought of just yet, but the idea is there.

Dev Resume Builder
https://dev-resume-orcin.vercel.app/

I built it with React Router 7 for quick development. This is just a validation prototype - if there's enough interest, I plan to rebuild with a more robust tech stack.

I Need Your Input

I'm still in the ideation and validation stage, and I'd love to hear your thoughts:

Would you use a resume builder specifically designed for developers?
What features would make it worth using over generic tools?
What's your biggest pain point when creating a developer resume?
Any other feedback on the concept or the MVP?

If you're interested in updates as this idea develops, you can sign up for the mailing list on the MVP site.

Thanks for reading, and I'm looking forward to your thoughts!

Secure File Share - A safer way to share sensitive files online

Menard Maranan — Sun, 13 Oct 2024 23:37:40 +0000

This is a submission for the The Pinata Challenge

What I Built

I've developed "Secure File Share", an open-source, self-hostable file sharing solution that addresses a common need in our digital world: the secure sharing of sensitive files without relying on third-party services.

Inspiration

Being a developer working with a remote team, it is very common for us to share sensitive company files online, which is at risk of accidentally leaking to the outside world. Files have been scattered over email attachments, chat threads, and anywhere we communicate. For now, we adopted the password-protected files sharing feature of Google Drive but we're always looking for solutions without any 3rd party involvement and where we can have full control over our files, especially if we can self-host it. Our DevOps guy is working on a solution, but if I were to build that solution, this is how I imagine it to be.

This is also heavily inspired by Onetimesecret. This is like one time secret, but for files.

How it Works

Upload a file you want to share
Set a passphrase and expiration, then click Create Share Link
Send the share link to your intended recipient/s. It's recommended to share the passphrase separately.

The uploaded file as well as its records will all be deleted upon the specified expiration date. Upon viewing the file, the set expiration will be overwritten and will be set to 5 minutes before it's totally gone.

Key features of Secure File Transfer include:

Disposable and password protected share links
No sign-up required.
Fully self-hostable

Demo

(Update: I already took down the demo as I'm getting a lot of traffic and I don't wanna end up with a huge bill in fly.io or redis cloud😅 besides, this project is intended to be self-hosted, so that's what I encourage everyone intending to use this to do. There are hosting services out there with generous free-tier like fly.io. I highly recommend self hosting this if you're intending to use it for full security and control over your sensitive files. I'm taking down the demo but the source code will always be available. You're free to fork it, make your own modifications if you'd like, and self-host it. I left a docker-compose file there if you don't want a separate redis server, especially if you're hosting this in a VPS.

Quick Peek

My Code

Here's the link to the Github Repo: https://github.com/menard-codes/secure-file-transfer

menard-codes / secure-file-transfer

Secure File Transfer

A Dev x Pinata hackathon project for secure file sharing via password-protected disposable share links.

Overview

"Secure File Transfer" is an open-source, self-hostable file sharing solution that allows users to generate secure, password-protected file share links with customizable expiration dates. This application doesn't require any logins or signups - it's designed for simple, secure file sharing.

This app mainly solves the issue of sharing sensitive information online, without the need of signing up from any 3rd party app. Since this can be self-hosted, you can have full control over your files.

How it Works

Upload a file you want to share
Set a passphrase and expiration, then click Create Share Link
Send the share link to your intended recipient/s. It's recommended to share the passphrase separately.

Key Features

Generate secure, password-protected file share links
Set custom expiration dates for shared links
No user accounts or logins required
…

View on GitHub

(NOTE: You can read the README for more info)

Tech Stack

Backend: Express.js with TypeScript
Frontend: EJS templates, Bulma CSS framework, Alpine.js
Database: SQLite with Prisma ORM (easily replaceable if needed)
File Storage: Pinata cloud
Background Tasks: BullMQ with Redis

I tried to be as light weight as possible when choosing the techstack and to not over engineer this. That said, I just have a simple express ts backend, ejs templates with Alpine.js (for minimal frontend interactivity) and Bulma as the CSS framework. The database is just an sqlite file since I don't see a need for a full blown database in this hackathon project, but this can be easily changed since I used Prisma ORM for it. Just modify the datasource. I use BullMQ with Redis for background tasks (handling file expiration). And of course, Pinata cloud. I hosted this in fly.io as they have a generous free tier plan but this can be hosted anywhere, like in VPS (there's a docker compose you can use).

More Details

Pinata plays a pivotal role in this project as all the shared files need to be stored somewhere, and that's where Pinata fits.

Here's the myPinata.ts file where I primarily interacted with Pinata via the Files SDK

import { FileObject, PinataSDK } from "pinata";
import dotenv from "dotenv";

dotenv.config();

const pinata = new PinataSDK({
    pinataJwt: process.env.PINATA_JWT,
    pinataGateway: process.env.PINATA_GATEWAY
});

export async function uploadFile(file: FileObject) {
    try {
        const upload = await pinata.upload.file(file);
        return upload;
    } catch (error) {
        console.error(error);
    }
}

export async function getFileUrl(cid: string, expires=1800) {
    try {
        const signedUrl = await pinata.gateways.createSignedURL({
            cid,
            expires // defaults to 30 minutes (1800 seconds)
        });
        return signedUrl;
    } catch (error) {
        console.error(error);
    }
}

export async function deleteFile(fileId: string) {
    try {
        const deleted = await pinata.files.delete([fileId]);
        return deleted;
    } catch (error) {
        console.error(error);
    }
}

I use these three functions in my endpoint handlers to handle file operations with Pinata. My background tasks also use the deleteFile function, since these background tasks are used for dispatching deletion jobs at the set expiration of the files.

Star Wars Themed Solar System Guide - Glam Up My Markup

Menard Maranan — Sun, 08 Sep 2024 08:04:50 +0000

This is a submission for Frontend Challenge v24.09.04, Glam Up My Markup: Space

What I Built

Explore the Solar System: A Star Wars-Inspired Galactic Journey

Imagine stumbling upon a legendary travel brochure from a galaxy far, far away—a guide to a mysterious star system known as the Solar System. In the spirit of the Star Wars universe, this project transforms our own celestial neighborhood into an intergalactic destination for adventurous travelers. From the shimmering orbits of the planets to the enigmatic asteroid belt and icy Kuiper Belt, this guide serves as your Jedi-approved travel companion. Packed with knowledge on the heavenly bodies, planets, moons, and cosmic wonders, it's like a holographic map leading you on a stellar tour through a system that feels as exotic as Tatooine, yet as familiar as home.

Demo

Demo: https://menard-codes.github.io/starwars-outer-space/
Source Code (Github Repo): https://github.com/menard-codes/starwars-outer-space

Journey

Coming from the realm of frontend frameworks and web components, this was my first time diving into vanilla CSS and JavaScript without altering the HTML markup—a real challenge that pushed me to level up my skills in JS DOM manipulation and explore some cool CSS features. I hacked this together over a weekend, so it’s far from perfect and has a few UI quirks. If I had more time (I wish I did!), I’d smooth out all the rough edges.

I also have some big ideas for future enhancements. Imagine orbiting moons, parallax effects, and an interactive experience that truly immerses you in the Solar System, Star Wars-style, but in 8-bit glory. With just two days to work on it, this was a quick project, but if I had months, I could take it to a whole new level of awesomeness.

References

I also want to credit these sources where I got the assets for this project:

AI Image generation: https://firefly.adobe.com/
AI-Generated 8-bit Pictures of the Planets, moons, and other heavenly bodies: Imagen 3 by Google Gemini https://gemini.google.com/
Death Star in 8-bit by FanManDan16: https://www.newgrounds.com/art/view/fanmandan16/pixel-death-star
Star Destroyer pixel art: https://www.pngwing.com/en/free-png-tzcob#google_vignette
Star Wars Font by Boba Fonts: https://www.dafont.com/star-jedi.font
The ITC Serif Gothic Font uploaded by Eladio Simonis: https://font.download/font/itc-serif-gothic-2

And this online tool:

To remove the background of images: https://www.remove.bg/upload

My Pomodoro Clock Project

Menard Maranan — Tue, 28 Nov 2023 15:50:47 +0000

TL;DR: I'm learning state management in React and I built this Pomodoro Clock. No state management libraries used (i.e. Redux), just Context Managers, useRef, and useState. Also, this blog is more of a personal journal rather than a technical guide or a tutorial.

Journal

I'm using React.js for quite some time now, but lately I decided to step back and relearn the fundamental concepts.

State Management is at the core of React.js which I barely focused on when I first started learning React. This gave me headaches down the road after I encountered deeply nested components with complex state logic.

This is a common mistake committed by beginners (like me), which is not paying attention to the fundamentals.

Not knowing proper state management gave me problems like prop drilling and handling unnecessary states, while my code is messy, hard to read, and ill-structured. As a result, the app itself is buggy, inefficient, and have tons of unnecessary re-renders. Yikes!

So with this problem, I decided to learn proper state management in React.

My main resource for this is this section of the React docs about state management. After reading it, I decided to put my learnings to the test and try to build a project with complex state logic.

For this, I decided to build a Pomodoro clock.

The Project

NOTE: If you look at my code, you may still see some issues regarding proper state management and structuring my code, but this is an improvement as compared to my last projects with improper state management. I'll be kind to myself and take it as a good first step😉

Learnings

I learned a lot from what I read in the React docs as well as on that project, but I'll try to summarize some of my learnings.

Thinking in React

This section in the React docs about thinking in React resonates on me.

I learned that when building React projects, you should start with a mockup and plan your project from there.

By braking it down:

Have some kind of UI Wireframe or mockup of the UI. This will become the basis of the rest of the plan.
Break the UI into a component hierarchy. Identify which parts of the UI makes sense to be grouped together and define the components that will make up your UI based on your mockup.
Build a static version. Start defining the markup first. State and props can be added later. You can use static data for the state and props so that you can check how your components reacts to these inputs.
Find the minimal but complete representation of the UI State. Identify all the data your components will rely on. Then from these data, identify which ones are dynamic (changing) and can't be calculated from other data/input. All of the data that fits this criteria is considered a state. If several components rely on a similar data, it makes sense to not give them their own separate states but rather let these components share this data so that they're in sync.
Identify where your state should live. Now that you identified the states in your project, it's time to identify which components should hold these states and how shared states will be handled. If sibling components would rely on a state and they won't be deeply nested, just pass these data as props. If the components relying on this state exceeded more than 1 or two prop passings, it just makes sense to pass the state via Context Managers.
Identify how to manage inverse data flow. State trickles down the component tree, but for managing state changes made by child components, you need to pass down state setters as well, just like the state. Identifying where state setters should live and how to pass them is the same as how you identified where your states should live.

I built a Snake Game in React

Menard Maranan — Sun, 05 Nov 2023 09:46:44 +0000

TL;DR: I built this classic "Snake Game" using React, HTML Canvas, and TypeScript. No third-party libraries are used.

Play the Game: https://snakes-game-nine.vercel.app/
Source Code: https://github.com/menard-codes/snakes-game

Background Story

While I was bored and lying on the swing the other day, a random thought just went into my head. I remember back in the days that I used to play this Snakes game on a Nokia phone. So I wondered how could I build a game like this🤔.

Web development is my thing, I'm not a game dev and I never built a game before, so this would be a challenge.

But tackling a challenge is also my thing.

So I sat there for a couple of hours conceptualizing this possibly 'new project' to see if I could pull this up. I wrote down my ideas and the structure of the project on my phone, as well as some pseudocode.

After pondering about it for a while, I think I can build this thing and I have a rough concept in my phone, with all the game logic ready to be implemented and tested if this idea works.

Development Time

I was excited to start this project. So I brought my phone with my concept in it, went to my computer, and opened VS Code.

I've thought of what tech should I use. Welp, I don't think I have lots of choices, I only know React (as I said, I'm just a web developer 😅). But since the game will be implemented primarily using HTML Canvas, I thought React would be optional as I can build this without a framework. But still, I pushed on as I hadn't built a React project before with this complex Canvas Element logic, so I gave it a try.

Of course, I used TypeScript😉.

And ohh, no CSS libraries. A plain 'ol CSS would do the trick since the UI won't be too complex and the components that I will style won't be that much.

After several hours of coding (and tons of debugging), I finally managed to implement the game logic and my idea came to fruition. It's rough to the edges but the game is already working.

This is the first game I made and the joy of making it work is priceless. It was just an idea moments ago and now I'm already playing it.

Anyway, I'm also a bit tired at this moment so I continued the other day.

So on the next day, I spent most of my hours fixing several bugs in the code. I also added some new features, like the scoring, high score, and pause/play.

Then it's finished. I was so ecstatic. I showed it to my brothers and let them play for a while (and also to check if they might encounter some bugs, which they actually did).

After fixing those minor bugs and making the game fully working, I hosted it on Vercel and wrote this blog.

Demo

Play the Game: https://snakes-game-nine.vercel.app/
Source Code: https://github.com/menard-codes/snakes-game

Features

Classic Snake gameplay
Score tracking
Saves HighScore
Game over screen with the option to restart
Keyboard controls for navigation

Tech Stack

React.js and HTML Canvas
TypeScript for type safety
No third-party libraries used

Game Controls

Use the arrow keys or W,A,S,D keys on your keyboard to control the snake's direction:

↑ (Up) or W - Move Up
↓ (Down) or S - Move Down
← (Left) or A - Move Left
→ (Right) or D - Move Right

Others:

To Pause the game - Press esc or click anywhere on the screen

React.js: Why you might need useReducer

Menard Maranan — Wed, 05 Jul 2023 07:50:10 +0000

Hooks in React.js is at the core of building functional components. Among the most used are the state management hooks, or simply the state hooks.

In React, two hooks allow you to manage the state:

useState - Gives you a state variable and a function to change the value of the state
useReducer - Gives you a state variable and a dispatch function for updating the state (via another function called a reducer function).

Both hooks do the same thing, "to manage state", and what you can do with useState can also be done with useReducer and vice versa.

So how do they differ?

The useState hook is the simpler one and is more commonly used. Meanwhile, useReducer (which is based on Redux - a state management library) is often mocked to have tons of boilerplate code.

But treating these hooks this way doesn't give useReducer justice.

There are use cases why useReducer makes a better option than useState.

In this article, I will discuss why you might want to consider using useReducer in some cases over the useState hook.

Organizing the logic for changing the state

When managing a complex component state, your update logic might look messy, especially if you have different ways on changing the state.

I'll give you a simple example - a counter component. Let's say you need to build this component with the following requirements:

the component should have a state for tracking the count
you should be able to increment, decrement, as well as reset the count.
when the count value is 10 or more, the increment and decrement value must be 10.
when the count value is -10 or less, the increment and decrement value must be 5.
when the count value is between -9 and 9 (inclusive), the increment and decrement value is just 1
Resetting the state reverts the count value to 0

So in this example component, we're required to have 3 update logics to the state (increment, decrement, reset) where both increment and decrement update logics have 3 different conditions.

With useState, you might do it this way:

import { useState } from "react";

function Counter() {
    const [count, setCount] = useState(0);


    // The count update logics:
    // handleIncrement, handleDecrement, and handleReset

    const handleIncrement = () => {
        let incrementValue: number;

        if (count >= 10) {
            incrementValue = 10;
        } else if (count <= -10) {
            incrementValue = 5;
        } else {
            incrementValue = 1;
        }

        setCount(prevCount => prevCount + incrementValue);
    }

    const handleDecrement = () => {
        let decrementValue: number;

        if (count >= 10) {
            decrementValue = 10;
        } else if (count <= -10) {
            decrementValue = 5;
        } else {
            decrementValue = 1;
        }

        setCount(prevCount => prevCount - decrementValue)
    }

    const handleReset = () => {
        setCount(0);
    }


    return (
        <div>
            <p>Count: {count}</p>
            <button onClick={handleIncrement}> + </button>
            <button onClick={handleDecrement}> - </button>
            <button onClick={handleReset}>Reset</button>
        </div>
    )
}

So in this simple component, you'll see how convoluted the component can get because of those update logics. You may reason out that you can simplify the state update logic by refactoring those three separate functions into one function that accepts a parameter to tell whether you want to increment, decrement, or reset. Sure that works, but how does that differ from creating a reducer function?

And this is why you might consider using useReducer. With useReducer, you can work with complex state management in a more organized way. The main reason why useReducer would be a great choice is that you have a complex state where you have different update logics, and you want to keep things organized. This makes it easier to debug the update logics later (or update them when the requirements change).

Alright, let's rewrite the same component but let's use the useReducer hook here. Let's put the reducer logic in another file and just import it on the component.

// counterReducer.ts

interface CounterAction {
    type: "increment" | "decrement" | "reset";
}

export interface CounterState {
    count: number;
}

export function counterReducer(state: CounterState, action: CounterAction) {
    const changeValue = state.count >= 10
                            ? 10
                            : state.count <= -10 ? 5 : 1;

    switch (action.type) {
        case "increment":
            return { ...state, count: state.count + changeValue };
        case "decrement":
            return { ...state, count: state.count - changeValue };
        case "reset":
            return { count: 0 };
        default:
            const _impossible: never = action.type;
            throw new Error(`Invalid action type: ${action.type}`);
    }
}

Now, let's import this in the counter component:

// Counter.tsx

import { useReducer } from "react";
import { counterReducer, CounterState } from "./counterReducer"

const initialState: CounterState = { count: 0 };

function Counter() {
    const [state, dispatch] = useReducer(counterReducer, initialState);

    return (
        <div>
            <h1>Count: {state.count}</h1>
            <button onClick={() => dispatch({ type: "increment" })}> + </button>
            <button onClick={() => dispatch({ type: "decrement" })}> - </button>
            <button onClick={() => dispatch({ type: "reset" })}> Reset </button>
        </div>
    )
}

So in this case, the reducer function handles all the update logic to the state. This way, you can abstract away from the nitty-gritty details of the state update logic and just specify in the component which update logic you want to take effect. And since we separated the reducer logic in another file, the Counter component here no longer needs to concern itself with the update logic, making things more organized. If you need to debug the update logic, it's easier to know where to look. When requirements change and you want to update these state update logic, it's easier to go to what you're looking for and make changes.

Now you might argue that this makes more boilerplate code (especially because I used TypeScript which adds more boilerplate), but eliminating boilerplate code is not the goal of useReducer (because it's definitely more verbose). Rather, you should use useReducer if you have to manage a complex state and you want the state update logic organized. And as mentioned earlier, organizing your state update logic this way makes it easier to debug and update later when requirements change.

Final thoughts

Hopefully, I conveyed to you the importance of useReducer and why you might want to use it in some cases over useState.

For further reading, I suggest you to look at extracting state logic into a reducer from React documentation. There's also a challenge at the end to help you better understand useReducer.

The Advantages of Medusa's Composable Architecture for Enterprise E-commerce Solutions

Menard Maranan — Wed, 19 Apr 2023 03:30:50 +0000

The e-commerce market has exploded in recent years, with more and more businesses turning to online sales to reach their customers.

As the market grows, so does the need for businesses to choose the right e-commerce platform to meet their specific needs. For enterprise-level businesses, this decision is particularly crucial, as they require a solution that can handle high traffic, large product catalogs, and complex requirements.

This is where Medusa comes in - a flexible, scalable, and customizable e-commerce platform that is built on a composable architecture.

In this article, we will explore the advantages of Medusa's composable architecture for enterprise-level e-commerce solutions, and why it is the perfect choice for businesses looking for a comprehensive and flexible e-commerce solution.

Advantages of Medusa's Composable Architecture for Enterprise Solution

Medusa's composable architecture offers several advantages for enterprise-level e-commerce solutions. It can be summed up with the following:

Customization and Flexibility
Scalability
Cost-effectiveness
No Vendor Lock-In
Integration with other tools
Security and compliance

Customization and Flexibility

One of the key advantages of Medusa's composable architecture is its ability to offer a high level of customization and flexibility. This is made possible through Medusa's modular and composable architecture, which allows businesses to choose only the features and functionalities that they need, and to easily customize and extend their e-commerce solution.

Medusa's modular architecture is made up of a series of interchangeable modules, each of which is responsible for a specific set of functionalities. This allows businesses to easily swap out modules, and to add or remove features as needed, without having to rebuild their entire platform.

For example, a business that wants to offer a subscription service to its customers could easily add a subscription module to their Medusa e-commerce solution. This would allow customers to sign up for a subscription service, and for the business to manage and track subscriptions through the platform.

In contrast, traditional e-commerce platforms like Shopify or BigCommerce offer a more rigid architecture, with limited customization options. Businesses using these platforms are often required to pay for features and functionalities that they may not need or want, and may be unable to customize the platform to meet their specific requirements.

Scalability

Another advantage of Medusa's composable architecture is its ability to scale and handle high traffic and large product catalogs. Medusa is designed with a focus on performance and speed, making it a great choice for enterprise-level businesses that need an e-commerce solution that can handle large volumes of traffic and sales.

Medusa's scalable architecture is designed to handle high traffic and large product catalogs, with the ability to add and remove resources as needed. This is made possible through Medusa's modular and composable architecture, which allows businesses to easily add and remove modules as needed, and to scale their e-commerce solution as their needs grow.

For example, a business that experiences a sudden spike in traffic during a holiday season can easily add additional resources to their Medusa e-commerce solution, ensuring that the platform can handle the increased traffic.

In contrast, traditional e-commerce platforms like Shopify or BigCommerce may struggle to handle high traffic and large product catalogs, and may require businesses to pay for additional resources or upgrade to a more expensive plan in order to handle increased traffic.

Cost Effectiveness

One of the biggest advantages of Medusa's composable architecture is its cost-effectiveness, particularly for enterprise-level businesses. Medusa is an open-source platform, which means that businesses can save money on licensing fees that they may otherwise need to pay for traditional e-commerce platforms like Shopify or BigCommerce.

In addition, Medusa's modular and composable architecture allows businesses to choose only the features and functionalities that they need, rather than paying for a comprehensive e-commerce solution that includes features they may not need. This allows businesses to save money on unnecessary features and functionalities, and to focus their resources on building a customized e-commerce solution that meets their specific requirements.

For example, a business that only sells physical products may not need a subscription module, and can choose not to install it, rather than paying for it as part of a larger e-commerce platform.

In contrast, traditional e-commerce platforms like Shopify or BigCommerce often require businesses to pay for a comprehensive e-commerce solution, which may include features and functionalities that they do not need. This can result in higher costs for businesses, particularly for enterprise-level businesses that may require more customized e-commerce solutions.

No Vendor Lock In

Another advantage of Medusa's composable architecture is that it helps businesses avoid vendor lock-in. Since Medusa is an open-source platform, businesses have full access to the codebase, which means that they are not tied to a single vendor or service provider. Businesses can choose to host their Medusa backend wherever they want along with their data.

This is particularly important for enterprise-level businesses that require customized e-commerce solutions that may not be available through traditional e-commerce platforms. With Medusa's composable architecture, businesses have the flexibility to choose the vendors and service providers that best meet their needs, without being tied to a single e-commerce platform.

In addition, Medusa's modular and composable architecture allows businesses to easily switch out modules and integrations, without having to rebuild their entire e-commerce solution. This is in contrast to traditional e-commerce platforms, where businesses may be tied to a specific set of integrations and may have difficulty switching to a different platform.

Furthermore, Medusa's open-source nature allows businesses to take control of their own development and to build a customized e-commerce solution that meets their specific requirements. This gives businesses more control over their e-commerce solution, and allows them to respond quickly to changing market conditions and customer needs.

Integration with Other Tools

Another advantage of Medusa's composable architecture is its ability to integrate with third-party tools and services. Medusa's modular and composable architecture allows businesses to easily integrate their e-commerce solution with other tools and services in their technology stack, such as ERP systems, CRM systems, marketing automation platforms, and more.

For example, a business may use an ERP system to manage their inventory. Medusa can easily integrate with the ERP system to keep track of inventory levels and to update product information. This integration allows businesses to manage their inventory more efficiently and to ensure that they have the right products in stock at all times.

In addition, Medusa's composable architecture allows businesses to build a comprehensive e-commerce solution that is fully integrated with their existing technology stack. This can help businesses streamline their operations and improve their overall efficiency, by providing a single platform that can manage all aspects of their e-commerce operations.

In contrast, traditional e-commerce platforms like Shopify or BigCommerce may not offer the same level of integration with other tools and services. This can result in businesses having to manage multiple systems and platforms, which can be time-consuming and costly.

Security and Compliance

One of the critical considerations for enterprise-level businesses when choosing an e-commerce platform is security and compliance. Medusa's composable architecture provides businesses with the flexibility to implement security and compliance measures that are tailored to their specific needs.

Medusa allows businesses to choose which security and compliance measures to implement, such as adding PCI compliance features to their e-commerce solution.

For example, businesses that handle credit card information need to ensure they are PCI compliant. Medusa can help businesses achieve PCI compliance by providing features such as secure credit card storage, fraud detection, and protection against data breaches.

In contrast, traditional e-commerce platforms like Shopify or BigCommerce may offer a one-size-fits-all approach to security and compliance measures, which may not meet the specific needs of all businesses.

Final Thoughts

Medusa's composable architecture provides enterprise-level businesses with the flexibility, scalability, and customization they need to create a comprehensive e-commerce solution that meets their unique needs.

Medusa offers several advantages over traditional e-commerce platforms like Shopify and BigCommerce, including customization and flexibility, scalability, cost-effectiveness, integration with other tools, and security and compliance. By choosing Medusa, businesses can tailor their e-commerce solution to their specific requirements and have greater control over their platform's functionality and features.

For businesses that prioritize flexibility and customization, Medusa is an ideal choice. With its modular architecture, businesses can choose the features they need, integrate with their existing technology stack, and achieve compliance with relevant regulations and standards.

Overall, Medusa offers enterprise-level businesses a powerful and flexible e-commerce platform that can meet their unique needs. We highly recommend Medusa for businesses looking for a scalable, customizable, and cost-effective e-commerce solution.

How to Build a Custom Field Plugin for Webiny Headless CMS

Menard Maranan — Wed, 31 Aug 2022 14:10:21 +0000

The concept of Headless CMS has gained a steady increase in popularity as the way people consume data evolves. Today, data and content are delivered not just through websites, but also in mobile apps, smart watches, VR, smart assistants, IoT devices, and more. As a result, more and more Headless CMS providers have stepped in to fulfill the demand, each offering common and unique features to fulfill your content and data management needs.

Many of these Headless CMS platforms are proprietary. As a result, you’re locked into whatever feature and functionality there is your Headless CMS provider offers. If you need a certain feature or you want to customize something, you have no choice but to hope and wait for your provider to implement it (if they ever do).

Alternatively, you can use open-source Headless CMS platforms like Webiny. Webiny is an open-source framework that allows you to build serverless applications and websites, and as mentioned, it comes with a Headless CMS. Webiny’s composable architecture allows you to customize and extend its built-in features and functionalities, giving you full control over your entire software (such as your websites, GraphQL API’s resolvers, data types, schemas, Infrastructure as Code with Pulumi, etc) and data.

Most of Webiny’s functionality is built with plugins. When you need to extend Webiny’s built-in features, you’ll also need to use plugins (or build new ones that best fit your needs). So if you need a custom field type for your CMS content model, you can create a new one through plugins.

To demonstrate, this article will guide you through building a custom field type for Webiny’s Headless CMS content model. And to build that custom field, we will use a set of built-in plugins in Webiny for constructing a new content model field type. We’ll do this through a step-by-step process with code samples and screenshots to help you along the way, so feel free to follow along.

In this article, you’ll learn:

What are the plugins used to construct a new CMS content model field type
How to create your custom field plugin

Building a custom CMS model field type

Like other Headless CMS platforms, Webiny comes with built-in content model fields. You can get pretty far with these built-in fields. But depending on your needs, you might need to have a content model that requires a property that doesn't come with Webiny's built-in field types. And in cases like this, you'll need to create your custom CMS content model field type.

Plugins for Creating a Custom CMS Field

To build your custom field, you’ll need to use several plugins that all come with Webiny. These built-in plugins will help you define and build your new content model field type.

There are five plugins related to building new content model field types, where three of which are required and two are optional:

CmsEditorFieldTypePlugin - This is a required plugin used to define some properties of your new content model field, from its name, type, description, label, the icon to associate with this new field, and more. Registering the plugin you created with CmsEditorFieldTypePlugin will render your new field type to the content model UI editor.
CmsEditorFieldRendererPlugin - This is another required plugin used to define the renderer for your new field type. With this plugin, you’ll define the component to render the field you’re creating. It can be as simple as an input or as complex as a widget.
CmsModelFieldToGraphQLPlugin - This is the third required plugin used to define the new field’s schema, resolver, filters, etc. to the GraphQL API.
CmsModelFieldToStoragePlugin - This is an optional plugin that sits in between your storage and API layer. With this plugin, you can manipulate the data before it’s sent to the storage layer (for example: censoring profanity in a blog post or comment) or after retrieving the data from the storage (and do things like decrypting an encrypted text).
CmsModelFieldToElasticSearchPlugin - This is also an optional plugin that is similar to the CmsModelFieldToStoragePlugin for being an intermediary. But in this case, instead of the storage layer, this plugin sits in between the API layer and ElasticSearch. With this plugin, you can manipulate the data before it is sent to the index or after retrieving it.

Prerequisites

Before we begin with the steps on building a custom content model field, make sure you have the following if you want to follow along the tutorial:

Node.js 14.0.0 or higher
Either of the two: yarn 1.22.0 (classic) or higher || yarn 2 (berry) or higher
An AWS account and pre-configured user credentials to your machine
And a pre-deployed Webiny project to AWS (Check this guide to learn how)

We’ll skip the Webiny app installation and deployment process in this article. So if you don’t have an up and running Webiny project yet, be sure to follow this installation and deployment guide.

Step-by-Step: How To Build a Custom CMS Model Field Type

Let’s say we have an e-commerce store selling mainly wrist watches. The products in this store are grouped according to their watch type, namely:

Mechanical Watch
Quartz Watch
Digital Watch
Smart Watch
and Hybrid

The content model needed for our PDP (Product Detail Page) requires an enumeration field type to select which kind of wrist watch a given product is. This new enumeration field will help categorize the products in the store. Since there is no built-in content model field in Webiny for our use case, we need to create a new one ourselves.

So in this tutorial, we’ll build a simple dropdown menu as our new content model field type. This dropdown menu should contain all the mentioned watch types so that whenever we add a new product to the store, we can choose from the dropdown menu which category of watch it is.

And with all that said, open your Webiny project in the code editor of your choice and let’s build this dropdown menu field type!

You can check the full version of the code in this repo.

Step 1: Define a New Field Type

When building a new content model field type, you should first create a plugin that defines this new field type you’re making. In this new plugin, you’ll give your new field a name, a field type, label, description, the icon for this new field (to be rendered on the list of content model fields in the content model UI editor), and more.

To define our new field, we’ll be using the CmsEditorFieldTypePlugin.

So first, create this new directory fields/dropdown under the apps/admin/src/plugins/headlessCMS directory:

# from the root of your Webiny project:
mkdir -p apps/admin/src/plugins/headlessCMS/fields/dropdown

Then, create a new file called productCategoryFieldPlugin.tsx under this new directory you created:

touch apps/admin/src/plugins/headlessCMS/fields/dropdown/productCategoryFieldPlugin.tsx

In this new file, we’ll write the plugin to define our new content model field type using the plugin CmsEditorFieldTypePlugin. Copy the code below and paste it inside the file productCategoryFieldPlugin.tsx:

// apps/admin/src/plugins/headlessCMS/fields/dropdown/productCategoryFieldPlugin.tsx

import React from "react";
import { CmsEditorFieldTypePlugin } from "@webiny/app-headless-cms/types";

const DropdownIcon: React.FunctionComponent = () => <i>ICON</i>

const plugin: CmsEditorFieldTypePlugin = {
    type: "cms-editor-field-type",
    name: "cms-editor-field-type-product-category",
    field: {
        type: "product-category",
        label: "Product Category",
        description: "Product Category",
        icon: <DropdownIcon />,
        allowMultipleValues: false,
        allowPredefinedValues: false,
        multipleValuesLabel: "Use as a list of multiple categories",
        createField() {
            return {
                type: "product-category",
                validation: [],
                renderer: {
                    name: ""
                }
            }
        },
    }
}

export default plugin;

Before we proceed, let’s first dissect this plugin and understand what it does.

Under the field property of the CmsEditorFieldTypePlugin, we defined the properties of this new dropdown field we’re building. Here, we specified that the type of this new plugin is product-category, which we will use later to identify this new field type. We also defined its label, description, and icon. You can assign your values here if you want to. And the rest of the properties inside the field property only relates to the rules regarding this new plugin.

After defining our new field type, we need to include this in the list of content model field types of the headless CMS.

Under the directory apps/admin/src/plugins/, open the file headlessCMS.ts and import our newly created plugin, then add this plugin to the exported array:

// apps/admin/src/plugins/headlessCMS.ts

// ... rest of the imports

import richTextEditor from "./headlessCMS/richTextEditor";

// My custom plugins
import productCategoryFieldPlugin from "./headlessCMS/fields/dropdown/productCategoryFieldPlugin"; // <- import the plugin

export default [
    headlessCmsPlugins(),
    richTextEditor,
    textField,
        // ...
        objectFieldRenderer,
    productCategoryFieldPlugin // <- the product-category field plugin
];

Now it’s time to check our new custom field type in the content model UI editor.

Run this command to start a development server for your Webiny project’s admin workspace:

yarn webiny watch app/admin --env=dev

And then, create a sample content model in Webiny’s Headless CMS (just name it Product) and check out the field types list. You should be able to see the new field type named PRODUCT CATEGORY.

Step 2: Define and Build the Renderer for the New Field

Now that we defined our new field type, it’s time to build the renderer for it. The custom field’s renderer is what will be shown when you add or edit your content.

For the renderer of our product-category field type, we are going to define a dropdown menu. And to simplify things, we’ll use a third-party dependency called react-dropdown to skip the part of implementing a dropdown menu from scratch.

So with that said, open your terminal and install react-dropdown:

yarn workspace admin add react-dropdown

Take note of the workspace admin since we only want to install react-dropdown in the admin area. This is because every Webiny project is a monorepo that has several workspaces in it (including the mentioned admin workspace which we’re working on right now).

After installing the dependency, we can now define and build the renderer for product-category field.

We will be using the CmsEditorFieldRendererPlugin] to define our renderer’s properties like rendererName, description, canUse (or when should it be rendered), and most importantly, the component that will be rendered.

Under the directory apps/admin/src/plugins/headlessCMS/fields/dropdown, add another file named productCategoryFieldRendererPlugin.tsx.

touch apps/admin/src/plugins/headlessCMS/fields/dropdown/productCategoryFieldRendererPlugin.tsx

Then, write the renderer plugin inside this file using the CmsEditorFieldRendererPlugin. Use the react-dropdown to create the dropdown component:

//apps/admin/src/plugins/headlessCMS/fields/dropdown/productCategoryFieldRendererPlugin.tsx

import React from "react";
import { CmsEditorFieldRendererPlugin } from "@webiny/app-headless-cms/types";
import ReactDropdown from "react-dropdown";
import "react-dropdown/style.css";

export default (): CmsEditorFieldRendererPlugin => ({
    type: "cms-editor-field-renderer",
    name: "cms-editor-field-renderer-product-category",
    renderer: {
        rendererName: "product-category", // must be the same as the field type defined in CmsEditorFieldTypePlugin
        name: "Product Category",
        description: "Product Category",
        canUse({ field }) {
                        // only render this on fields with the type `product-category`
            return field.type === "product-category"; 
        },
                // the component to render for the field type `product-category`
        render({ getBind }) {
            const Bind = getBind();

                        // the product categories in the e-commerce store
            const options = [
                "Mechanical Watch",
                "Quartz Watch",
                "Digital Watch",
                "Smart Watch",
                "Hybrid"
            ];
            const defaultOption = options[0];
            return (
                <Bind>
                    {
                        bind => (
                            <ReactDropdown
                                options={options}
                                onChange={({ value }) => bind.onChange(value)}
                                value={bind.value || defaultOption}
                                placeholder="Select an option"
                            />
                        )
                    }
                </Bind>
            )
        }
    }
})

From the code above, the product-category field’s renderer was defined in the renderer property of the CmsEditorFieldRendererPlugin. The rendererName is the same with the custom field’s type, product-category, which is required in order to associate the renderer to its corresponding field type. The canUse property indicates that this renderer should only be used when the field type is product-category. And finally, the render property is where we defined the dropdown menu component, which will be rendered when creating or editing contents that has product-category properties in them. Also, you might have noticed that our dropdown component is nested inside that Bind component. This Bind component is hooked into a React Context and helps abstract managing the state of our field renderer's component. That's why we don't have a useState hook inside our renderer component. Instead, we pass the value from the dropdown to bind and use the onChange handler of bind to pass changed data from the component to the context object.

After you defined the renderer, import this plugin to headlessCMS.ts and add it to the exported list (next to the field type definition plugin from earlier). Remember to call this function upon adding it to the list.

// apps/admin/src/plugins/headlessCMS.ts

// ... rest of imports

import richTextEditor from "./headlessCMS/richTextEditor";

// My custom plugins
import productCategoryFieldPlugin from "./headlessCMS/fields/dropdown/productCategoryFieldPlugin";
import productCategoryFieldRendererPlugin from "./headlessCMS/fields/dropdown/productCategoryFieldRendererPlugin" // <- import the renderer plugin

export default [
    headlessCmsPlugins(),
    richTextEditor,
    textField,
        // ...
        objectFieldRenderer,
    productCategoryFieldPlugin,
        productCategoryFieldRendererPlugin() // <- the product-category field renderer plugin
];

Now that you added this field renderer plugin, you can preview it in the content model UI editor and check the new dropdown field type we just defined:

Step 3: Define the Field in the GraphQL API

After you defined the new field type and its renderer, it’s time to define this new field in the GraphQL API. For this, we’ll need to use the CmsModelFieldToGraphQLPlugin to define our product-category field type on the GraphQL API to handle all incoming requests from this field type.

Since we will be working on the API layer, we’ll leave the admin area for now and switch to the Headless CMS API workspace.

First off, add the directory fields/dropdown under the directory apps/api/headlessCMS/src/.

# from the root of your Webiny project:
mkdir -p apps/api/headlessCMS/src/fields/dropdown

Then, create the file named productCategoryFieldPlugin.ts under the directory you just created:

touch apps/api/headlessCMS/src/fields/dropdown/productCategoryFieldPlugin.ts

Inside the file productCategoryFieldPlugin.ts, define the product-category field type to GraphQL:

// apps/api/headlessCMS/src/fields/dropdown/productCategoryFieldPlugin.ts

import { CmsModelFieldToGraphQLPlugin } from "@webiny/api-headless-cms/types";

const plugin: CmsModelFieldToGraphQLPlugin = {
    name: "cms-model-field-to-graphql-product-category",
    type: "cms-model-field-to-graphql",
    fieldType: "product-category", // <- Must be the same as the field type defined in CmsEditorFieldTypePlugin
    isSortable: true,
    isSearchable: true,
    read: {
        createTypeField({ field }) {
            if (field.multipleValues) {
                return `${field.fieldId}: [String]`;
            }
            return `${field.fieldId}: String`
        },
        createGetFilters({ field }) {
            return `${field.fieldId}: String`
        },
        createListFilters({ field }) {
            return `
                ${field.fieldId}: String
                ${field.fieldId}_not: String
                ${field.fieldId}_in: [String]
                ${field.fieldId}_not_in: [String]
                ${field.fieldId}_contains: String
                ${field.fieldId}_not_contains: String
            `
        }
    },
    manage: {
        createListFilters({ field }) {
            return `
                ${field.fieldId}: String
                ${field.fieldId}_not: String
                ${field.fieldId}_in: [String]
                ${field.fieldId}_not_in: [String]
                ${field.fieldId}_contains: String
                ${field.fieldId}_not_contains: String
            `
        },
        createTypeField({ field }) {
            if (field.multipleValues) {
                return `${field.fieldId}: [String]`;
            }
            return `${field.fieldId}: String`
        },
        createInputField({ field }) {
            if (field.multipleValues) {
                return `${field.fieldId}: [String]`;
            }
            return `${field.fieldId}: String`
        }
    }
}

export default plugin;

In here, we defined the fieldType as product-category because the fieldType in this plugin must match the field’s type we defined in CmsEditorFieldTypePlugin. That way, Webiny knows this specific plugin is for the product-category field type.

The properties isSearchable and isSortable are set to true since we want this field to be searchable and sortable via the GraphQL API.

In the read property, we defined the field type for product-category in the Read API through createTypeField, as well as some filters. Similarly in the manage property, we defined the field type of product-category in the Manage API through the createTypeField. We also defined the input GraphQL field type through createInputField, as well as a filter.

Now that this plugin is defined, we can now import this to the apps/api/headlessCMS/src/index.ts file and add the productCategoryFieldPlugin plugin to the plugins used by the Headless CMS API.

// apps/api/headlessCMS/src/index.ts

// ... the rest of the imports

import scaffoldsPlugins from "./plugins/scaffolds";

// My custom plugins
import productCategoryFieldPlugin from "./fields/dropdown/productCategoryFieldPlugin"; // <- import the GraphQL plugin for the product-category field

// ...

export const handler = createHandler({
    plugins: [
        createWcpContext(),
                // ...
                scaffoldsPlugins(),
        productCategoryFieldPlugin // <- add here the field to GraphQL plugin of the product-category field
    ],
    http: { debug }
});

And finally, deploy the changes in the API and run the dev environment of your Headless CMS API using this command:

yarn webiny watch apps/api/headlessCMS --env=dev

If everything worked as expected, you should now be able to save your content model (that has the product-category field type) and create new product entries using this new custom field. We will do all these in the next and final step of this tutorial.

Step 4: Testing the New Field

For the final step, we will test our new custom product-category plugin by making a simple content model for the PDP (Product Detail Page) of our products, create entries or product page contents using the PDP content model, and finally, query the Headless CMS API for the product content entries. And if our custom plugin works properly, we should be able to use it on the PDP content model, use the dropdown menu to categorize the product entries, and get the product category when querying the products through the Headless CMS API.

So to begin with, first go to Webiny’s Headless CMS and create a new content model (or use the Product model from earlier) for our PDPs. You can use the following fields in your content model:

Text - For the product name. Set it as the Title
Product Category - Our custom field type. Used for categorizing the watches on the store.
File - This is where we’ll put the product images. Set it to accept multiple values and to only accept image files.
Number - For the price of the product
Rich Text - For the product description

Your Product content model, including our very own product-category field, should look something like this:

Save this content model, and create a new product entry for the Products content model. For this example, I’ll add a mechanical watch and set the category using the dropdown menu we created earlier to Mechanical Watch. When querying the products lists, we expect that the value we get for this product is Mechanical Watch.

Save and publish this product entry. Make sure you press the orange button from the top-right that says Save & Publish and then click Confirm so that we can query it from the Read API.

If everything works well, you should be able to publish your first product content entry with the custom field type we created! Feel free to add as many product entries as you want.

And now, for the final test, we will query the Headless CMS API for all our product entries. Make sure you’re on the Read API’s tab, or that your API endpoint is cms/read/{locale}. You can also query the product entries in the Preview API, but since we already have a published content entry, we can use the Read API instead.

Now, remove the pre-populated query and replace it with our products list query:

{
  listProducts {
    data {
      productName
      productCategory
      productPrice
      productImages
      productDescription

    }
  }
}

Finally, hit the play button to run the GraphQL query. And if our implementation works flawlessly and as expected, we should be able to retrieve the data we entered on the product content entries. Most importantly, we’ll see the value of the product-category obtained from our custom product-category dropdown field type!

And there you have it!

You just created your own custom content model field type in Webiny’s Headless CMS. Feel free to play around and experiment with this new custom field type, or better yet, create your own field and use your imagination to build the field type you want.

Conclusion

In this article, you learned how you can extend Webiny’s built-in features through plugins. You learned the different built-in plugins in Webiny for creating custom field types in Webiny’s Headless CMS, how to use these plugins, and how to define the field’s type, renderer, and field to GraphQL plugins to create the custom content model field type. We made a simple dropdown menu for our hypothetical e-commerce store to help categorize products. We also tested our custom field type by creating a content model with the dropdown menu, creating content entries using this field type, and querying the results in the API Playground.

Webiny’s composable architecture allows you to have full control and freedom over your Headless CMS platform. Webiny’s plugins power most of its built-in features, and plugins are also what you need when you’re extending Webiny’s functionalities. With the world of technology rapidly changing year-over-year, having a dynamic and easy to scale Headless CMS platform like Webiny is crucial to the success of your business. If you want to have more freedom and control over your Headless CMS platform (and your software and data in general) be sure to check out Webiny and build your next website with them.

What is Unit Testing? How to Perform Unit Tests in Rust

Menard Maranan — Thu, 28 Jul 2022 05:12:00 +0000

Testing is an essential part of Software Development. Testing your code ensures that the software you develop works as expected and makes it less vulnerable to attackers.

Software testing is a very broad topic. That's why in the software industry, there are separate professionals who specialize in just QA and testing alone. These professionals are often referred to as QA Engineers.

Although QA is its own thing, that doesn't mean developers don't do testing at all.

The most common tests that developers conduct are Unit Tests. Unit testing is a type of testing where you test small units of code (like functions) – hence the term, Unit Testing. You often do this by comparing the expected behavior of a unit of code against its actual behavior.

Unit testing is such an integral part of the development workflow that some companies' whole development culture is centered around what's called Test-Driven Development (or TDD).

In TDD, developers first write test cases (from the feature requirements, often called the user story) and proceed to write the code that satisfies them. TDD shines mostly in projects where requirements are highly specific.

You can implement unit testing in different ways across different programming languages. But at its core, Unit Testing is just about comparing the expected vs the actual behavior of the code.

So regardless of how it's implemented in a particular language, the same principle generally applies when you work in any other language.

In this tutorial, you'll learn unit testing in the Rust programming language. That said, you should know at least the basics of programming in Rust although you don't need advanced knowledge of it.

This article will cover:

How unit testing works in Rust
How to write a unit test in Rust
How to test a function
Why failing tests are useful
How to handle expected error behavior so that your tests won't fail

So, with all that said, let's proceed to learn unit testing with Rust!

How Unit Testing Works in Rust

Rust is built with code safety at its core. Rust's strict type annotation rules help eliminate a ton of bugs early on in the development phase. But still, it's not foolproof.

Like any other language, the business logic is on your shoulders and you have to help Rust understand what's acceptable in your code and what's not.

And yes, that's why we do testing.

You don't need to install a test suite to get started testing in Rust since it has built-in support for testing.

To get started, create a new cargo project (take note of the --lib flag) on your local machine and open it in the text editor or IDE of your choice. For this tutorial, I'll be using VS code.

cargo new --lib rust_unit_testing
code rust_unit_testing

Then, open the src/lib.rs file. This is where we'll spend the most time in this tutorial.

In a newly created library project in Rust, you'll notice that the lib.rs file is already pre-populated by a sample test code by default.

The main purpose of this is for you to have a template to begin with when writing your tests. We'll dissect each part of this simple test and understand the basic testing concepts in Rust.

So first, let's understand what those lines of test code are doing. In this example, you'll see a test module defined in lib.rs with one test inside it which tests if 2 + 2 is equal to 4.

If you don't know the concept of modules and attributes in Rust yet, that's fine and you can ignore them for now.

But just to give you an idea, tests in Rust are written inside the tests module (the mod tests part says it's the tests module), and anything written inside this module tells cargo to run them only during testing (and that's essentially what the #[cfg(test)] attribute implies).

A test in Rust is essentially just a function annotated as a test. From the example above, you'll notice the #[test] attribute above the function it_works. This simply tells cargo that this function is a test, and should be invoked during testing.

Inside the it_works test function, it checks if the value of result derived from 2 + 2 is equal to 4. It performs the checking using the assert_eq! macro. The assert_eq! macro compares the equality (==) of the left and right values passed onto it.

In most programming languages, there's a rule that the left values passed to the assert should be the expected values, while the actual value should be in the right. With Rust, there are no hard rules for that and you can pass on either side the expected and actual results.

Now, try running your test using this command:

cargo test

Here's what the result should look like for the example above:

By running cargo test, cargo will execute your test cases and output the report in your terminal. From that report, you'll see the tests run by cargo.

The first line in the report says running 1 test since we only have one test function tests::it_works. Alongside the tested function, you'll see the message ok, meaning, the test passed.

You can also see the summary of the results below that:

1 passed
0 failed
0 ignored
0 measured
0 filtered out
and the status of the result that says test result: ok

The 1 passed counter here represents that one test function (tests::it_works) that passed the test, while the failed counter tells how many failing tests we have. The same applies to the other counters as well.

You'll also see the results of the Doc-tests below. Since we don't have any doc tests here, you'll see running 0 tests. You can ignore this for now and just focus on the unit tests. But if you want to learn more, you can check Rust's official documentation.

How to Write Tests in Rust

When writing a test, you generally need to go through these three steps:

Mock the data or state needed for a test case. By this, I mean providing mock or sample data needed by the code you're testing (if necessary) and/or setting up the state or environment needed for the test case to run.
Run the code that needs to be tested (passing the mock data necessary). An example is invoking a function you want to test.
Check if the actual behavior of the code you're testing matches its expected behavior. For example, by passing an argument x to a function, you assert if its returned value is the same as what you're expecting for it to return. Or check if a unit of code raises panic!—which is the expected behavior, for example—if it's given a certain parameter.

In Rust, unit tests are written in the exact file where the code being tested is written. Test functions are then grouped inside the tests module (which is named this way by convention).

How to test functions in Rust

Now let's proceed to testing functions in Rust.

To begin with, we need a simple function to test. But first, remove the it_works test function since we no longer need it. Then, write this adder function above the tests module:

// src/lib.rs

pub fn adder(x: i32, y: i32) -> i32 {
    x + y
}

#[cfg(test)]
mod tests {
// ...

The adder function from above is a simple public function that just adds two numbers and returns the sum. To test if it works as expected, let's write a unit test for this function.

From the three steps of writing unit tests we discussed earlier, the first two steps are:

set the data for the code to be tested
run the code.

So going back to the tests module, first, bring the adder function into its scope (using the use keyword). Then write a function named it_adds annotated with the #[test] attribute.

// src/lib.rs

pub fn adder (x: i32, y: i32) -> i32 {
    x + y
}

#[cfg(test)]
mod tests {
    // this brings everything from parent's scope into this scope
    use super::*;

    #[test]
    fn it_adds() {
    }
}

Inside the it_adds test function is where we'll write the tests. So within it, declare a variable named sum, then call the function adder and pass 4 and 5 as its parameters (which are our mock data).

// src/lib.rs

// --snip--

    #[test]
    fn it_adds() {
        let sum = adder(4, 5);
    }
}

And finally, the third step in writing unit tests is to check the expected vs actual behavior of the code we're testing.

So here, let's assert if the value of sum as returned by the adder function is equal to 9 (which is our expected return value) using the assert_eq! macro.

// src/lib.rs

// --snip--

    #[test]
    fn it_adds() {
        let sum = adder(4, 5);
        assert_eq!(sum, 9);
    }
}

Here's the final version of our code and test in the lib.rs file:

// src/lib.rs

pub fn adder(x: i32, y: i32) -> i32 {
    x + y
}

#[cfg(test)]
mod tests {
    // this brings everything from parent's scope into this scope
    use super::*;

    #[test]
    fn it_adds() {
        let sum = adder(4, 5);
        assert_eq!(sum, 9);
    }
}

As you learned earlier, you can run this test using this command:

cargo test

If everything works well, we should get test result: ok stating that our tests passed.

You can add more tests in the tests module for the adder function if you like (for example, adding negative numbers). Or better yet, create your own function and write a test (or tests) for it.

Moreover, there are a lot more built-in assertion macros in Rust that you can use besides the assert_eq! macro. Some of those include the assert_ne! macro for asserting not equal values (!=), and the assert! macro which just asserts if the code you're testing returns a true value.

If you need more assertion macros (for example, comparison assertions that support >, <, >=, <=), you can install external crates like this one: claim. You can check claim's documentation here for more info.

Why Failing Tests Are Useful

So far we're always getting passing results on our tests.

Although it's good, the true power of unit tests comes from catching errors or bugs in our code and reporting them through failing tests. So for this time, let's intentionally write a 'buggy' code and see what happens.

Back in the lib.rs file, modify the adder function by replacing the + operator with -.

// src/lib.rs

pub fn adder(x: i32, y: i32) -> i32 {
    // change the operator from '+' to '-'
    x - y
}

// --snip--

Now run the tests again using cargo test. And as expected, you should see a failing test result like this:

First off, notice that the status of the test function tests::it_adds is a big red FAILED. This is what failing tests with cargo look like.

Below that, you'll see the 'failures' report which lists out the failing tests and some information as to why they failed.

From our example, the tests::it_adds test failed and as the report said, the left and right values passed into the assert_eq! macro aren't equal (==).

That's because the left value is -1 while the right value is 9. Remember that on our assert_eq! assertion, the left value that we passed to it is the sum variable that contains the return value of adder(4, 5).

Since our operator is wrong, the adder function performs 4 - 5 instead of the expected 4 + 5. That's why instead of the expected value of 9, we got -1. Cargo noticed this so it raised a failing test.

Below the failed tests report is its summary (sort of), still under the failures category, but just lists out the names of the test functions that failed.

And lastly, the entire summary of the overall test:

Status is: test result: FAILED
0 passed
1 failed
0 ignored
0 measured
0 filtered out

This time, our failed counter is 1 (referring to our failed test function) while passed is 0.

How to Handle Expected Errors

From the previous section, you learned that errors cause tests to fail.

But what if you are expecting the code you're testing to fail (like for example, by giving it an invalid parameter). If it gets an error, cargo will flag this as a failing test even though you're actually expecting it to fail.

Can you expect failing behaviors?

The short answer is: yes, you can!

To demonstrate this, let's go back to the lib.rs file and modify our adder function. This time, let's set a rule for it to only accept single-digit integers (positive, zero, and negative) – otherwise, it should 'panic'. And for readability purposes, let's rename our adder function to single_digit_adder.

// src/lib.rs

// modify the `adder` function from earlier
// and turn it into `single_digit_adder`
pub fn single_digit_adder(x: i8, y: i8) -> i8 {
    fn is_single_digit(x: i8) -> bool {
        x < 10 && x > -10
    }

    if !(is_single_digit(x)) || !(is_single_digit(y)) {
        panic!("Only single digit integers are allowed!");
    } else {
        x + y
    }
}

#[cfg(test)]
mod tests {
// --snip--

Since we're expecting the single_digit_adder function to 'panic' whenever it receives a non-single digit integer, we need to specify that on the test function that's responsible for testing exactly this behavior.

To do that, we need to add another attribute to one of our test functions. And that is the #[should_panic] attribute.

Going back to the tests module, first, edit the it_adds test function by renaming the adder function call into single_digit_adder.

Then, create a new test function named it_should_only_accept_single_digits with both the #[test] and the #[should_panic] attribute.

Inside this new test function, call the single_digit_adder function with an invalid parameter (11) in this case.

// src/lib.rs

pub fn single_digit_adder(x: i8, y: i8) -> i8 {
    // ...
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn it_adds() {
        let sum = single_digit_adder(2, 3);
        assert_eq!(sum, 5);
    }

    // our new test function that expects `panic!` with invalid param
    #[test]
    #[should_panic]
    fn it_should_only_accept_single_digits() {
        single_digit_adder(11, 4);
    }
}

You don't need any assert macros in the it_should_only_accept_single_digits test function since we just need single_digit_adder to 'panic'. So simply calling the function is enough.

By giving it an invalid parameter (11, which isn't a single digit), we're expecting it to 'panic'. The #[should_panic] attribute will then expect that something should panic inside the it_should_only_accept_single_digits test function. If it didn't catch any panic, this test will fail. It will only pass if single_digit_adder panics.

So to test if it really works, try commenting the #[should_panic] attribute first and then run cargo test. You should expect it to fail.

Now, uncomment the #[should_panic] attribute and re-run the test. Your tests should all pass as expected:

Notice that on the test tests::it_should_only_accept_single_digits, there's a should panic alongside it, and that it passed the test. This means that this test function caught a panic as expected.

And there you have it! You just learned what unit testing is and how to perform unit tests with the Rust programming language. Feel free to write your own tests using the knowledge you obtained from this article and use it in your future projects.

Conclusion

In this article, you learned what unit testing is and its importance in the software development process. You also learned how to write unit tests through the simple three steps process and actually perform testing in the Rust programming language.

We covered the structure of a test module in Rust and how to construct a test function, and then we wrote a simple Rust program and some test cases for it. We also covered failing tests and how to handle an expected failing behavior in the unit of code.

Testing is an important part of the software development process. Testing your code helps ensure that the software works as expected. As a developer, it's important that you test your code to ensure the quality of the software you're shipping and that those silly bugs don't reach the end-user!

REPL-like environment for Rust (A Rust Playground Locally)

Menard Maranan — Sat, 16 Jul 2022 22:40:00 +0000

TL;DR: I made a simple REPL-like environment program (similar to Python's REPL or interactive interpreter) for Rust. In a sense, it's a Rust Playground, but locally, right through your terminal, so you can play along some Rust code without creating a new file and compiling it.

Repo Link is here: https://github.com/menard-codes/rust_playground_locally (also, read the caution at the end of this blogpost)

Check the short demo video below to see it in action.

So I'm currently learning Rust.

As per my background, this is my first low-level language, and I'm still getting used to compiling my code. Coming from interpreted languages such as Python, I kinda miss the REPL (as it always come in handy when testing small pieces of code).

And for a language like Rust, the closest thing is to use the Rust playground.

I admit, I'm a lazy dev. It's sometimes annoying to constantly open a browser, create a new tab, and search 'rust playground' just to test a small piece of code. Comparing it to Python's REPL which is more straightforward, I can just open the terminal and do my thing there.

So I thought of making something similar for Rust, a REPL-like environment to run Rust code without the need to create a new file and compile it, all done right through the terminal.

So I just did that.

And to give you an idea, here's what it looks like:

So how did I made this?

First off, I wondered around the Rust Playground.

I tried running a simple hello world program, and opened the dev tools and checked the networks tab to see what's what. From there, I noticed that the playground sends the code from the playground to an API which executes it.

Then I thought if I can send my own request to that API and make it execute my code, then I can work on my idea around this. So I pulled out the API URL and the structure of the request payload, dropped them off into my Python script, wrote a sample Rust code, and tried sending it to this code execution API to see if it will work.

As you might probably guess, it worked.

"Gotcha!" I said.

So then I preceded to write this stupidly simple program that looks like Python's REPL, wherein it takes the user's raw code input and sends it directly to that API to execute the Rust code for us, then print the stdout or stderr that's returned by the API (if any).

Now, instead of opening the Rust playground, I can just pull out my terminal and run pieces of Rust code; without the need to create a new file and compiling it.

And since I'm pretty much satisfied (at least) with it, I thought why not share it to everybody else. There might be someone out there who also came from a background like me, and who used to have (and love) REPL or the interactive environment of their languages to test out some pieces of code.

So I decided to share it with the dev community.

You can check the repo of this stupid simple program I made here: https://github.com/menard-codes/rust_playground_locally

A little word of caution. I haven't tested this thing out, thus, there are potentially a number of edge-cases (as well as bugs) that'll make this not work properly.