DEV Community: richardevcom

Great article that dives deep into comparing how macOS, Linux, and Windows report file changes and provides a practical, reusable pipeline—normalization, debouncing, batching, and filtering—for building reliable cross‑platform file‑watching tools.

richardevcom — Thu, 13 Nov 2025 07:27:53 +0000

Asoseil

Nov 12 '25

How macOS, Linux, and Windows detect file changes (and why it's hard to catch them)

#go #testing #development #programming

Comments 7

3 min read

I had to vent somewhere about how insanely inconvenient Simbase API is. So I wrote this a while ago and recently decided to finally publish it. Simbase? More like Simmaze - one sim at a time.. literally. 🤦‍♂️

richardevcom — Tue, 08 Jul 2025 20:37:59 +0000

richardevcom

Jul 8 '25

Simbase API maze and how to avoid it

#api #sim #debugging #iot

Comments

6 min read

Simbase API maze and how to avoid it

richardevcom — Tue, 08 Jul 2025 12:00:00 +0000

A few months ago, our client decided to use Simbase for managing custom SIM cards in OBD devices. Little did I know I was about to dive headfirst into a debugging nightmare.

Too lazy to read it all? This post is mostly a rant - feel free to skip ahead to
👉 Epilogue: Why I'll Never Use Simbase Again.

Issue #1 - Inefficient data retrieval

At first, everything looked fine - API permissions were set up, IP whitelisting in place, and even webhook triggers (though they never fired as promised). Managing hundreds of SIM cards through their API seemed straightforward, so I thought, "I'll figure it out as I go."

Then reality hit. I discovered a major flaw: zero granular filtering. Our SIMs live in OBD devices and are tracked by IMEI. Need to fetch a SIM by IMEI? Forget it - you can only fetch by ICCID. That means pulling every single SIM and hunting for one needle in a haystack. I expected a direct lookup; instead, I got endless paginated requests. Multiply that by 100+ clients, and you're guaranteed to hit those absurd rate limits. Uff! 🤦‍♂️

The "Solution"

I had no choice but to fetch, cache, and store all SIMs locally - and keep everything in sync. This extra layer was a ticking time bomb for our production environment.

import axios from 'axios';
import { getLocalSims, saveLocalSims } from './localDatabase';

interface SimCard {
  iccid: string;
  imei: string;
  // ... other fields
}

interface SimcardsResponse {
  simcards: SimCard[];
  cursor: string | null;
}

export async function getSyncedSims(): Promise<SimCard[]> {
  const allSims: SimCard[] = [];
  let cursor: string | null = null;

  // keep pulling pages until cursor is null
  do {
    const { data } = await axios.get<SimcardsResponse>(
      'https://api.simbase.com/v2/simcards',
      {
        headers: { Authorization: 'Bearer YOUR_SECRET_TOKEN' },
        params: { cursor },
      }
    );
    allSims.push(...data.simcards);
    cursor = data.cursor;
  } while (cursor);

  await saveLocalSims(allSims);
  return allSims;
}

export async function getSyncedSimByImei(
  imei: string
): Promise<SimCard | undefined> {
  const sims = await getSyncedSims();
  return sims.find(sim => sim.imei === imei);
}

Issue #2: Absurd rate limits

By the time I built our local SIM-management layer, I quickly ran into ridiculous Simbase's limits:

10 calls per second;
5,000 calls per day;

Juggling data for 100+ (expected therefor simulated) clients, every extra API call felt like pouring gasoline on a fire. 🤯

Syncing hundreds of SIMs? Torture. The only workaround was a homemade throttle + batch scheduler - more code, more delays, more potential headaches.

The "Solution"

I wrapped my fetch in a tiny rate-limiter class and batched the updates. It's not pretty, but at least we don't smash the API - or our sanity.

// ...

const delay = (ms: number) => new Promise(res => setTimeout(res, ms));

class RateLimiter {
  private calls = 0;
  private windowStart = Date.now();

  constructor(private limit = 10, private windowMs = 1000) {}

  async throttle() {
    const now = Date.now();

    if (now - this.windowStart >= this.windowMs) {
      this.windowStart = now;
      this.calls = 0;
    }

    if (this.calls >= this.limit) {
      await delay(this.windowMs - (now - this.windowStart));
      this.windowStart = Date.now();
      this.calls = 0;
    }

    this.calls++;
  }
}

export async function getSyncedSims(): Promise<SimCard[]> {
  const limiter = new RateLimiter(10, 1000); // 10 calls/sec
  const allSims: SimCard[] = [];
  let cursor: string | null = null;

  do {
    await limiter.throttle();

    const { data } = await axios.get<SimcardsResponse>(
      'https://api.simbase.com/v2/simcards',
      {
        headers: { Authorization: 'Bearer YOUR_SECRET_TOKEN' },
        params: { cursor },
      }
    );

    allSims.push(...data.simcards);
    cursor = data.cursor;
  } while (cursor);

  await saveLocalSims(allSims);
  return allSims;
}

// ...

Issue #3 - Inconsistent field naming

Next up - small but annoying inconvenience - inconsistent field names. Some endpoints return cost as current_month_cost; others use current_month_costs. It's like the dev team flipped a coin every time-so you end up adding boilerplate just to keep your code sane.

The "Solution"

I wrote a tiny (unnecessary) normalizer that standardizes both variants into one cost property. No more guessing which field you'll get.

export function normalizeSimCard(sim: SimCardRaw): SimCardNormalized {
  return {
    iccid: sim.iccid,
    imei: sim.imei,
    cost: sim.current_month_cost || sim.current_month_costs || "0",
    // ... normalize other fields as needed
  };
}

Issue #4 - Sparse error messaging

Debugging became painful when the API started returning vague responses. One wrong call returned a vague 429 error and left me thinking: "Was it the per-second cap or the daily limit?" The message didn't say.

The "Solution"

I wrapped every request in a helper that logs the error, reads retry_after, and automatically retries-or bails if I've truly hit the daily ceiling. With this in place, every 429 comes with clear context and an automatic pause - no more head-scratching over "Which limit did I hit?"

// ...
const delay = (ms: number) => new Promise(res => setTimeout(res, ms));

/**
 * Fetch with built-in retry for 429 errors.
 * Logs context, waits the suggested time, and retries once.
 */
export async function fetchWithRetry<T>(
  url: string,
  options: Record<string, any> = {}
): Promise<T> {
  try {
    const { data } = await axios.get<T>(url, options);
    return data;
  } catch (err) {
    if (axios.isAxiosError(err) && err.response) {
      const { status, data } = err.response as { status: number; data: any };
      console.error(`Error ${status}:`, data.message || err.message);

      if (status === 429) {
        const waitSec = typeof data.retry_after === 'number' ? data.retry_after : 10;
        if (waitSec >= 86400) {
          console.error('Daily rate limit hit-stopping retries for today.');
          throw err;
        }
        console.log(`Rate limit hit. Waiting ${waitSec}s before retrying…`);
        await delay(waitSec * 1000);
        return fetchWithRetry(url, options);
      }
    }
    throw err; // non-retryable or non-Axios error
  }
}

// ...

Issue #5 - Bulk operations

I finally had a basic API client working and decided to add bulk CRUD operations. In unit tests, it felt like playing Russian roulette - one failed SIM, and the whole batch imploded. What should have been a single call turned into a spaghetti of errors and wasted time.

The "Solution"

Use a "bulk-first" strategy with recursive split-on-failure. Try registering all SIMs at once. If it fails, split the list in half, retry each half, and keep recursing until only the bad record is isolated. That way, most SIMs sail through in efficient bulk calls, and only the failed ones get singled out - no need to fall back to one-by-one for every SIM.

// ...

interface BulkSim {
  iccid: string;
  // ... other fields
}

async function registerBulk(sims: BulkSim[]): Promise<void> {
  await axios.post('https://api.simbase.com/v2/simcards/register', sims, {
    headers: { Authorization: `Bearer ${'YOUR_SECRET_TOKEN'}` },
  });
  console.log(`✔️ Registered ${sims.length} SIMs in bulk`);
}

export async function safeBulkRegister(sims: BulkSim[]): Promise<void> {
  try {
    await registerBulk(sims);
  } catch (err: any) {
    if (sims.length === 1) {
      console.error(
        `❌ SIM ${sims[0].iccid} failed:`,
        err.response?.data?.message || err.message
      );
      return;
    }
    const mid = Math.floor(sims.length / 2);
    await safeBulkRegister(sims.slice(0, mid));
    await safeBulkRegister(sims.slice(mid));
  }
}

// ...

Issue #6 - Flaky webhook callbacks

Simbase promised real-time updates via webhooks; in practice these callbacks were as reliable as a paper umbrella in a storm - irregular, delayed, or vanishing into thin air. 🤷‍♂️ Without guarantees, you'll miss critical events and have no clue why.

The "Solution"

Add a polling fallback that only fetches new events. Use a since cursor (timestamp or event ID) so each poll grabs just what you haven't seen. Webhooks do the heavy lifting when they arrive; polling picks up anything they miss.

interface SimEvent {
  id: string;
  timestamp: string;
  type: string;
  payload: any;
}

interface EventsResponse {
  events: SimEvent[];
}

const POLL_INTERVAL = 5 * 60 * 1000; // 5 minutes

async function pollEvents(lastTimestamp: string | null): Promise<string | null> {
  try {
    const params = lastTimestamp ? { since: lastTimestamp } : {};
    const { data } = await axios.get<EventsResponse>('https://api.simbase.com/v2/events', {
      headers: { Authorization: `Bearer ${'YOUR_SECRET_TOKEN'}` },
      params,
    });

    if (data.events.length) {
      console.log('✔️ Polled events:', data.events);
      // Return the newest event timestamp for next poll
      return data.events[data.events.length - 1].timestamp;
    }
  } catch (err: any) {
    console.error('Polling error:', err.response?.data?.message || err.message);
  }
  return lastTimestamp;
}

// Kick off polling
let lastTs: string | null = null;
(async () => {
  lastTs = await pollEvents(lastTs);
  setInterval(async () => {
    lastTs = await pollEvents(lastTs);
  }, POLL_INTERVAL);
})();

Additional inconvenience - Outdated documentation & glacial support

The official Simbase docs feel like relics from the API Stone Age - packed with abstract examples, missing endpoints, and inconsistent field names. I was lucky enough to start on v2, but if you've ever been stuck with v1, you'll know it's like navigating a maze.
When you finally need help - a quick rate-limit bump or clarification on a disappearing webhook event callback - their support won't help you. My first email - ghosted, and the one follow-up reply to client e-mail took another week to arrive.

Epilogue: Why I'll Never Use Simbase API Again

After getting lost in Simbase's maze, I learned that peace of mind beats their inconvenient API features. Here's why this turned into a nonstop debugging nightmare:

Inefficient data retrieval: No proper filters. Need a SIM by IMEI? - You pull every SIM by ICCID and hunt it down yourself;
Absurd rate limits: 10 calls/sec, 5000 calls/day - constant throttling hacks and extra code to cope;
Inconsistent field naming: current_month_cost here, current_month_costs there - pick one, please;
Sparse error messaging: Vague codes forced me to build custom error handlers and retry loops;
Bulk operations gone wild: One bad SIM sinks the entire batch;
Flaky webhook callbacks: Promised live updates that almost never arrive without a polling backup;
Outdated Documentation & Slow Support: Documentation that's more confusing than helpful, paired with glacial support.

I wish we had chosen a better alternative at the time, but this was my first - and last - SIM management project with them.

In the end, this is more than a rant - it's a cautionary tale. Save yourself the trouble, skip the endless maze, and steer clear of Simbase.

Thanks for reading this far and happy coding! 🙏

WordPress development environment with Docker

richardevcom — Fri, 09 Aug 2024 12:23:09 +0000

We built a WordPress site for a client ages ago. Fast forward to today, and we're tasked with a much-needed update. The old process? Let's just say it was about as fun as watching paint dry. I realized the painfully slow workflow was a major pain compared to modern development standards. I knew I had to create somewhat automated development environment.. and I chose to do that using Docker.

Setting up WordPress with Docker means you can avoid the hassle of setting up set of server-side software for web applications. Even though Docker isn't made specifically for WordPress, the setup is rather simple. In this guide, we'll look at how to setup WordPress development environment using Docker.

Before you start

Make sure you have Docker installed. You can quickly get started with Docker here.
⚠️ If you're running Linux - you'll also need to manually setup Docker Compose.

Project tree

To keep things lean, we'll avoid loading the entire WordPress source code into a shared volume. This can be a real resource hog! Instead, we'll focus on sharing just the wp-content/ folder. Let's break down the project structure:

wp-dev/
├─ wp-content/
├─ composer.yml
├─ dump.sql (optional)

Go ahead and create the project tree like one above.

⚡ If you have an existing WordPress project that you want to import (like I did), simply copy your wp-content/ folder and database dump file into the project's root directory.

Configuration

Here is the compose.yml configuration file for Docker Compose:

version: "3.6"
services:
  wordpress:
    image: wordpress:latest
    container_name: wordpress
    volumes:
      - ./wp-content:/var/www/html/wp-content
    environment:
      - WORDPRESS_DB_NAME=wordpress
      - WORDPRESS_TABLE_PREFIX=wp_
      - WORDPRESS_DB_HOST=db
      - WORDPRESS_DB_USER=root
      - WORDPRESS_DB_PASSWORD=password
    depends_on:
      - db
      - phpmyadmin
    restart: always
    ports:
      - 8080:80

  db:
    image: mariadb:latest
    container_name: db
    volumes:
      - db_data:/var/lib/mysql
      # This is optional!!!
      - ./dump.sql:/docker-entrypoint-initdb.d/dump.sql
      # # #
    environment:
      - MYSQL_ROOT_PASSWORD=password
      - MYSQL_USER=root
      - MYSQL_PASSWORD=password
      - MYSQL_DATABASE=wordpress
    restart: always

  phpmyadmin:
    depends_on:
      - db
    image: phpmyadmin/phpmyadmin:latest
    container_name: phpmyadmin
    restart: always
    ports:
      - 8180:80
    environment:
      PMA_HOST: db
      MYSQL_ROOT_PASSWORD: password

volumes:
  db_data:

This is a standard configuration file to create a WordPress development environment. However, I've made a couple of adjustments to tailor it to our specific needs:

volumes: - ./wp-content:/var/www/html/wp-content: this line syncs your local wp-content/ folder with the container's wp-content/ directory, allowing you to make changes locally and see them reflected in the container.
./dump.sql:/docker-entrypoint-initdb.d/dump.sql: will automatically import your database dump file after MySQL server is installed.

Running it

👏 You're almost there! With your compose.yml file in place, it's time to bring your development environment to life.

Open your terminal and navigate to your project directory. Then, run the magic command:

docker-compose up -d

⚡ This command will create and start all the containers defined in your compose.yml file in detached mode, meaning they'll run in the background without interrupting your terminal session.

Quick fix file permissions

Before we dive into your new WordPress development environment, there's one small adjustment to make. Docker has specific rules about file permissions, and the WordPress image is set up in a particular way. To ensure you can easily edit your WordPress files from outside the container, you'll need to change the ownership of the wp-content/ directory.
Open your terminal and run the following command, replacing {your-username} with your actual username:

sudo chown -R {your-username}:{your-username} wp-content

⚡ This command will give you the necessary permissions to work with your WordPress files without any hassle.

Ready!

🥳 Congratulations! Your Dockerized WordPress development environment is up and running.

To access your new WordPress installation, open your web browser and navigate to localhost:8080. You'll be greeted by the familiar WordPress installation screen (if you imported an existing project source, you'll see your homepage).

Follow the on-screen instructions to complete the setup process. Once you've finished, you'll be able to log in to your WordPress admin dashboard using the credentials you created.

'memba?: Twilio & Vertex AI SMS Reminder System for Seniors who don't 'memba.

richardevcom — Mon, 24 Jun 2024 18:34:03 +0000

✨ As part of dev.to Twilio AI challange me and @isitayush crafted a digital guardian angel for seniors (not you... probably).

Here's how 'memba works:

You simply send an SMS message to a designated Twilio phone number +44 7822 021078. The message should be formatted like this: Remind me to take medicine on 24nd June 18:00.
Twilio sends SMS to our Node.js/Express.js app container.

⚡ This app is containerized using Docker Hub and run using Google Cloud Run (hail automation).
The Cloud Run application forwards the SMS content to Vertex AI (Gemini LLM), with our predefined instructions.

Functionality:Parse reminder text into JSON format.
Input:The text of the reminder and/or date, time.Output:JSON string in the format: {'reminder_text': "<text>", 'reminder_datetime': "<ISO 8601 extended format>"}.
Don't include any introduction text likt "Hello...", "Remind me to...", "Please..." in reminder_text.

Error handling:If the reminder text doesn't follow the expected format (e.g., missing date/time), return an empty JSON string {}.
If the date/time is not set or can't be parsed, return an empty JSON string {}.
If reminder_text is empty or not set, return an empty JSON string {}.
If date is set, but time is not set, use current time. If time is set, but date is not set, use current date.
Don't return the JSON string as markdown.
Do not delimit the output JSON with anything.
If reminder text contains abstract date, time meanings like "tomorrow", "next week", "next month", etc. then convert them to date, time as ISO8601 extended format - for example, "tomorrow" becomes <current_date> + 1 day or "next week" becomes <current_date> + 7 days, etc.

Vertex AI then translates the extracted information into a structured JSON format like this:

{
   "reminder_text": "take medicine",
   "reminder_datetime": "2024-06-24T18:00:00.000Z"
}

We then send the JSON out to our Cloud SQL MySQL database and store it (we chose to use Prisma in our Node.js app).
Then a background job (we also put it directly in our Node.js app) runs every minute. This job scans the database for reminders scheduled within the next minute.
For identified reminders, the job triggers an SMS notification back to the senior's phone via the Twilio API precisely at the set reminder_datetime.

Demo

Send your SMS reminder (for example, Remind me to take medicine on 24nd June 18:00) to +44 7822 021078.

⚡ We bravely topped up our Twilio account.

You can also fork our solution from here: richardevcom/memba
Check out our landing page (yeah, because why not?): 'memba?
Here is a quick demo video:

🐞 Known issues

Our LLM is smart enough to parse data, but not smart enough to determine correct timezone from phone nr. country code. Expect your reminders to have date/time offset.

⚡ Many countries have multiple timezones (did you know that France has 12 timezones? 🤯) and one phone number country code - which basically leads our solution to have date/time offsets.

Destructuring Vue.js props: The Reactivity Challenge

richardevcom — Mon, 25 Mar 2024 18:36:06 +0000

Destructuring objects is a common practice in JavaScript, and it can make your code cleaner by extracting specific properties. In Vue.js, however, destructuring props can unintentionally break reactivity.

The Pitfalls of Destructured Props

⚡ You cannot destructure defineProps because the resulting destructured variables are not reactive and will not update. Read more

When you destructure props in Vue.js, the resulting variables become plain JavaScript objects. These objects are not reactive, meaning changes to the original props won't trigger a re-render in your component. This can lead to stale data being displayed.

For example, imagine a component displaying a firstName and a lastName based on a prop. If the prop is destructured, the properties won't update when the parent component changes the prop value.

<template>
  <div>
    <p>Name: {{ firstname }} {{ lastname }}</p>
  </div>
</template>

<script setup>
import { ref } from 'vue';

// ❌ Non-reactive props - this won't re-render
const { firstName, lastName } = defineProps({
  firstName: String,
  lastName: String,
});
</script>

Keeping destructured props reactive (if necessary)

If you still really, really want to destructure props, there are two ways to maintain reactivity:

Reference your props object directly using toRefs() Vue’s toRefs function takes a reactive object (like props) and returns a new object where each property is wrapped in a ref. Accessing properties using .value (e.g., prop1.value) ensures reactivity.

⚡ Vue.js documentation advises against this approach for props, suggesting using the dot notation instead. Read more

<template>
  <div>
    <p>Name: {{ firstName }} {{ lastName }}</p>
  </div>
</template>

<script setup>
import { ref, toRefs } from 'vue';

const props = defineProps({
  firstName: String,
  lastName: String,
})

const { firstName, lastName } = toRefs(props)
</script>

Reference your props object directly using computed():

<template>
  <div>
    <p>{{ fullName }}</p>
  </div>
</template>

<script setup>
import { computed } from 'vue';
const { firstName, lastName } = defineProps({
  firstName: String,
  lastName: String
})
const fullName = computed(() => firstName + lastName)
</script>

The Bottom Line: Embrace the Dot Notation!

While destructuring can be useful for non-reactive objects, it’s generally recommended to access props directly using props.propertyName in Vue.js.

<template>
  <div>
    <p>Name: {{ props.firstname }} {{ props.lastname }}</p>
  </div>
</template>

<script setup>
import { ref } from 'vue';

// ✅ Reactive props - this will re-render
const props = defineProps({
  firstName: String,
  lastName: String,
});
</script>

This approach guarantees reactivity and avoids potential issues.

Remember, young traveler, maintaining reactivity is crucial for dynamic Vue components. Choose the approach that suits your style, but be mindful of the potential pitfalls of destructuring props.

Less is better - the pitfalls of Tech Bloat

richardevcom — Thu, 12 Oct 2023 08:54:51 +0000

⚡️Tech bloat is a term used to describe the excessive use of technologies in a software project.

It's tempting to believe that piling on more technologies is the path to success. However, the reality paints a different picture. Your tech stack, resembling an Eiffel tower, might seem impressive, but beneath the surface, it's a breeding ground for complications and inefficiencies.

Problem - Tech Bloat trend

The prevailing trend in the programming world is to stack layers of packages for even the most basic tasks. Simple components like alert modals and forms, once straightforward, are now bundled into massive packages. However, the hidden cost surfaces in the form of bloated code, longer debugging cycles, and an increasingly steep learning curve for newcomers.

Consequences of Tech Bloat

Longer Development Time: bloated packages mean longer development cycles, with debugging becoming a labyrinthine challenge.
Increased Complexity: each added layer brings complexity, making it difficult to understand the dependencies and slowing down your team.
Barriers to Collaboration: Overly complex tech stacks create barriers, hindering collaboration and making it hard for new team members to contribute meaningfully.
Simple Problems, Complex Solutions: Not every problem needs a complicated solution. Often, simplicity leads to elegant and efficient outcomes.

Solution - a call for simplicity

So, here's my very subjective advice: deflate your tech stack. Resist the allure of excess languages, frameworks, or libraries. Embrace simplicity and efficiency. Remember, the goal isn't to showcase your mastery of complex technologies but to create seamless, innovative solutions. By keeping your stack lean, you not only ease your burden but also foster a collaborative environment where ideas flow freely, unburdened by needless complexities.

Tips for Deflating Your Tech Stack

Choose the right tools. Select tools that fit the task at hand. Avoid complex frameworks for simple tasks.
Use focused libraries. Instead of using a general-purpose library, use a library that is specifically designed for the task you need to do.
Keep dependencies updated. Outdated dependencies can lead to security vulnerabilities and compatibility issues.
Remove unused dependencies. If you're not using a dependency, remove it. This will reduce the size and complexity of your project.

Conclusion

⚡️ Remember, the goal is to create a solution, not a complicated mess.

By deflating your tech stack, you can write simpler, more efficient code that is easier to maintain and extend.

Custom API server with basic CRUD — JS, Apollo, GraphQL & MongoDB

richardevcom — Mon, 16 Jan 2023 06:26:16 +0000

[...] All that was left to do for my cross-platform hybrid web app was to test it with actual content and create CRUD. First thought, obviously, was to write middleware for back-end that will communicate with database. However, I had planned on adding more features over time, so doing that on multiple platforms would be overkill. Therefore, I quickly decided on building API server, that could... well... do it all.

The most commonly used data format for transferring data to a client is JSON and for controlling it, well.. used to be REST (don't throw rocks at me just yet 😅). If you gradually increase your app's complexity as well as database, it can and will be a very resource-heavy solution in long term. Luckily for us, there are 2 much better alternatives --- GraphQL and gRPC. Even better --- there is also Node.js friendly Apollo Server (GraphQL server).

So, in this article "slash" tutorial, I'll try to dig into creating a custom API Apollo Server and as a bonus, we'll write some basic CRUD for it.

Let's dig in! 👏

Before you jump in

It goes without saying, that you'll need basic knowledge in Node.js, NPM and how to use its command-line tool. At the moment of writing this tutorial, I had the following versions set-up:

node -v
v16.16.0
npm -v
8.19.2

What about the database? I personally prefer going with good old MongoDB. If you have avoided it until now, get to know it better here, it's intuitive and fast. Oh, and we'll also use it the OOP way*,* so meet Mongoose --- it will be our "driver" for MongoDB.

⚡We'll be running our MongoDB server on Docker. Read --- how to install MongoDB on Docker. Alternatively, you can use MongoDB Atlas (which is remote & ready solution).

I installed and initialized MongoDB within Docker like so (replace mongoadmin and mongopasswd to whatever you want):

docker pull mongo
docker run -d  --name mongodb  -p 27017:27017 -e MONGO_INITDB_ROOT_USERNAME=mongoadmin -e MONGO_INITDB_ROOT_PASSWORD=mongopasswd mongo

Lastly, instead of writing our API core ourselves, we'll be using the star of this episode --- Apollo Server (a.k.a. GraphQL server). It has detailed documentation available here.

Initialization

Let's dig in and start by creating our project folder:

mkdir mag-api-server
cd mag-api-server

We'll go with MAG as in MongoDB, Apollo and GraphQL for the sake of... me loving abbreviations. 🤷‍♂️

Then initialize our Node.js project:

npm init -y

Let's update our package.json by setting type to module (so we can load our JS as ES modules) and changing npm test command to npm start:

...
"type": "module",
"scripts": {
   "start": "node index.js"
},
...

Apollo Server setup

Our project directory is set up, so let's install Apollo Server with GraphQL:

npm install @apollo/server graphql -S

Then create an index.js file in your project root folder and import packages from above in it.

import { ApolloServer } from "@apollo/server"
import { startStandaloneServer } from "@apollo/server/standalone"

Define temporary movie GraphQL schema for testing purposes below:

...
const typeDefs = `#graphql
  type Movie {
    title: String
    director: String
  }

  type Query {
    movies: [Movie]
  }
`

And add movies data set below:

...
const movies = [
   {
      title: "Edward Scissorhands",
      director: "Tim Burton",
   },
   {
      title: "The Terrifier 2",
      director: "Damien Leone",
   },
]

Next, we'll need to define a resolver.

⚡"Resolver tells Apollo Server how to fetch the data associated with a particular type." Because our movies array is hard-coded, the corresponding resolver is straightforward.

...
const resolvers = {
   Query: {
      movies: () => movies,
   },
}

Let's define our Apollo Server instance:

const server = new ApolloServer({
   typeDefs,
   resolvers,
})

const { url } = await startStandaloneServer(server, {
   listen: { port: 4000 },
})

console.log(`🚀  Server ready at: ${url}`)

And test run our server:

npm start

Which should print back:

> mage-api-server@1.0.0 start
> node index.js
🚀  Server ready at: http://localhost:4000/

If you open http://localhost:4000/, you will see a sandbox environment, where we will be executing GraphQL queries.

Go ahead and run this query in the operations tab:

query Movies {
   movies {
      title
      director
   }
}

If everything is set up correctly, you will receive this JSON response:

{
   "data": {
      "movies": [
         {
            "title": "Edward Scissorhands",
            "director": "Tim Burton"
         },
         {
            "title": "The Terrifier 2",
            "director": "Damien Leone"
         }
      ]
   }
}

Restructure Schemas & resolvers

With our Apollo Server running and querying, let's restructure our project files and create more automated type schema inclusion. We'll start by creating ./schemas/ folder which will hold our GraphQL type schemas.

For resolvers --- create ./resolvers/ folder as well as ./resolvers/movie.js file. Next, cut our movies constant data set and resolvers definitions from index.js and paste them into ./resolvers/movie.js. Finally, prefix resolvers with export and rename it to moviesResolvers:

const movies = [
   {
      title: "Edward Scissorhands",
      director: "Tim Burton",
   },
   {
      title: "The Terrifier 2",
      director: "Damien Leone",
   },
]

export const moviesResolvers = {
   Query: {
      movies: () => movies,
   },
}

Next, create ./schemas/Movie.graphql file, cut Movie type schema from ./index.js and paste it in our newly made file (without GraphQL syntax and JS definition):

type Movie {
   title: String
   director: String
}

type Query {
   movies: [Movie]
}

Before we create a loader for resolvers and schemas, let's install the necessary GraphQL Tools:

npm i @graphql-tools/load @graphql-tools/schema @graphql-tools/graphql-file-loader -S

Now create ./loader.js in the project root folder and import both scheme and resolvers using our new tools:

import { loadSchema } from "@graphql-tools/load"
import { GraphQLFileLoader } from "@graphql-tools/graphql-file-loader"
import { moviesResolvers } from "./resolvers/movie.js"

export const typeDefs = await loadSchema("./schemas/**/*.graphql", { loaders: [new GraphQLFileLoader()] })
export const resolvers = [moviesResolvers]

⚡Using loaders in the manner above will not only automize module, resolver and schema import but also make code more readable and writable in long term.

Let's go back to ./index.js and import schemas and resolvers:

...
import { resolvers, typeDefs } from "./loader.js"
...

To test if everything works fine, re-run the server npm start command and query movies in http://localhost:4000/.

MongoDB via Mongoose

We got our type query-able schema and resolvers. Let's remove the hard-coded data set in ./resolvers/movie.js and connect the database instead.

Adding MongoDB should be pretty intuitive, however thinking ahead we'd probably want our data the OOP way, right? This is where Mongoose comes in. It's a great "driver" for that.

As mentioned in "Before you jump in" section, we will be using Dockerized MongoDB approach. To test if our MongoDB container is running, let's run this command:

docker ps -a

If you see your container and its status indicates it's running, we're ready to continue.

So let's continue by installing Mongoose:

npm i mongoose -S

Then import it in our ./index.js:

import mongoose from "mongoose"

Now, initialize our MongoDB connection somewhere above our server constant (replace mongoadmin and mongopasswd to whatever you provided when initializing Docker container):

...
mongoose.Promise = global.Promise
mongoose.set("strictQuery", false)
mongoose.connect("mongodb://mongoadmin:mongopasswd@localhost:27017/?authSource=admin")
......

So, we have our connection to MongoDB, but we still need to replace hard-coded data set with a model.

Create ./models folder and create ./models/movie.js. Open it up and create movie database schema:

import mongoose from "mongoose"

const Schema = mongoose.Schema
const MovieSchema = new Schema(
   {
      title: {
         type: String,
         default: "",
         required: true,
      },
      director: {
         type: String,
         default: "",
         required: true,
      },
   },
   {
      timestamps: {
         createdAt: "created_at",
         updatedAt: "updated_at",
      },
   }
)

export default mongoose.model("movie", MovieSchema)

In theory --- this is it. However, I mentioned something about CRUD before, so let's dig into that and customize our MAG API a little bit more. 😅

CRUD

Because I love writing so much, I want us to create simple CRUD logic in our only resolver ./resolvers/movie.js. If you haven't already, remove hard-coded dummy data set and import ./models/movie.js.

import Movie from "../models/movie.js"
...

Also, let's redefine our movies query in ./resolvers/movie.js :

...
export const moviesResolvers = {
  Query: {
    async movies(root, {}, ctx) {
      return await Movie.find()
    },
  },
}
...

Lastly, before we continue --- it is always smart to use some kind of unique identifiers for your records, therefore let's go ahead and use MongoDB default one _id and reuse it in our movie schema ./schemas/Movie.graphql:

type Movie {
  _id: ID!
  title: String
  director: String
}
...

Create (CRUD)

Define CREATE mutation in our ./schemas/movie.graphql type schema:

...
type Mutation {
   addMovie(title: String!, director: String!): Movie!
}

Next, CREATE mutation resolver below in ./resolvers/movie.js:

...
export const moviesResolvers = {
  ...
  Mutation: {
     async addMovie(root, { title, director }, ctx) {
        return await Movie.create({
           title,
           director,
        })
     },
  }
}

Now, let's restart our server and test if we can add new movie via sandbox at http://localhost:4000/ by querying this mutation:

mutation Mutation($director: String!, $title: String!) {
  addMovie(director: $director, title: $title) {
    _id
    title
    director
  }
}

And for variables let's enter data from a previously deleted data set. Write couple of different ones for the diversity of things.

{
  "title": "Prometheus",
  "director": "Ridley Scott"
}

When you're ready --- run the mutation query.

To confirm that we actually saved the movie, open up a new query tab in sandbox and re-run:

query Query {
  movies {
    _id
    title
    director
  }
}

You will receive your newly created movie within JSON response.

Now, we have to mirror our steps above and create read, update and delete logic. There is no CRUD without RUD. 🥁

Read (CRUD)

We already have a method to READ all movies, so let's just define READ query in our ./schemas/movie.graphql type schema for reading a single movie (using its ID):

...
type Query {
  ...
  getMovie(_id: ID!): Movie
}

Define READ query resolver below in ./resolvers/movie.js:

...
Query: {
  ...
  async getMovie(root, { _id }, ctx) {
    return await Movie.findOne({ _id })
  }
}
...

Restart the server and test if you can get a movie by its _id via sandbox at http://localhost:4000/ using this query:

query Query($id: ID!) {
  getMovie(_id: $id) {
    _id
    director
    title
  }
}

And use your newly added movie's _id as a variable value:

{
  "id": "63c224272a9dd1ef31d73de5"
}

Update (CRUD)

Define UPDATE mutation in our ./schemas/movie.graphql type schema:

...
type Mutation {
  ...
  updateMovie(_id: ID!, title: String, director: String): Movie
}

Now, to update the movie, we'll UPDATE mutation in out ./resolvers/movie.js like so:

...
Mutation: {
  ...
  async updateMovie(root, { _id, title, director }, ctx) {
    return await Movie.findOneAndUpdate({ _id }, { title, director })
  },
}

Restart the server, define the query and provide _id and one or both variables for it to update:

mutation Mutation($id: ID!, $title: String, $director: String) {
  updateMovie(_id: $id, title: $title, director: $director) {
    director
    title
  }
}

I'm updating "Prometheus" movie title and director, so I'm providing its _id value from the previous query response and the rest below it:

{
  "id": "63c224272a9dd1ef31d73de5",
  "title": "Antichrist",
  "director": "Lars von Trier"
}

Delete (CRUD)

Time flies and taste in movies changes, so we will obviously need a way to delete a movie in future, therefore let's go and define DELETE mutation in our ./schemas/movie.graphql type schema:

...
type Mutation {
 ...
 deleteMovie(_id: ID!): Movie
}

Next, define DELETE mutation resolver below in ./resolvers/movie.js:

Mutation: {
  ...
  async deleteMovie(root, { _id }, ctx) {
    return await Movie.findOneAndDelete({ _id })
  },
 },

Finally, let's go ahead, restart and test with this query:

mutation Mutation($id: ID!) {
  deleteMovie(_id: $id) {
    _id
    director
    title
  }
}

Now let's define _id of movie that we'll be deleting:

{
  "id": "63c224272a9dd1ef31d73de5"
}

Finally, restart the server and query all movies to see if it all worked!

🎉Congratulations!

You did it! You read this lengthy "how-to" tutorial and created your own API server with basic CRUD. 👏

Leave a comment below if and where you had trouble running the server, or if you simply want to make a suggestion.

What's next?

This API server is bare-bone by itself, so your journey doesn't end here. "One simply does not CRUD without an auth". Surely you wouldn't want to lose all your precious po.. I mean movies!? 👀

So, here are some ideas on what to do next:

What is API without a key? Try integrating JWT with basic key based permission logic;
Integrate this with a front-end framework, for example, Vue.js;
Containerize your API server and MongoDB for Docker (make an easily deployable container);
Write sanitizers & conditions to work with duplicates or queries returning errors on non-existing records;
Secure queries and mutations by writing checks for inputs and customizing callbacks (I might do part 2 regarding this);

Publish your first NPM package - next step towards open-source

richardevcom — Sun, 14 Aug 2022 20:03:00 +0000

A while back I wrote an article about custom Vue 3 boilerplate where I swiftly went over how to stack your own reusable boilerplate. With surprisingly positive feedback, it became obvious that I’ll open-source it. So, while hosting it on GitHub, I decided to also publish my boilerplate on NPM — Node Package Manager — to make easily manageable and quickly install-able package.

With Node.js becoming more and more popular among programmers, correlatively numerous popular modules were being re-published and maintained on NPM "registry". I too wanted to give back to open-source community, therefore in this article/tutorial I will go through the process of publishing my custom boilerplate on NPM as an example.

Prerequisite

One of the first things you'll need are verified NPM account and installed Node.js. Obviously. 😅

Create NPM account

Go ahead, visit NPM Signup page, fill out the sign up form and verify your account with one time password (sent to your e-mail).

⚡Ideally, setup 2-Factor Authentification protection before you continue.

Install Node.js

Now it's time to install Node.js (it comes together with NPM command-line tool) - visit https://nodejs.org/en/download/ and select installation depending on your OS and CPU cores of the machine.

⚡Note - if you have 2 or more CPU cores, you should use 64bit installer.

Run the installer. You'll be fine by going with default settings, just make sure you've selected "Add to path" - this will allow you to run NPM command-line.

After installation is done - open up terminal and test if you can use Node.js & NPM command-line tool:

node -v // Node.js Version
npm -v  // NPM version

👏 It works!

Initialize our package

Great, now we can initialize our package of choice. In my case, I'll open up my Vue 3 boilerplate directory and start NPM initialization process:

cd vue3-boilerplate
npm init

⚡Feel free to use my Vue 3 boilerplate for the sake of this tutorial.

You'll now be asked to fill in the basic package information, such as - name, version, description, keywords and etc. Once done, new package.json file will be created in your project's root, containing all the package information.

⚡Remember - make your package more reachable… add as detailed information as possible, as well as many keyword combinations as possible. You can learn more about configuring package.json here.

Login

Before we can publish, we'll have to login to NPM:

npm login
Username: <your_username>
Password: <your_password>
Email: (this IS public) <your_e-mail>

If you don't have 2FA setup (which I strongly advice you to do), you'll be sent an One-Time Password to your e-mail. Copy it and finish your login process:

npm notice Please check your email for a one-time password (OTP)
Enter one-time password: 12345678
Logged in as <your_username> on https://registry.npmjs.org/.

Final test

There are many npm link tutorials out there on how to test a package before publishing, so in contrary I'll do the other, much simpler way.

Create ./test directory in ./vue3-boilerplate project's root directory, go into ./test directory and initialize test install in the folder:

mkdir test
cd test
npm i "../"
// or
npm i "absolute/path/to/<your_package_name>"

⚡Always test before publishing!

Publish package

Now - 🥁(drumroll) the moment of truth - time to publish our solution to NPM public repository (remember, you have to be inside your project directory when running this):

npm publish --access public

You'll be asked for either 2FA code or One-Time Password sent to your e-mail. Enter one of them and finish the publishing process.

If everything was entered correctly, you should see this in the end:

npm notice Publishing to https://registry.npmjs.org/
+ vue3-boilerplate@1.0.6`

⚡To publish privately, remove --access public parameter. Remember, you have to have at least Pro subscription to have access to private package hosting on NPM.

Updating package

In order to update your package, you'll have to update the version number as well. For testing purposes, let's open up our package.json file and increase the version number from 1.0.0 to 1.0.1.

...
"version": "1.0.1"
...

Save and re-publish your package again. This time you can use one of the version control commands:

npm version patch // 1.0.1 => 1.0.2
npm version minor // 1.1.0 => 1.2.0
npm version major // 1.0.0 => 2.0.0

Then:

npm publish --access public

Now, if you visit your package's NPM repository page, you should see the newly updated version.

🎉Congratulations!

You're ready to open-source your own NPM packages. 👏

Final words

In conclusion I just want to mention a couple crucial points regarding publishing packages:

Always - and I mean ALWAYS - test before publishing. Nobody wants to install a broken package. There are many different testing tools depending on your stack.
403 - Forbidden - an error during publishing can mean many things - your newly created account e-mail is not verified, the name of your package is already taken, you don't have Pro subscription to publish privately or you're updating the same version.
Write README.md file. Imagine - you're reaching the views, but nobody is downloading your solution because, well.. there is no documentation on how to use your solution. 🤨
NPM has a lot more great commands up its sleeves - simply hit npm help or npm help <command> to list them all or read its documentation. I found this article with some great NPM tips & tricks.
Automate your NPM package installation with NPX or NPM CLI. It is a great idea to give developers the possibility to configure your package during main installation process.

If you're having trouble following my steps above, or simply liked this article - I'll appreciate it if you reach out in the comments below. 👋

Custom Vue 3 boilerplate - Vite, Pinia, Vue Router & Tailwind CSS

richardevcom — Wed, 03 Aug 2022 13:32:00 +0000

⚡Update: I've recreated TypeScript ready version of this boilerplate here.

A while back I realized I'm trashing my beautiful workspace with quite a few repetitive Vue web apps. Shortly before backing them up to never be seen again, it clicked - why not repurpose those reusable parts and simply stack them in a boilerplate? 🤔

I doubt that many devs like staging same project and repeat same initial commands again and again, therefore in this article "slash" tutorial I will swiftly go over how does one stack and configure a boilerplate.

Boilerplate stack

The stack of this boilerplate is focused on web app front end, therefore I'll keep it simple and use following packages:

Vite - dev tool for building and serving
Pinia - for storing
Vue Router - for dynamic routing
Tailwind CSS - for looks
Vite SVG loader (optional) - to easily import SVGs

Prerequisite

Before we start, I'm assuming you're somewhat acquainted with command line and have Node.js installed. If not - download it here. To check if it's installed, simply run node -v command.

Quickstart - Vue, Router & Store

Let's begin by initializing our boilerplate project.

npm init vue@latest

Now enter the project name. I'll be using vue3-boilerplate. On feature prompt choose to install Pinia and Vue Router.

✔ Project name: vue3-boilerplate
...
✔ Add Vue Router for Single Page Application development? Yes
✔ Add Pinia for state management? Yes

It's time to move into our project folder, install packages and run our boilerplate in development environment.

cd vue3-boilerplate
npm install
npm run dev

You should be seeing on your local development environment http://127.0.0.1:5173 this example page:

You can learn more about building or serving your app in this guide. Oh, and read more about Pinia here. It is very similar to Vuex.

Add Tailwind CSS

👏 Great, we got our base, now we need the looks. Following this guide we are installing Tailwind CSS, its dependencies and then initializing configuration file.

npm install -D tailwindcss postcss autoprefixer
npx tailwindcss init -p

In your project root you'll now find tailwind.config.js file - let's open it and add our template paths:

module.exports = {
   content: [
      "./index.html",
      "./src/**/*.{vue,js,ts,jsx,tsx}",
   ],
   ...
}

Next we will need to load @tailwind directives, so let's create tailwind.css in our /src/assets folder with following directives:

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

Now let's load this CSS file by importing it in the very top of /src/assets/main.css file:

@import "./tailwind.css";
...

Since we already import /src/assets/main.css file in /src/main.js, we are good to use Tailwind's utility classes in our project.
Let's test it out by adding some classes inside /src/views/AboutView.vue in <h1> tag:

<template>
   <div class="about">
      <h1 class="text-xl font-medium text-white">This is an about page</h1>
   </div>
</template>

We can also define our CSS properties separately below. To do so, we will need to install SASS package and PostCSS plugin - sass & postcss-import:

npm i -D sass postcss-import

Now let's use @apply with our utility classes:

<template>
   ...
   <h1>This is an about page</h1>
   ...
</template>
<style lang="scss">
   .about {
      @apply lg:min-h-screen lg:flex lg:items-center;

      h1 {
         @apply text-xl font-medium text-white;
      }
   }
</style>

🎉 Awesome! We have our core and we have our looks. What else could we add? 🤔

Add SVG loader (optional)

I like my SVG like I like my app - Component-Driven.🥁 It just so happens that our newly stacked boilerplate can easily import SVG imagery, but there is a catch - you'll have to use it as component, meaning you'll manually have to add SVG code within template tags and import it like that.

Luckily there is this vite-svg-loader package that basically allows you to simply import your .svg files within Vue template as components. Let's proceed by adding it to our boilerplate:

npm install vite-svg-loader --save-dev

Now add this plugin in our vite.config.js configuration file:

...
import svgLoader from 'vite-svg-loader'
export default defineConfig({
   plugins: [vue(), svgLoader()],
   ...
})

Lastly, to test it out I'm going to change that Vue.js logo code to Vite.js in /src/assets/logo.svg to this one and save it:

<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" viewBox="0 0 2454.32 2457.41"><defs><linearGradient id="a" x1="285.11" y1="1790.44" x2="285.7" y2="1789.74" gradientTransform="matrix(2454.32, 0, 0, -2187.24, -699180.9, 3916163.49)" gradientUnits="userSpaceOnUse"><stop offset="0" stop-color="#41d1ff"/><stop offset="1" stop-color="#bd34fe"/></linearGradient><linearGradient id="b" x1="285.22" y1="1790.33" x2="285.29" y2="1789.46" gradientTransform="matrix(1125.42, 0, 0, -2051.66, -319596.68, 3673197.31)" gradientUnits="userSpaceOnUse"><stop offset="0" stop-color="#ffea83"/><stop offset="0.08" stop-color="#ffdd35"/><stop offset="1" stop-color="#ffa800"/></linearGradient></defs><path d="M2464.14,381.6,1311.22,2443.21c-23.8,42.57-85,42.82-109.12.46L26.33,381.79C0,335.63,39.47,279.72,91.78,289.08L1245.93,495.37a62.88,62.88,0,0,0,22.27,0l1130-206C2450.35,279.87,2490,335.35,2464.14,381.6Z" transform="translate(-17.94 -17.87)" style="fill:url(#a)"/><path d="M1795.71,18.48,942.53,185.66a31.33,31.33,0,0,0-25.25,28.9L864.8,1101a31.33,31.33,0,0,0,29.41,33.14,31.77,31.77,0,0,0,8.91-.75l237.54-54.82a31.32,31.32,0,0,1,37.73,36.79l-70.57,345.59a31.33,31.33,0,0,0,39.8,36.24l146.72-44.57a31.34,31.34,0,0,1,39.79,36.32L1222,2031.73c-7,33.95,38.14,52.47,57,23.36l12.59-19.44L1986.77,648.19c11.65-23.23-8.44-49.72-33.94-44.79l-244.52,47.18a31.33,31.33,0,0,1-36-39.44L1831.86,57.91a31.34,31.34,0,0,0-36.14-39.43Z" transform="translate(-17.94 -17.87)" style="fill:url(#b)"/></svg>

Then in /src/App.vue file I'll import it as SVG component and replace it with <img class="logo" />.

<script setup>
   ...
   import LogoSVG from './assets/logo.svg?component'
</script>
<template>
   ...
   <LogoSVG alt="Vite logo" class="logo" />
   ...
</template>

🎉Congratulations!

You are a proud owner of your very own boilerplate. 👏

What's next?

You would now want to create an easily pull-able starter kit - for example, in Github - so your boilerplate is always one command away. I actually did just that - you can pull my version of boilerplate here or simply pull it:

npm i @richardev/vue3-boilerplate

Finally, I want to share this list of some useful Vue.js related packages to add to your boilerplate:
NuxtJS - Vue.js Framework
Vue Meta - for Web App SEO
VeeValidate - form validation
Vue Toastification - alerts a.k. toasts

If you have ideas on what to add or remove in this boilerplate, tips on configuring it or you simply have an issue setting it up - I'll appreciate if you reach out in the comments below. 👋

⚡Update: I've recreated TypeScript ready version of this boilerplate here.