Forem: JoLo

Building Confidence with Testcontainers

JoLo — Wed, 01 Apr 2026 20:25:09 +0000

Modern Node.js applications rarely live in isolation. They depend on databases, caches, message brokers, and third-party APIs. Unit tests validate business logic, but they cannot guarantee everything will still work once your service runs in a real environment with real dependencies.

This is where Testcontainers comes in: it lets you run integration tests against real services inside disposable Docker containers, both locally and in CI.

The Classic Deployment Failure Scenario

Story generated with Nano Banana 2

A familiar story:

You implement a new feature.
Your unit tests are green.
CI passes, you deploy, and everything looks good.
Shortly after, alerts start firing and messages arrive: requests are failing, the database can’t be reached, or some external service integration is broken.

Looking into the logs, you discover that your service failed to connect to another service—maybe a database, maybe a cache, maybe a message broker. The root cause is often that integration paths were never validated end-to-end. The code was tested in isolation, but the system was not.

In modern architectures—microservices and distributed systems—each service is just a small cog in a much larger machine. Services communicate over HTTP, gRPC, queues, and streams. If we only test in isolation with mocks, we ignore the very thing that often breaks in production: the integrations.

Why Integration Tests Are Hard

Integration tests are traditionally considered “hard” because:

They require external infrastructure, such as databases, brokers, or cloud services.
Managing these dependencies locally is painful (installing and configuring Postgres, Redis, Kafka, etc.).
Shared staging/sandbox environments are fragile and rarely reliably mirror production.
Cleaning up after tests is error-prone and often left to manual work.

A common workaround is to deploy to a sandbox or test environment and run manual or partially automated tests there. But these environments can drift from production and are often shared between teams, leading to flaky tests and fragile pipelines.

What Testcontainers Solves

Testcontainers addresses these pain points by wrapping real services inside lightweight, disposable Docker containers, managed directly from your tests.

At a high level, Testcontainers:

Starts a real service (for example, PostgreSQL or Redis) inside a container before your tests run.
Exposes connection details (host, port, credentials) to your test code.
Runs your tests against this real instance.
Automatically tears down the container afterwards.

This gives you:

Real services instead of mocks.
Isolated infrastructure per test suite (or even per test).
Repeatable, production-like testing both locally and in CI. ## Testcontainers vs. Docker Compose

It might be tempting to reach for Docker Compose for integration tests, but there are several drawbacks:

Port conflicts: Different projects or versions of the same service (e.g., PostgreSQL 8 vs 16) can’t share the same host port.
Networking complexity: You need to understand Docker’s networking model and set it up correctly.
Manual lifecycle management: It’s easy to start services in detached mode and forget to stop or remove them, leaving containers and volumes around.

Testcontainers abstracts all of this:

It picks free host ports automatically.
It hides Docker networking details behind a simple API.
It ensures containers are cleaned up when tests complete.

Instead of managing YAML files and Docker commands, you work entirely in code.

Example: Node.js (Bun) + Redis

Consider a simple Node.js/Bun application that uses Redis for caching. The application provides two functions: one to set a value in the cache and one to read it.

Application code (simplified):

import { createClient } from 'redis';

export async function setCache(redis: any, key: string, value: string) {
  await redis.set(key, value);
}

export async function getCache(redis: any, key: string) {
  return await redis.get(key);
}

Without Testcontainers, you would either:

Install Redis locally and assume it’s running on a given port, or
Mock Redis entirely and never hit a real instance.

With Testcontainers, you can spin up a real Redis container just for your tests.
Integration test with Testcontainers and Bun's Redisclient:

import { RedisClient } from "bun";
import { describe, beforeAll, afterAll, it, expect } from 'bun:test'
import { RedisContainer, StartedRedisContainer } from "@testcontainers/redis";
import { getRedis, setRedis } from ".";

describe("Redis", () => {
  let container: StartedRedisContainer;
  let redisClient: RedisClient;

  beforeAll(async () => {
    container = await new RedisContainer("redis:8").start();
    const connectionUrl = container.getConnectionUrl();

    redisClient = new RedisClient(connectionUrl);
    await redisClient.connect();
  }, 30000);

  afterAll(async () => {
    if (redisClient) {
      redisClient.close();
    }
    if (container) {
      await container.stop();
    }
  });

  it("works", async () => {
    await setRedis("key", "val", redisClient);
    const cache = await getRedis("key", redisClient);
    expect(cache).toBe("val");
  });
});

This test:

Starts a Redis container dynamically.
Connects to it using the mapped host and port.
Runs a real end-to-end operation (set + get).
Cleans up everything afterwards.

No manual Docker commands, no global Redis install, no mock behavior hiding integration issues.

How Testcontainers work

The good thing is you can easily swap the docker images out. So instead of using redis, you could use the open source module valkey 👇

import { RedisClient } from "bun";
import { describe, beforeAll, afterAll, it, expect } from 'bun:test'
import { ValkeyContainer as RedisContainer, StartedValkeyContainer as StartedRedisContainer } from "@testcontainers/valkey";
import { getRedis, setRedis } from ".";

describe("Redis", () => {
  let container: StartedRedisContainer;
  let redisClient: RedisClient;

  beforeAll(async () => {
    container = await new RedisContainer("valkey/valkey").start();
    const connectionUrl = container.getConnectionUrl();

    redisClient = new RedisClient(connectionUrl);
    await redisClient.connect();
  }, 30000);

  afterAll(async () => {
    if (redisClient) {
      redisClient.close();
    }
    if (container) {
      await container.stop();
    }
  });

  it("works", async () => {
    await setRedis("key", "val", redisClient);
    const cache = await getRedis("key", redisClient);
    expect(cache).toBe("val");
  });
});

And you will notice the logic did not change.

Running Testcontainers in CI/CD

Testcontainers can be used in CI environments as long as Docker is available. Typical setup:

Ensure the CI runner has Docker installed and the test process has permission to talk to the Docker daemon.
Run your test suite as usual (npm test, bun test, pnpm test, etc.).
Testcontainers spins up and tears down containers on the fly.

This brings the same level of integration testing you have locally into your automated pipeline, giving you much higher confidence before each deployment.

When to Use Testcontainers

Testcontainers is particularly useful when:

Your service talks to databases, caches, or message brokers and you want to test those interactions realistically.
You want to avoid maintaining dedicated integration environments.
You want reproducible tests with self-contained infrastructure, both locally and in CI.

It doesn’t replace unit tests, but complements them by validating that the whole system behaves correctly when real dependencies are involved.

Go check it out.

Do we need AWS Durable Functions when we have Step Functions?

JoLo — Mon, 05 Jan 2026 09:51:33 +0000

At re:invent 2025, AWS announced AWS Lambda Durable Functions, which could replace Step Functions and enable multi-step applications.
This got me interested because I don't like the definition in YAML or JSONata for Amazon Step Functions. But I appreciate the visual representation of each step and the ability to debug them individually.

In this blog post, I want to compare Step Functions with AWS Lambda Durable Functions.

What are Durable Functions?

Durable Functions are Serverless building blocks that let ordinary code remember its place. They can sleep for hours, wait for external events, survive crashes and new deployments, then pick up exactly where they left off—without keeping a server warm or paying for idle time.

Cloud providers hide the complexity: each time the function yields, the runtime snapshots the call stack and state to disk (or a distributed log) and restores them on the next wake-up. You get the elasticity of functions with the reliability of long-running workflows.

Cloudflare, Azure, and Vercel are offering Durable Workflows. But also businesses like Temporal.io and Inngest build their business around them. Trigger.dev is an open source library for TypeScript apps (I am a fan 😇) that also offers a nice UI for them.

The Idea

Okay, back to the questions, if we need Durable Functions when we have Step Functions?
To answer that, we will create a simple Magic Link confirmation.

In an architectural view where I combine durable functions handler with Step Functions, it would look like this:

For this demo, I created an API Gateway that has two endpoints. One points to the durable function; the other points to Step Functions.
From the architecture, you can clearly see that the durable function's architecture is simpler. We will cover the part with the Send Task Token later.
You can find the repository here.

The following sections describe the implementation of each.
To do this, we will use AWS CDK in TypeScript.

Durable Function

The NodeJsFunction- construct has a new property durableConfig.

new NodejsFunction(this, 'DurableHandler', {
  functionName: 'durable-handler',
  runtime: Runtime.NODEJS_24_X,
  entry: 'lambdas/durable/handler.ts',
  // 👇 this marks the handler to become durable
  durableConfig: {
    executionTimeout: Duration.minutes(15)
  }
})

In the AWS Console, it looks as follows

For the AWS Lambda Handler, I used the npm package aws-durable-execution-js.
Here, when a function is running

Here the code for the durable function that waits for a callback. For that, we need to install the aws-durable-execution-js

import { checkValue } from '../shared/check-value';
export const handler: DurableLambdaHandler = withDurableExecution<EmailRequest>(
  async (event, context) => {
    console.log('durable-handler event', event)
    const { email } = event
    const result = await context.waitForCallback(
        'wait-for-users-input',
        async (callbackId, ctx) => {
          ctx.logger?.info(`Submitting callback ID to external service: ${callbackId}`);

          const result = await sendEmail({
            email,
            taskToken: callbackId // <-- Callback Id has been generated
          });
          ctx.logger.info(`DurableLambdaHandler result ${result}`, result)

          const foundValue = await checkValue(email, result.code) // <-- This actually not correct but for demo purpose we keep it
          ctx.logger.info('DurableLambdaHandler foundValue', foundValue)
        },
        {
          timeout: { minutes: 15 },
        }
      );
      console.log('durable-handler result', result)
      return {
        success: true,
        externalResult: result,
      };

    return {
      success: true
    }
  }
);

The function withDurableExecution makes this durable. Then the context.waitForCallback makes the function wait and returns a callbackId to pass to the callback. That id then needs to be passed to the user.

Cannot pass another value to the Callback

However, we need another endpoint to look into the DynamoDB because the inputs have been made, and the durable function only waits for the callbackId. That means I cannot return the user input to the callback function.

Cannot use API Gateway directly in CDK

In the section above, I wanted to execute it directly from API Gateway. However, this won't work because you need a Qualified ARN, and if you use the HttpLambdaIntegration you can't. You may use L1-constructs here in order to modify the ARN. I added another proxy Lambda that executes the durable Lambda because of lazyness 😅

Use a Qualified ARNs requirement

That is one of the most confusing ones because aws-durable-execution-js and the AWS CDK do not mention that you need a Qualified ARN to invoke the durable function. Even GitHub Copilot and MCP context7 didn't get that information, so they hallucinate their response. I had to look it up in their official documentation.
In the end, I added the $LATEST to the ARN.

Not well-structured Documentation

The part where we add a policy to durable function in their documentation adds a circular dependency and CDK will fail.

const durableFunction = new lambda.Function(this, 'DurableFunction', { 
    runtime: lambda.Runtime.NODEJS_22_X,
    handler: 'index.handler',
    code: lambda.Code.fromAsset('lambda'),
    functionName: 'myDurableFunction',
    durableConfig: {
      executionTimeout: Duration.hours(1),
      retentionPeriod: Duration.days(30)
    }
}); // Add checkpoint permissions

// 👇 This creates a circular dependency
durableFunction.addToRolePolicy(new iam.PolicyStatement({
    actions: ['lambda:CheckpointDurableExecutions',
        'lambda:GetDurableExecutionState'],
    resources: [durableFunction.functionArn]
}));

However, that’s exactly what the documentation suggested. In the end, I left it out because I didn’t want to use resumability or their step-based logic anyway. I’ll revisit this once I encounter a use case that actually requires it.

Another thing is that if we want to waitForCallback, we need to send a SendDurableExecutionCallbackSuccessCommand or SendDurableExecutionCallbackFailureCommand via the Lambda API. Unfortunately, this isn't documented, but GitHub Copilot found it for me.
Furthermore, you can only use ESM (which is good) here, and you need to bundle the latest client-lambda in the token handler with it because the default client-lambda (which is usually part of the Lambda) is not up-to-date (as of 26/12/2025). It is missing the API SendDurableExecutionCallbackSucces and SendDurableExecutionCallbackFailure. It isn't delightful when your Lambda function bundle grows larger.

const callbackHandler = new NodejsFunction(this, 'CallbackHandler', {
      functionName: 'callback-handler',
      runtime: Runtime.NODEJS_24_X,
      entry: 'lambdas/shared/callback-handler.ts',
      bundling: {
        bundleAwsSDK: true, // <-- This has to be set otherwise you use an older SDK version
      },
    });

callbackHandler.addToRolePolicy(new PolicyStatement({
      actions: [
        'lambda:SendDurableExecutionCallbackSuccess',
        'lambda:SendDurableExecutionCallbackFailure'
      ],
      resources: [`${durableHandler.functionArn}:*`, durableHandler.functionArn]
    }))

Confusing AWS Console

I don't understand why the console is showing steps that come 'after' the callback is already shown as completed, even though the function is still 'running'.

Step Functions

For Amazon Step Functions, we’re currently implementing them with Lambda. I wanted to use Step Functions without Lambda, but I couldn’t validate the user’s input while the workflow was waiting. The user sends a code, but I need to pass it to the state machine while waiting. So that is why it will also be a single Lambda.

export const handler = async (event: Event) => {
  // -------------------------------------------------
  // 1️⃣ Parse incoming request
  // -------------------------------------------------
  console.log(event);
  const payload = typeof event.body === 'string' ? JSON.parse(event.body) : event.body;
  const { email, token, code } = payload;

  if (!token || !code) {
    return { statusCode: 400, body: JSON.stringify({ error: 'token and code required' }) };
  }

    // -------------------------------------------------
    // 3️⃣ Tell Step Functions the task succeeded
    // -------------------------------------------------
    const cmd = new SendTaskSuccessCommand({
      taskToken: token,
      output: JSON.stringify({ verification: 'ok' }), // any payload you want the state machine to receive
    });

    const result = await sfn.send(cmd);
    return { statusCode: 200, body: JSON.stringify({ message: 'Verification accepted'})
};

Here is the implementation in AWS CDK

const choiceStep = new Choice(this, 'IsCodeCorrect?')
      .when(Condition.stringEquals(JsonPath.stringAt('$.verification'), 'ok'), new Succeed(this, 'Success'))
      .otherwise(new Fail(this, 'IncorrectCode', {
        cause: 'Verification code did not match',
        error: 'IncorrectCode'
      }));

    const stepSendEmail = new NodejsFunction(this, 'StepSendEmail', {
      functionName: 'step-send-email',
      runtime: Runtime.NODEJS_24_X,
      entry: 'lambdas/step-functions/send-email.ts',
      bundling: {
        format: OutputFormat.ESM,
        minify: true,
      },
      environment: {
        TABLE_NAME: stateTable.tableName,
        SENDER_EMAIL: senderEmail
      },
      timeout: Duration.seconds(30)
    });
    stateTable.grantWriteData(stepSendEmail);
    emailIdentity.grantSendEmail(stepSendEmail);

    const sendEmailStep = new LambdaInvoke(this, 'SendEmailStep', {
      lambdaFunction: stepSendEmail,
      integrationPattern: IntegrationPattern.WAIT_FOR_TASK_TOKEN,
      payload:
        TaskInput.fromObject({
          email: JsonPath.stringAt('$.email'),
          taskToken: JsonPath.taskToken,
        })
    });

    // Define the state machine with task token pattern
    const definition = sendEmailStep
      .next(choiceStep); // Check if the received code matches the original code

    const stateMachine = new StateMachine(this, 'EmailStateMachine', {
      stateMachineName: 'EmailProcessingWorkflow',
      definitionBody: DefinitionBody.fromChainable(definition),
      timeout: Duration.minutes(15) // Match task token timeout
    });

For the Send Task Token to proceed, we need a proxy Lambda, similar to the durable functions.

To wait for human interaction, we need to use a Callback with the Task Token. Initially, I sent a success message, but I also need to include the user's input here. That is not possible because the step function is already running, and all arguments and inputs have been made.

So I added a task-token-sender-Handler endpoint to the API Gateway that returns a success or failure response when the user input is correct.

Conclusion

It makes sense that AWS introduced durable functions, given that Cloudflare, Azure, and Vercel had already introduced them. Now, with the rise of AI Agent, which lets functions wait for user input without losing context, this makes sense. Wes from Syntax.fm even predicted that 2026 will be the year of durable functions¹.
Definitely, the Durable Function is infrastructure-wise simple to implement, but it requires a third-party package, aws-durable-execution-js . Luckily, the handler won't grow large because the dependencies are limited to the lambda client.
It is also interesting to note that the Lambda paradigm, which used to run for 15 minutes of computing, has shifted to days, if not years.

Both the durable functions and Step Functions require a proxy to send either a success or a failure, and cannot send input to the current waiting Lambda Function. Step Functions require much more configuration (see CDK code above), and waiting for the Callback with the Task Token gave me a headache.

However, AWS Lambda Durable Functions cannot be used directly with API Gateway and require an 'Invoker' in between. It took a while to understand that I needed an invoker for that. Also, I need the Qualified ARN (simply the Lambda version at the end of the ARN) to invoke the durable handler that is missing in the developer documentation. The documentation for aws-durable-execution-js does not explain how to retrigger waitForCallback. It does not specify that it requires the Lambda SDK to send either a success or a failure (AI and MCP also weren't aware).
What is also confusing is the output in the AWS Console. It shows that the steps have already been concluded, even though the function was still running.

Cost-wise you won't be charged for idle time.

Even with some documentation issues and odd AWS Console output, I will use AWS Lambda Durable Functions more, as it requires me to structure my code better. For my little idea, I won't use Lambda's waitForCallback yet; I'll use Step Functions, event trigger.dev, or Temporal.io, as they are much more mature in that regard.

I guess Wes is right and 2026 may be the year of Durable Functions.

https://syntax.fm/show/967/what-s-going-to-happen-in-web-dev-during-2026 ↩

Why and how to optimize your Lambda

JoLo — Wed, 18 Jun 2025 19:58:06 +0000

AWS now charges you for the INIT phase, which means you pay for each cold start¹.
This blog provides tips on optimizing your Lambda to minimize cold starts and outlines the necessary configuration settings to reduce costs.

Why do we have a Cold Start in AWS Lambda?

Let me show you this beautiful animation that explains what's happening at a Cold Start²

As you can see, preparing the Lambda environment requires downloading and starting the execution environment.
The following section demonstrates how to minimize cold start and thereby reduce execution time.

Reducing the Cold Start

We can keep Cold Start small by minimizing the Lambda package.
Remember when we had to wait for the pirate movie to be downloaded because it was too big?
Also, AWS Lambda needs to download your code before executing it.

Reduce dependencies

For that, we can remove unnecessary packages, such as dev dependencies or the AWS SDK, which is already included in the execution environment.
The execution environment would check the dependencies file. In NodeJS, it is the package.json; in Python, it would be the requirements.txt, or go.mod for Go. For Python, I recommend having a requirements.dev.txt that includes both requirements.txt and the developer dependencies.

# in requirements.dev.txt
-r requirements.txt

pytest
pytest-cov
black
flake8
boto3

I recommend using NodeJS, not because it fits the event-driven, non-blocking model, but because it is very well-suited for reducing file size by bundling the code.
Esbuild is a great tool to bundle your Lambda. It is already included in the CDK construct NodeJSFunction when using AWS CDK, and you don't need source maps, at least not in production.

Here is the script on how to bundle your Lambda for a NodeJS runtime:

esbuild my-lambda.js --bundle --minify --platform=node

With this command, you get a single minified file. For example, for the Express app below, the bundle is only 790KB 🤯
I don't think that you can beat that with Python's Flask (17 MB)

const express = require('express')
const app = express()
const port = 3000

app.get('/', (req, res) => {
  res.send('Hello World!')
})

app.listen(port, () => {
  console.log(`Example app listening on port ${port}`)
})

But what if I told you that you can reduce the size even further for your NodeJS Lambda?

Choose the right Package

Especially in the Node.js ecosystem, there are numerous alternatives to choose from. When selecting an Express alternative, check out HonoJS. Not because the syntax is similar to ExpressJS, but the bundle is only 19 KB 🤯
When using Zod 4, consider Zod mini.

Use ESM

This one is not straightforward, but you can reap numerous benefits by using ESM.
ESM stands for ECMAScript Modules, and due to their statistically analyzable nature, it results in smaller JavaScript bundles³.
ECMAScript is also the JavaScript standard and is adopted by Node.js since version 16.
When using TypeScript, you are subconsciously using ESM syntax (import {} from 'my-module')

Let's compare the AWS SDK for S3. JavaScript v3 supports both ESM and CommonJS. In the following example, we initialize the S3 client using both the CJS and ESM approaches.

// CommonJS -> s3-get-files.cjs
const s3 = require('@aws-sdk/client-s3');
new s3.S3Client({ region: 'eu-central-1' });

// ESM -> s3-get-files.mjs
import { S3Client } from '@aws-sdk/client-s3';
new S3Client({ region: 'eu-central-1' });

Now, let's bundle the files

# for CJS
npx esbuild src/s3.cjs --bundle --format=cjs --outfile=s3-bundle.cjs --platform=node

# for ESM
npx esbuild src/s3.mjs --bundle --format=esm --outfile=s3-bundle.mjs --platform=node --main-fields=module,main

One note: We need to specify --main-fields=module,main to tell esbuild to check the module first; if it's not found, then use main from the package.json as a fallback.
The results of the bundles

# For CJS
s3-bundle.cjs  1.4mb

# For ESM
s3-bundle.mjs  703.0kb

The bundle of ESM results into half of the CJS- size. That also means less time to download, and faster execution time:

hyperfine --warmup 10 --style color 'node s3-bundle.cjs' 'node s3-bundle.mjs'

Benchmark 1: node s3-bundle.cjs
Time (mean ± σ): 62.1 ms ± 2.5 ms [User: 53.8 ms, System: 6.7 ms]
Range (min … max): 59.5 ms … 74.5 ms 45 runs

Warning: Statistical outliers were detected. Consider re-running this benchmark on a quiet system without any interferences from other programs. It might help to use the '--warmup' or '--prepare' options.

Benchmark 2: node s3-bundle.mjs
Time (mean ± σ): 45.3 ms ± 2.2 ms [User: 38.1 ms, System: 5.6 ms]
Range (min … max): 43.0 ms … 59.2 ms 62 runs

Warning: Statistical outliers were detected. Consider re-running this benchmark on a quiet system without any interferences from other programs. It might help to use the '--warmup' or '--prepare' options.

Summary

  node s3-bundle.mjs ran
    1.37 ± 0.09 times faster than node s3-bundle.cjs

A win-win here 🚀

Use CDK

As I mentioned, the NodeJsFunction comes with esbuild out of the box, but bundles your functions to CJS by default.
Luckily, you only need to tweak the configuration a bit to achieve ESM first.
You can specify it in the bundling- option

const lambdaFunction = new NodejsFunction(scope, 'LambdaFn', {
      runtime: Runtime.NODEJS_22_X, // <~~ Recommended
      entry: `${handlerPath}/${props.handler}.ts`,
      bundling: {
        minify: true, // the default is false
        format: OutputFormat.ESM, // <~~ Change this!
        target: 'node22', // Default is the node version of the runtime
        mainFields: ['module', 'main'], // <~~ Change this and use this order!
      }
    });

Unfortunately, ESM is not a silver bullet, and I ran into some issues. For example, running the mysql2 in ESM was not possible. Make sure to test everything properly. I wrote a more extensive blog post about ESM vs CJS.

Choose the optimal configuration for cost efficiency

You learned how to reduce the cold start (INIT-Phase) above. In this section, I want to show you a tool that helps you use the correct configuration of your Lambda: AWS Lambda Power Tuner.
In every IaC tool, you have to specify the Memory size, but how do you know what number to put in?

Yan Cui posted on LinkedIn that a reasonable default value is 1024 MB.
The general formula

Monthly Cost = (Number of Requests x Cost per Request) + (Total Compute GBS x Cost per GBS)
Total Compute GBS = Sum of all (Memory Allocated (GB) / 1024 MB/GB) * Execution Time (ms)/ 1000 ms/s))

Wow, quite a formula. Luckily, all values except the Memory Size are fixed.
Here is the list of pricing of ARM in eu-central-1:

Memory (MB)	Price per 1ms
128	$0.0000000017
512	$0.0000000067
1024	$0.0000000133
1536	$0.0000000200
2048	$0.0000000267
4096	$0.0000000533

If you configure your Lambda in eu-central-1, and you know you have 1 Mio requests and your Lambda runs for 200 ms for 128 MB, then your Lambda costs you

Monthly Cost = (1000000 x 0.0000000017) + (128MB/1024MB x 200ms/1000ms/s) = $0.61

On top of that, you would pay the cold start.

Let's say we follow Yan Cui, and the execution time should also decrease to 50 ms, the calculation appears as follows.
sh Monthly Cost = (1000000 x 0.0000000133) + (1024MB/1024MB x 50ms/1000ms/s) = $0.87`

However, as Yan also mentioned, we would not use that in Production, and it's most likely that in development, we would reach 1 Mio requests (not that we cannot do that :D).

Okay, based on that, we can make an educated guess! But we still don’t know the execution time for sure!
Let's explore Lambda Power Tuning to get the cost-efficient values for your memory in your Lambda.

Lambda Power Tuning

Lambda Power Tuning is a fascinating project that operates your Lambda with varying memory sizes and presents a chart. It displays the execution time and costs based on the memory size (see below).

How to interpret the chart above: execution time goes from 35s with 128MB to less than 3s with 1.5GB, while being 14% cheaper to run⁴.

It deploys a little state machine, and with the execution script, it outputs the result directly in your terminal.

The more executions you perform, the more accurate your memory setting becomes. Interestingly, having more memory doesn’t always mean faster execution times.

Conclusion

AWS now charges you for the 'Cold Start!' 😱 But don’t worry, there are some awesome techniques to optimize your Lambda before the INIT phase! 🎉

Let’s think about reducing dependencies by moving development dependencies outside of the actual package and exploring smaller alternatives! 🚀 Plus, bundling to ECMAScript can significantly shrink the size! Smaller bundles mean faster execution, which leads to lower costs! Win-win! 🙌

Now, during the execution phase, it’s tricky to determine the best memory size for our Lambda. That’s where AWS Lambda Power Tuning comes in—what a fantastic tool to help us find that cost-efficient configuration! 🎯

In conclusion, by optimizing our Lambda functions and embracing tools like AWS Lambda Power Tuning, we can tackle challenges head-on while keeping costs down—let’s get optimizing and make our cloud journey even more rewarding! 🚀✨

Oh CommonJS! Why are you mESMing with me?! Reasons to ditch CommonJS

JoLo — Fri, 12 Jul 2024 08:21:24 +0000

It was a normal patching day. I patched and upgraded my npm dependencies without making code changes, and suddenly, some of my unit tests failed.

Wtf!

My tests failed because Jest encountered an unexpected token; they failed because Jest cannot handle ESM-only packages out of the box. In fact, Jest is written in CommonJS.
But what does that mean? To do so, we need to understand why CommonJS and ESM exist.

Why Do We Need Module Systems?

In the early days of web development, JavaScript was mainly used to manipulate the Document Object Model (DOM) with libraries like jQuery. However, the introduction of Node.js also led to JavaScript being used for server-side programming. This shift increased the complexity and size of JavaScript codebases. As a result, there arose a need for a structured method to organize and manage JavaScript code. Module systems were introduced to meet this need, enabling developers to divide their code into manageable, reusable units¹.

The Emergence of CommonJS

CommonJS was established in 2009, originally named ServerJS². It was designed for server-side JavaScript, providing conventions for defining modules. Node.js adopted CommonJS as its default module system, making it prevalent among backend JavaScript developers. CommonJS uses require to import and module.exports to export modules. All operations in CommonJS are synchronous, meaning each module is loaded individually.

The Rise of ESM (ECMAScript Modules)

In 2015, ECMAScript introduced a new module system called ECMAScript Modules (ESM), primarily targeting client-side development. ESM uses import and export statements, and its operations are asynchronous, allowing modules to be loaded in parallel³. Initially, ESM was intended for browsers, whereas CommonJS was designed for servers. It became more and more a standard for the JS ecosystem. Nowadays, modern JavaScript runtimes support both module systems. Browsers began supporting ESM natively in 2017. Even Typescript adapted the ESM syntax, and whenever you learn it, you also learn ESM subconsciously.

CommonJS is here to stay

The truth is that there are many more CommonJS (CJS)- only packages than ESM-only packages⁴.

However, there is a clear trend. The number of ESM-only or dual module packages is on the rise, while fewer CJS-only packages are being created. This trend underscores the growing preference for ESM and raises the question of how many of the CJS-only packages are actively maintained.

Comparison

An interesting comparison between CommonJS and ESM involves performance benchmarks. Due to its synchronous nature, CommonJS is faster when directly using require and import statements. Let's consider the following example:

// CommonJS -> s3-get-files.cjs
const s3 = require('@aws-sdk/client-s3');
new s3.S3Client({ region: 'eu-central-1' });

// ESM -> s3-get-files.mjs
import { S3Client } from '@aws-sdk/client-s3';

new S3Client({ region: 'eu-central-1' });

I used the aws-sdk S3-Client because it has dual module support. Here we instantiate the client and then execute it with node:

hyperfine --warmup 10 --style color 'node s3-get-files.cjs' 'node s3-get-files.mjs'

Benchmark 1: node s3-get-files.cjs
Time (mean ± σ): 82.6 ms ± 3.7 ms [User: 78.5 ms, System: 16.7 ms]
Range (min … max): 78.0 ms … 93.6 ms 37 runs
Benchmark 2: node s3-get-files.mjs
Time (mean ± σ): 93.9 ms ± 4.0 ms [User: 98.3 ms, System: 18.1 ms]
Range (min … max): 88.1 ms … 104.8 ms 32 runs

Summary
node s3-get-files.cjs ran
  1.14 ± 0.07 times faster than node s3-get-files.mjs

As you can see, the s3-get-files.cjs and, thus, CommonJS run faster.
I got inspired by Buns Blogpost.

However, when you want to productionize your JS library, you need to bundle it. Otherwise, you will ship all the node_modules. Is used esbuild because it is able to bundle to CJS and ESM. Now, let's run the same benchmark with the bundled version.

hyperfine --warmup 10 --style color 'node s3-bundle.cjs' 'node s3-bundle.mjs'

Benchmark 1: node s3-bundle.cjs
Time (mean ± σ): 62.1 ms ± 2.5 ms [User: 53.8 ms, System: 6.7 ms]
Range (min … max): 59.5 ms … 74.5 ms 45 runs

Warning: Statistical outliers were detected. Consider re-running this benchmark on a quiet system without any interferences from other programs. It might help to use the '--warmup' or '--prepare' options.

Benchmark 2: node s3-bundle.mjs
Time (mean ± σ): 45.3 ms ± 2.2 ms [User: 38.1 ms, System: 5.6 ms]
Range (min … max): 43.0 ms … 59.2 ms 62 runs

Warning: Statistical outliers were detected. Consider re-running this benchmark on a quiet system without any interferences from other programs. It might help to use the '--warmup' or '--prepare' options.

Summary

  node s3-bundle.mjs ran
    1.37 ± 0.09 times faster than node s3-bundle.cjs

As you can see, the s3-bundle.mjs is now faster than the s3-bundle.cjs. The ESM file is now even faster than the unbundled CommonJS file because it results in smaller file sizes and faster load times due to efficient tree-shaking—a process that removes unused code.

Embrace ESM!

The future of JavaScript modules is undoubtedly leaning towards ESM. This starts when creating a new NodeJS project or even a React project. Every tutorial and article uses the import—statement, which is thus ESM. Despite many existing CommonJS packages, the trend is shifting as more developers and maintainers adopt ESM for its performance benefits and modern syntax. Another question is also how many of these CJS-only projects are still maintained.

ESM is a standard that works in any runtime, such as NodeJS, Bun, or Deno, and in the browser without running on a server. It is unnecessary to convert via Babel to CommonJS because the browser understands ESM. You can still use Babel to convert to a different ECMAScript version, but you shouldn't convert to CJS.

You should develop in ESM-only because every runtime now and browser newer than 2017 understands ESM.

If your code breaks, you may have legacy issues. Consider using different tooling or packages. For example, you can migrate from Jest to vitest or from ExpressJS to h3. The syntax remains the same; the only difference is the import statement.

Key Takeaways:

Smaller Bundles: ESM produces smaller bundles through tree-shaking, leading to faster load times.
Universal Support: ESM is supported natively by browsers and JavaScript runtimes (Node.js, Bun, Deno).
Future-Proof: With ongoing adoption, ESM is positioned as the standard for modern JavaScript modules.

To get started, you can follow this Gist or get an inspirational learning here.

For a better JavaScript Future, Embrace ESM!

The presentation

More Resources

GHosttp

JoLo — Fri, 24 May 2024 15:21:00 +0000

GHosttp is a tiny development server for developing GCP functions.
With GHosttp, you can choose the folder where your GCP functions reside, allowing you to start developing from there.
Your functions can be developed in Typescript and use the latest ESM features.

Why?

The functions framework by Google does not offer a great developer experience when developing an entire backend using GCP.
Whenever you develop or test a new function, you must run the npx @google-cloud/functions-framework --target=myFunction command. Not only is that super long, but it also does not offer hot module reloading.
What if the name changes?
You need to rerun the command. Do you really want to create a bash alias for this library?
Furthermore, their repository shows CommonJS syntax. What if you want to use ESM or Typescript? Since Gen2 is running on Node v20, you could and should leverage ESM. GHosttp is familiar with both ESM and Typescript.

Cloud Run

The Gen2 GCP cloud functions use ExpressJS on top of Cloud Run. ExpressJS comes with a development server. So, why not directly develop it locally in Express and then put it in a Dockerfile? Well, that's a lot of work, and you must be familiar with Docker and Cloud Run. GCP Cloud Functions gen2 abstracts many things for you.

Opinionated

This package is a bit opinionated about developing your GCP function, but I made it as close to the ExpressJS function as possible.
You must name your function handler, and it shall be exported. Below you find a Typescript version.

import type { Request, Response } from '@google-cloud/functions-framework';

export const handler = async (req: Request, res: Response) => {
  res.set('Access-Control-Allow-Origin', '*');
  res.set('Access-Control-Allow-Methods', 'POST');

  // Because of CORS
  if (req.method === 'OPTIONS') {
    res.set('Access-Control-Allow-Methods', 'GET');
    res.set('Access-Control-Allow-Headers', 'Content-Type');
    res.set('Access-Control-Max-Age', '3600');
    res.status(204).send('');
    return;
  }

  // Destructering your request body
  const { message } = req.body;
  res.set('Content-Type', 'application/json');
  res.send(
    JSON.stringify({
      message,
    }),
  );
  return new Response(JSON.stringify(message));
};

Requirements

GCP account
GCP functions gen2
Node >= 20 (I haven't tried with 18, but it's a good point to upgrade)

Getting Started

In your repository, just run npx ghosttp --dir path/to/my/functions. That's all. Per default, your backend will run on http://localhost:3000

  ➜ Local:    http://localhost:3000/
  ➜ Network:  use --host to expose

🚀 Loading server entry ./src/run-dev-server.ts GHosttp 12:21:58 AM
✅ Server initialized in 90ms                   GHosttp 12:21:58 AM
👀 Watching ./path/to/functions for changes     GHosttp 12:21:58 AM
ℹ Following endpoints are available             GHosttp 12:21:58 AM
ℹ /logger                                       GHosttp 12:21:58 AM
ℹ /run-dev-server                               GHosttp 12:21:58 AM

It watches whenever you make changes to your function or add a new function. This is great if you want to do Test-Driven-Development and get instant feedback.

Watch the video above to see it in action.

Arguments

--dir - Path to your functions (default ".")
--port - Port where your localhost will run (default 3000)

PR and contributions are welcome

Find the repository here:
https://github.com/jolo-dev/ghosttp

What's next?

I will add a development server for Flask and Go.
Furthermore, I want to add a new command, npx ghost add-handler my-new-handler --typescript, which scaffolds a new file.
I will also make a blog/video about deploying your ESM/Typescript GCP function ;)

Let me know what you think, and I will be happy to make any contribution 🤩

Don't (.git)ignore .vscode

JoLo — Mon, 06 May 2024 13:34:53 +0000

Have you ever reviewed a PR that has formatting changes?

That could happen because developer tend to have their configurations and settings or don't use the linting and formatting command and simply skip the pre-commit 🫠

Let's say your team uses VS Code as their editor.
What if you could use the .vscode folder to share repository settings? You can put settings, configuration, and recommended extensions inside .vscode and share them with your colleagues. This ensures that everyone is on the same page, reducing the chances of errors and inconsistencies. However, I have noticed that some people delete the .vscode folder or put it into the .gitignore.

But with that, you are missing out on its capabilities to streamline settings and even increase productivity by enabling formatting and linting.
So, please Don't (.git)ignore the vscode 🙅‍♂️
Let's explore together how to utilize its features to take your development to the next level.

Understanding the Importance of Configuration

To create a consistent configuration, you can create a settings.json file in your VS Code folder. This file allows you to define settings for your project, such as the formatting style, compiler version, and default formatter. By sharing this file with your team, you can ensure everyone is working with the same configuration.

{
    'editor.formatOnSave': true,
    'typescript.tsdk': './node_modules/typescript/lib',
    '[typescript]': {
        'editor.defaultFormatter': 'biomejs.biome'
    },
    'eslint.format.enable': false,
    'typescript.format.enable': false,
    'prettier.enable': false
}

editor.formatOnSave: true - allows formatting whenever you hit the save button
typescript.tsdk - ensures using the correct compiler version
editor.defaultFormatter - allows changing the formatter. You can have individual formatter by programming languages. Above we define a formatter for Typescript- files.
eslint.format.enable: false - ensures that ESLint is disabled because, in my case, BiomeJS is able to do it. Otherwise, you may have conflicting linting errors
typescript.format.enable: false - disable the VS Code in-built formatter. It could conflict with the default formatter
prettier.enable: false - same as above

Recommending Extensions

VS Code allows you to recommend extensions to new users or team members. By adding an extensions.json file to your VS Code folder, you can specify the extensions that are required for your project. This ensures that new users have the necessary tools to work on the project efficiently.

{
  'recommendations': [
    'biomejs.biome'
  ]
}

Code Snippets

Code snippets are a powerful feature in VS Code that allows you to scaffold code quickly. By creating custom snippets, you can generate boilerplate code for your project, reducing the time and effort required to write code. However, the syntax for defining is quite complicated. That is why I would recommend to use the snippet generator tool which helps you create snippets quickly and efficiently.

{
  'Creates a simple Snippet': {
    'prefix': 'snippet',
    'description': 'Creates a simple Snippet',
    'body': [
      'import { http, type Request, type Response } from '@google-cloud/functions-framework';',
      '',
      'export const $0 = async ( req: Request, res: Response ) => {',
      '  const result = { result: 'This is gonna be the result for Handler: $0'}'
      '  res.send(',
      '    JSON.stringify( {',
      '      result,',
      '    } ),',
      '  );',
      '};'
    ]
  }
}

prefix - the shortcut that appears in the autocompletion box
description - the description of the snippet
body- the code which will be generated or scaffolded
$0- where the cursor will land. You can add multiple variables by $1, $2 etc. you change the variables by tabbing.

Launching a Fully Fledged IDE

VS Code can be turned into a fully-fledged IDE by using the launch.json file. This file allows you to define configurations for your project, including the executable, working directory, and runtime arguments. By using the launch.json file, you can create a customized development environment that suits your needs.

For example, when you have a Monorepo you can turn on a debugger for the backend and frontend.

{
    'configurations': [
        {
            'type': 'node',
            'name': 'Run Backend',
            'cwd': '${workspaceFolder}/packages/backend',
            'request': 'launch',
            'runtimeExecutable': 'bun',
            'runtimeArgs': [
                'dev'
            ],
            'console': 'integratedTerminal'
        },
        {
          'type': 'expo',
          'request': 'attach',
          'name': 'Debug Expo app',
          'projectRoot': '${workspaceFolder}/packages/app',
          'bundlerPort': '8081',
          'bundlerHost': '127.0.0.1'
        }
    ]
}

type - Where the debugger should be running
request - either attach for attaching it to a running instance e.g. you turn on the development server and want to attach the debugger to it, or launch where you create a new instance
name - the name will be reflected in the Run and Debug tab
cwd or projectRoot- change working directory if your script is located in a different folder
runtimeExecutable - for running a binary
runtimeArgs - the arguments that the binary is using
console - where you want to log the logs. VS Code is giving you suggestions
if attach, bundlerPort - the port where the current instance is running
if attach, bundlerHost - the url where the current instance is running (usually, localhost)

Conclusion

In conclusion, VS Code is a powerful tool that can help you streamline your development process, improve code quality, and increase productivity. You can take your development to the next level by configuring your editor like a pro. Don't ignore the power of VS Code; instead, harness its features to create a customized development environment that suits your needs ⭐

Cloud Tools You Probably Haven't Heard Of

JoLo — Sun, 31 Mar 2024 19:25:51 +0000

Keeping an eye on your cloud resources becomes increasingly difficult as their number grows. However, the tools below offer effective solutions for monitoring resources and controlling costs.

Komiser

Komiser is an open-source platform loved by cloud experts and developers. Connect your cloud accounts to get detailed insights into your cloud infrastructure.

It provides a nice dashboard to see your cloud assets inventory, understand their resource dependencies, and uncover idle, underutilized, and untagged resources. Komiser aims to bring transparency to cloud management. I see it as a useful tool for creating an inventory of your cloud resources. It can be connected to AWS, GCP, Azure, Digital Ocean, and more. It is interesting to see what resources are abstracted from when using a library like AWS CDK or AWS SAM.

Steampipe

Steampipe is a tool for querying cloud APIs and other data sources using SQL in a zero-ETL manner.

Some key capabilities include:

Dynamically query APIs, code repositories, logs, and other data sources using SQL for unified access.
Combining data from different sources creates new insights through relationships and attributes across entities.
It operates without needing to set up traditional databases through its 'Zero-ETL' approach of querying data directly at the source.
Providing metadata about available data tables and fields to help with the discovery and understanding of cloud resources and attributes.

I think Steampipe's dashboards (Mods) make Steampipe more powerful. They offer a variety of them, such as AWS Well-Architected, AWS Compliance, and many more.

If you look for an inventory, you can check how to build your dashboard.

StackQL

Like Steampipe's revolutionary approach, StackQL harnesses the power of SQL to query your resources seamlessly. Moreover, it empowers you to utilize SQL syntax for querying and creating resources.

INSERT INTO aws.s3.buckets (bucket, region)  
SELECT 'stackql-demo',  
'eu-central-1'

It is versatile and usable. Even though it is written in Go, they provide a Python package, which means you can use it with Jupyter Notebooks. I also like their guide on using it with Superset.
In comparison to Steampipe, you can query all AWS services, whereas Steampipe is missing some. However, Steampipe offers autocompletion, which StackQL not have.

I used this instruction to create the inventory of my AWS account.

ChatWithCloud

Thanks to a generative AI model, ChatWithCloud allows users to interact with and manage their AWS cloud infrastructure using natural language commands in their terminal. Some key capabilities mentioned include:

Performing cost analysis to find out spending and optimize costs
Conducting security analysis by reviewing IAM policies and resources
Troubleshooting infrastructure issues to understand problems and how to fix them
Having the ability to fix infrastructure issues directly through commands
There is no need for AWS knowledge or API keys to use most basic functions

So, in summary, ChatWithCloud provides a natural language interface for viewing, analyzing, and troubleshooting AWS resources with the help of an AI assistant.
You must buy a license and use your OpenAI key or subscribe to it.

Conclusion

All these tools provide a comprehensive overview of your AWS resources. Komiser also displays costs, while ChatWithCloud provides answers by entering prompts. Steampipe and StackQL use SQL to interact with the cloud. Additionally, you can connect these to dashboards to visualize them, similar to any data analytics process.

Bonus: Create Inventory with AWS Console ¹

The tools above offer dynamic monitoring of your AWS resources. But what if you need inventory just once or less frequently? The following steps allow you to create a CSV of all the resources within your account:

Use the Resource Group & Tag Editor.
Choose the regions from which you want to fetch. The more regions you select, the longer it will take.
Then download them.

https://bobbyhadz.com/blog/aws-list-all-resources ↩

Developing your own Chrome Extension - Fetch with a Proxy and Cloudflare Workers (Part 5)

JoLo — Sun, 03 Mar 2024 11:00:00 +0000

In the last part, we encountered a problem. The content_script cannot skip the CORS and fetch the content outside the host where the script got injected.
That is why I came up with the idea of my server, a.k.a. a proxy.

However, choosing an HTTP Server can be a difficult task. While Bun has an in-built HTTP Server, deploying it can be challenging. Although you can wrap it into a Docker file, there are multiple ways to deploy it, which can be confusing.

In this part, I chose Cloudflare Workers because of its Serverless Edge functions and ease of deployment. Furthermore, the DX is excellent.

Cloudflare Workers as Proxy

The idea got extended. The content_script will call the Cloudflare Worker and fetch the entire content (see below).

Let's get started:

bun install wrangler @cloudflare/workers-types

Change the package.json

{
...
  "scripts": {
    "server": "wrangler dev scripts/server.ts",
    "deploy": "wrangler deploy --minify src/index.ts"
  }
...
}

The Wrangler, Cloudflare's Developer Platform command-line interface (CLI), allows you to manage Worker projects and has an in-built Miniflare, which runs an HTTP server.

Let's create an HTTP server server.ts

// in server.ts
export default {
  fetch(request: Request, env: Env, ctx: ExecutionContext) {
    return new Response(null, {
        status: 200,
    });
  },
}

In comparison, the Bun HTTP server looks similar.
export const server = Bun.serve({
  async fetch(req) {
    return new Response(null, { status: 200 });
  },
});
Let's run the server.
bun server
Now, the server is running on http://localhost:8787 and we need to adjust the scraper.ts.
const response = await fetch('http://localhost:8787', {
  method: 'POST',
  body: JSON.stringify({ link }),
  headers: {
    'Content-Type': 'application/json',
  },
  mode: 'no-cors'
});
Here we do a POST request to our Worker and post a {"link": "link"}. With that, we adjust the Worker:
export default {
    async fetch(req: Request) {
        if (req.method === 'POST') {
          const link: { link: string } = await req.json();
          const foo = await fetch(link.link);
          const bar = await foo.text();
          const res = new Response(bar, {
            status: 200,
            headers: {
              'Access-Control-Allow-Origin': '*', // Allow requests from all origins
              'Access-Control-Allow-Methods': 'POST', // Specify allowed methods
              'Access-Control-Allow-Headers': 'Content-Type', // Specify allowed headers
            },
          });
          console.log('In Server', res);
          return res;
        }
    }
}
Now, we are using a Cloudflare Worker as a proxy to obtain the content of any website, effectively avoiding CORS. However, we need to ensure its security since the URL is public.

Adding Hono

This is the default version of Cloudflare Workers, which adopts the HTTP fetch standard. But honestly, I don't like this syntax, and we can do better. Here, I would like you to introduce Hono.
Hono is a fast, lightweight framework optimized for the edge, which runs on any JavaScript runtime, embraces web standards, and offers a better Developer Experience. For example, it offers a Router. Let's see what it looks like with our code:
import { Hono } from 'hono';

const app = new Hono();

app.post('/', async (c) => {
const link: { link: string } = await c.req.json();

const foo = await fetch(link.link);
const bar = await foo.text();

return new Response(bar, {
status: 200,
headers: {
'Access-Control-Allow-Origin': '*', // Allow requests from all origins
'Access-Control-Allow-Methods': 'POST', // Specify allowed methods
'Access-Control-Allow-Headers': 'Content-Type', // Specify allowed headers
},
});
});

With that, we can easily add new APIs, and it is more readable.
Hono also comes with more features. One feature we will use in the next section is **authentication**.
### Adding a Bearer Token
Alternatively, we could set up [Lucia](https://lucia-auth.com/). But Hono has an in-built [authentication middleware](https://hono.dev/middleware/builtin/bearer-auth).
```ts
import { Hono } from 'hono';
import { bearerAuth } from 'hono/bearer-auth';

const app = new Hono();

const token = 'honoiscool';

app.post('/', bearerAuth({ token }), async (c) => {
  const link: { link: string } = await c.req.json();

  const foo = await fetch(link.link);
  const bar = await foo.text();

  return new Response(bar, {
    status: 200,
    headers: {
      'Access-Control-Allow-Origin': '*', // Allow requests from all origins
      'Access-Control-Allow-Methods': 'POST', // Specify allowed methods
      'Access-Control-Allow-Headers': 'Content-Type', // Specify allowed headers
    },
  });
});

That's it. Now, we can only access this API endpoint when there is a valid Bearer Token

// in scraper.ts

export async function getPage(link: string) {

  try {

    const response = await fetch('http://localhost:8787', {

        method: 'POST',

        body: JSON.stringify({ link }),

        headers: {

            'Content-Type': 'application/json',

            Authorization: 'Bearer honoiscool',

        },

    });

  }

}

Adding CORS

Please note that CORS restricts any other domain outside of the origin (in this case, localhost) from loading resources. Since the Chrome extension is injected into a page, it obtains the website's origin. For instance, if the extension is used on medium.com, the origin is medium.com, outside of where the server is running (localhost). To enable an external origin to call this server, we can utilize Hono's CORS middleware.

// in server.ts

import { cors } from 'hono/cors';

const app = new Hono();

app.use('/', cors());

Conclusion

As part of the series, we have created our own server to avoid CORS. To achieve this, we combined Cloudflare Workers with Hono, a framework that provides useful middleware like cors and authentication, enhancing the developer experience. We plan to replace the currently hardcoded Bearer Token with a Google OAuth module in the upcoming part.

Find the repository here.

Thanks for reading, and stay tuned!

Developing your own Chrome Extension - Fixing Errors with ts-morph and using Buns API (Part 4)

JoLo — Sun, 03 Mar 2024 09:10:00 +0000

Oh geez… Developing a Chrome Extension is hard. If you haven't seen my previous post, please take a look.

In this update, we'll be addressing an error where injected JavaScript into a Chromium-based platform can't read a class declaration that comes after initialization.

Idea

A little recap: here is what we want to build

What’s the Error?

It took me a while to figure out what happened until I played a round with the resulting package. I noticed that a class named BasePromptTemplate was being declared after it had already been used by another class called BasePromptStringTemplate. To fix this issue, the solution would be to move the declaration of BasePromptTemplate above the declaration of BasePromptStringTemplate.

The same happens with BaseChain.

Using `ts-morph`

Whenever you execute bun dev, all the classes and functions from external packages are compiled into a single index.js.

Here is the idea:

Find the class declaration
Get the full declaration
Find its first reference
Get the full declaration of the reference
Replace the 4. with 2. + 4.
Remove 2.

I recently came across an incredibly powerful tool called ts-morph. It's an Abstract Syntax Tree (AST) code analyzer and manipulator that can easily locate class declarations and their references. Just remember, it only works on TypeScript files. To use it, we created a new "build.ts" file and harnessed the full potential of Bun's API. Because ts-morph only understands TypeScript files, we bundled our files accordingly.

// in build.ts
import Bun from "bun";

// First step to bundle all the files
await Bun.build({
  entrypoints: ["./src/index.ts"],
  outdir: "./out",
  naming: "[name].ts",
});

Now, we start using ts-morph by adding a new project and reading the bundled index.ts inside out- folder. And then, we use their API to get the BasePromptTemplate- class and the getText() gets us the full declaration of this class.

import { Project } from "ts-morph";

const project = new Project();
const file = project.addSourceFileAtPath("out/index.ts");
const basePromptTemplate = file.getClass("BasePromptTemplate") // 1. Find the class
const basePromptTemplateDeclaration = basePromptTemplate?.getText(); // 2. Get the Full Declaration

Now, we want to navigate to the first reference and get its full declaration of the reference. The findReferencesAsNodes gives us enough information, but the findReferences¹

import { SyntaxKind } from 'ts-morph';

const references = basePromptTemplate.findReferencesAsNodes();
const firstUsage = references[0]
const firstReferenceUsage = firstUsage.getFirstAncestorByKind(
  SyntaxKind.ClassDeclaration,
); // This gives me the class declaration of the first usage
const firstReferenceUsageClassName = firstReferenceUsage?.getName(); // 3. Find its first reference
if(!firstReferenceUsageClassName) throw new Error('No First Reference');
const firstReferenceClass = file.getClass(firstReferenceUsageClassName);
const firstReferenceClassDeclaration = firstReferenceClass.getText(); // 4. Get full declaration

The next step is to bring the basePromptTemplateDeclaration before the firstReferenceClassDeclaration. For that, we use the replaceWithText- function, we remove the basePromptTemplateClass, and save it.

firstReferenceClass.replaceWithText(
  `${basePromptTemplateDeclaration}\n${firstReferenceClassDeclaration}`,
);
basePromptTemplateClass.remove();
file.saveSync();

And now the same for the BaseChain…

Instead of doing that, we will put that into a function and refactor a bit

function hoistClassUptoFirstUsage(targetClassName: string) {
  const targetClass = file.getClass(targetClassName);
  if (!targetClass) return;

  const targetClassText = targetClass.getText();
  const references = targetClass.findReferencesAsNodes();

  if (references.length === 0 || !targetClassText) return;

  const firstUsage = references[0];
  const firstReferenceUsage = firstUsage.getFirstAncestorByKind(
    SyntaxKind.ClassDeclaration,
  );

  if (!firstReferenceUsage) return;

  const firstReferenceUsageClassName = firstReferenceUsage.getName();
  if (!firstReferenceUsageClassName) return;

  const firstReferenceClass = file.getClass(firstReferenceUsageClassName);
  if (!firstReferenceClass) return;

  const firstReferenceClassDeclaration = firstReferenceClass.getText();
  firstReferenceClass.replaceWithText(
    `${targetClassText}\n${firstReferenceClassDeclaration}`,
  );

  targetClass.remove();
  file.saveSync();
}

hoistClassUptoFirstUsage("BasePromptTemplate");
hoistClassUptoFirstUsage("BaseChain");

Final step- Bundling again

Since the bundled file is in TypeScript, we must bundle it back to index.js. At this point, we can also bundle the popup.ts.

Furthermore, we can also get rid of the out- folder. For that, we use Bun’s in-built $- Shell (no, it’s not jQuery 🤭).

await Bun.build({
  entrypoints: ['./out/index.ts', './src/popup.ts'],
  outdir: './dist',
  naming: '[name].[ext]',
});

await $`rm -rf out`;

Add Watcher

Now, we need to bundle whenever there is a change in the directory. I took the example from Bun’s instruction on how to watch a directory for changes in Bun. I used it without recursive- option and should watch the src- folder

import { watch } from 'fs';

watch('src', async (event, filename) => {
  console.log(`Detected ${event} in ${filename}`);

  // First step to bundle all the files
  await Bun.build({
    entrypoints: ['./src/index.ts'],
    outdir: './out',
    naming: '[name].ts',
  });

  hoistClassUptoFirstUsage('BasePromptTemplate');
  hoistClassUptoFirstUsage('BaseChain');

  await Bun.build({
    entrypoints: ['./out/index.ts', './src/popup.ts'],
    outdir: './dist',
    naming: '[name].[ext]',
  });

  await $`rm -rf out`;
});

Adjust the Script part

The index.js will now be bundled by the build.ts . Until now, we used the CLI, but now we need to run bun run build.ts. So, we need to adjust the package.json and add a new script.

{
"scripts": {
    "dev": "bun run --watch build.ts",
    "build": "bun run build.ts"
  }
}

The —watch - flag executes the command whenever there are changes on the file. That’s really handy whenever we change something on the build.ts .

The Full `build.ts`

Here is the full build.ts

import Bun, { $ } from "bun";
import { Project, SyntaxKind } from "ts-morph";
import { watch } from "fs";

/**
 * The function hoistClassUptoFirstUsage moves a target class to the first usage within its parent
 * class.
 * @param {string} targetClassName - The `targetClassName` parameter is a string that represents the
 * name of the class that you want to hoist up to its first usage.
 * @returns nothing (undefined) if any of the following conditions are met:
 * - The target class with the specified name does not exist in the file.
 * - There are no references to the target class in the file.
 * - The target class text is empty or undefined.
 * - The first usage of the target class does not have a parent class declaration.
 * - The parent class declaration does not have a name
 */
function hoistClassUptoFirstUsage(targetClassName: string) {
  // Start Ts-morph
  const project = new Project();
  const file = project.addSourceFileAtPath("out/index.ts");
  const targetClass = file.getClass(targetClassName);
  if (!targetClass) return;

  const targetClassText = targetClass.getText();
  const references = targetClass.findReferencesAsNodes();

  if (references.length === 0 || !targetClassText) return;

  const firstUsage = references[0];
  const firstReferenceUsage = firstUsage.getFirstAncestorByKind(
    SyntaxKind.ClassDeclaration,
  );

  if (!firstReferenceUsage) return;

  const firstReferenceUsageClassName = firstReferenceUsage.getName();
  if (!firstReferenceUsageClassName) return;

  const firstReferenceClass = file.getClass(firstReferenceUsageClassName);
  if (!firstReferenceClass) return;

  const firstReferenceClassDeclaration = firstReferenceClass.getText();
  firstReferenceClass.replaceWithText(
    `${targetClassText}\n${firstReferenceClassDeclaration}`,
  );

  targetClass.remove();
  file.saveSync();
}

export async function build() {
  await Bun.build({
    entrypoints: ["./src/index.ts"],
    outdir: "./out",
    naming: "[name].ts",
  });

  hoistClassUptoFirstUsage("BasePromptTemplate");
  hoistClassUptoFirstUsage("BaseChain");

  const result = await Bun.file('out/index.ts').text();
  await Bun.write('dist/index.js', result);

  await Bun.build({
    entrypoints: ["./src/popup.ts"],
    outdir: "./dist"
  });

  const remove = await $`rm -rf out`;
  console.log(remove.exitCode === 0 ? "Bundled sucessfully" : remove.stderr);
}

watch("src", async (event, filename) => {
  console.log(`Detected ${event} in ${filename}`);

  await build();
});

Now, when you run bun dev it should wait until you change the file.

There is a slight issue if you only want to build the index.ts. Currently, the extension is built only when there are changes in the src folder. We need to add a new file watch.ts with the following to change that.

import { watch } from "fs";
import { build } from "./build";

watch("src", async (event, filename) => {
  console.log(`Detected ${event} in ${filename}`);

  await build();
});

And remove that from the build.ts and use build() instead.

Another issue

Are we done now? Unfortunately, not yet. Here is another problem

This most likely happened because the script cannot call an external page.

Conclusion

Creating a Chrome Extension can be challenging, but it can become easier with the right tools and techniques. We addressed a class initialization error in a Chromium-based platform using the ts-morph tool and discussed automating the bundling process. However, calling an external page remains an issue. This project requires patience, perseverance, and a willingness to learn. But the end result is rewarding.

We will add a proxy to address this issue in the next post.

Find the repository here .

Stay tuned!

https://ts-morph.com/navigation/finding-references ↩

Developing your own Chrome Extension with OpenAI and Langchain (Part 3)

JoLo — Sat, 02 Mar 2024 22:00:48 +0000

Now, it’s time to parse the external website and add AI.

Idea

This is the idea of the project

Parsing Websites

Or you can even call it scraping 🫢

We can get the HTML by using the fetch function and then parse it via cheerio as it can parse HTML and manipulate it:



export function parseHtml(html: string): string {
  const $ = cheerio.load(html);
  const content: string = $('article').text() || $('main').text() || $('body').text();
  return content.trim();
}

As you can see, we parse only the content of article with fallback to main or body .

The fetch function is here:



export async function getPage(link: string) {
  console.log('Start scraping and fetching', link);
  try {
    const response = await fetch(link, {
      headers: {
        'Access-Control-Allow-Origin': '*',
      },
      mode: 'no-cors',
    });
    if (response.ok) {
      const html = await response.text();
      return html;
    }
  } catch (error) {
    console.error(error);
    throw new Error(`Error fetching ${link}: ${error}`);
  }
}

export async function getPageContent(link: string) {
  const html = await getPage(link);
  const content = html ? parseHtml(html) : '';
  return content;
}

Adding AI to it

Okay, we got the text and want to leverage a Large Language Model (LLM) to summarize it. The most popular one is OpenAIs GPT, but I also considered Ollama for local development. For now, let’s go with OpenAI.

But if you use OpenAI solely, then streaming is quite a pain. What also is complicated is managing the tokens. For these, we have two options.

Using Vercel’s AI
Use Langchain

Calculating the tokens is especially hard, so you should use one of the libraries above.

Vercel’s AI SDK

The Vercel AI SDK is an open-source library designed to help developers build AI-powered user interfaces, particularly for creating conversational, streaming, and chat user interfaces in JavaScript and TypeScript.

We will use their OpenAIStream , and StreamingTextResponse because it offers streaming, which is much better than the OpenAI module. And why reinvent the wheel, right?

LangChain

LangChain simplifies the development of Large Language Model (LLM) applications by offering a modular framework that allows developers to quickly build complex LLM-based applications through composition and modularity, providing standardized interfaces, prompt management, and memory capabilities, and enabling seamless integration with various data sources, thus streamlining the process of crafting LLM-based applications.

We will use it mainly for splitting long text into chunks. It might be that we could use LangChain also for streaming the response.

Create Options popup

If you have followed my previous blog posts, you should be familiar with the manifest.json . We add a default_popup in there.



{
  "manifest_version": 3,
  "name": "Link previewer",
  "version": "0.0.1",
  "description": "It sneak preview the link by mouse hovering and show key facts using OpenAI GPT model.",
  "icons": {
    "16": "images/icon-16.png",
    "32": "images/icon-32.png",
    "48": "images/icon-48.png",
    "128": "images/icon-128.png"
  },
  "content_scripts": [{
    "js": ["dist/index.js"]
  }],
  "action": {
    "default_popup": "popup.html"
  }
}

The purpose of this Popup is to enter the OpenAI- token. Here is the popup.html



<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Link previewer Options Page</title>
  </head>

  <body>
    <style>
      #popup {
          display: flex;
          justify-content: center;
          align-items: center;
          min-width: 220px;
          height: 300px;
          background-color: #f5f5f5;
      }
    </style>
    <div id="popup"></div>
    <!-- We bundle that inside the dist folder -->
    <script type="module" src="dist/popup.js"></script>
  </body>
</html>

Here is the Popup.tsx with preact.



import * as React from 'preact';

export default function Popup() {

    const saveOpenAi = () => {
        const openaiApiKey = document.querySelector<HTMLInputElement>('input[name="openai-api"]')?.value;
        chrome.storage.sync.set({ openaiApiKey }, () => {
            console.log('Value is set to ', openaiApiKey);
        });
    }
    return (
        <div class="openai-api-key-form">
            <h3>OpenAI API Key</h3>
            <input onClick={saveOpenAi} type="text" placeholder="Enter your OpenAI API key" name="openai-api" />
        </div>
    );
}

But I recommend using VanJS because the bundle size will be much smaller. I also used their VanUI for a Toast message.



import van from 'vanjs-core';
import { MessageBoard } from 'vanjs-ui';

const { h3, div, input, button } = van.tags;

const board = new MessageBoard({ top: '20px' });

const Form = () => {
  const divDom = div({ class: 'openai-api-key-form' }, h3('OpenAI API Key'));
  const inputDom = input({
    type: 'text',
    id: 'openai-api',
    placeholder: 'Enter your OpenAI API Key',
  });
  van.add(
    divDom,
    inputDom,
    button(
      {
        onclick: () => {
          // Set the OpenAI key to the Chrome Storage key
          chrome.storage.sync.set({
            openai: inputDom.value,
          });
          board.show({ message: 'Added your OpenAI Key', durationSec: 2 });
        },
      },
      'Add',
    ),
  );
  return divDom;
};

document.addEventListener('DOMContentLoaded', () => {
  const popup = document.getElementById('popup');
  popup ? van.add(popup, Form()) : null;
});

Let’s add Vercel’s AI

First, run bun add ai openai . Then, we create a new file openai.ts , and we need to get the OpenAI-Key. Luckily, we can use the chrome.storage- Object.



// openai.ts
let openai: OpenAI;

chrome.storage.sync.get(['openai'], (result) => {
  const openAIApiKey = result.openai;
  openai = new OpenAI({
    apiKey: openAIApiKey,
    dangerouslyAllowBrowser: true, // This allows it to use in the Chrome Extension
  });
});

That snippet gets the openai key from the storage. But it only gets the OpenAI key whenever the extension is loaded for the first time. What if the user changes the key? Luckily, we can listen to the event whenever the storage changes.



// in openai.ts
chrome.storage.onChanged.addListener((changes, area) => {
  if (area === "sync" && changes.openai) {
    const openAIApiKey = changes.openai.newValue;
    openai = new OpenAI({
      apiKey: openAIApiKey,
      dangerouslyAllowBrowser: true, // because we will use OpenAI directly inside the browser
    });
  }
});

Let’s write a function where we take a text as input and create a prompt. That function uses OpenAI along with Vercel’s AI and returns back a ReadableStream.



export async function getSummary(text: string) {
  try {
    // We do some clean up
    const cleanText = text
      .replaceAll('`', '')
      .replaceAll('$', '\\$')
      .replaceAll('\n', ' ');

    const promptTemplate = `
    I want you to act as a text summarizer to help me create a concise summary of the text I provide.
    The summary can be up to 2 sentences, expressing the key points and concepts written in the original text without adding your interpretations.
    Please, write about maximum 200 characters.
    My first request is to summarize this text – ${cleanText}.
    `;
    // This is OpenAI's way to create messages
    const completion = await openai.chat.completions.create({
      model: 'gpt-3.5-turbo',
      messages: [{ role: 'assistant', content: promptTemplate }],
      stream: true, // Turn on the stream
    });

    // Convert the response into a friendly text-stream
    const stream = OpenAIStream(completion);

    // Respond with the stream
    const response = new StreamingTextResponse(stream);
    if (response.ok && response.body) {
      return response.body;
    }
  } catch (error) {
    console.error(error);
    return '<b>Probably, too big to fetch </b>';
  }
}
```

Now, let’s call that function. I hope you still have the `index.ts` from the previous part of this series.

```typescript
// index.ts
import { getSummary } from "./openai.ts";
import { getPageContent } from "./scraper.ts";

// Find the code in the prev part
for (const link of links) {
  link.addEventListener("mouseenter", async (event: MouseEvent) => {
    const timer = setTimeout(async () => {
      // Find the code in the prev part
      const externalSite = await getPageContent(link.href);
      const summary = await getSummary(externalSite); // <-- New function
      if (
        summary === undefined &&
        summary === "<b>Probably, too big to fetch </b>"
      )
        return;
    }, 3000);
    // Find the code in the prev part
  });
}
```

Okay, our summary is now of type `ReadableStream` if we don’t get the message `<b>Probably, too big to fetch</b>`.

Now, we create another function inside the `openai.ts` to read the stream

```typescript

// declare function getSummary()

export async function readFromStream(
  stream: ReadableStream,
  url: string,
): Promise<string> {
  let result = '';
  const reader = stream.getReader();
  const decoder = new TextDecoder();
  const container = document.querySelector<HTMLElement>(`[data-url="${url}"]`);

  try {
    while (true) {
      const { done, value } = await reader.read();
      if (done) {
        break;
      }
      const chunk = decoder.decode(value);
      for (let i = 0; i < chunk.length; i++) {
        await new Promise((resolve) => setTimeout(resolve, 10)); // Adjust the delay as needed
        result += chunk[i];
        if (container) {
          container.style.height = 'auto';
          container.textContent += chunk[i];
        }
      }
    }
    return result;
  } catch (error) {
    console.error(error);
    return '<b>Probably, too big to fetch </b>';
  }
}
```

On line 11, we retrieve the tooltip element to display the result. Line 10 fetches the stream reader and reads all the streams (line 15). Since the data is encoded, we must decode it (line 19) and then iterate over each chunk, essentially each character. To create a typing animation effect, we introduce an artificial delay of 10ms (which can be adjusted per your requirement) and then append it to the tooltip element.

![Tooltip functionality](https://assets.vrite.io/646ce5fc07ef9ba4530fd23b/7CaacNjdpEtKhLETygSW3.gif)

Unfortunately, there is a limit. With OpenAI, you only have a limit of tokens of 4096 you can send.

![Error when reaching too many tokens](https://assets.vrite.io/646ce5fc07ef9ba4530fd23b/AgBwD5rTLvmfO1V-g9f5M.gif)

Luckily, we can use [LangChain](https://langchain.com/) here.

## How to deal with long texts

We have to change the strategy a bit. There are two ways, and all involve using [LangChain](https://python.langchain.com/docs/get_started/introduction):
1. We split the text into chunks and summarize each chunk to shrink so that the result fits the number of tokens
2. We use LangChains [Chain Summarizer](https://js.langchain.com/docs/modules/chains/additional/analyze_document) to summarize it first and then send the summary to OpenAI along with our prompt.

I prefer the latter, so let’s continue.

![Adjusting the idea by adding Langchain](https://assets.vrite.io/646ce5fc07ef9ba4530fd23b/Bi5TTP7RuWVs0kYu21KZi.png)

### Split the Text into Chunks

Since we extract the whole content from the website, we take the `cleanText` and use the `RecursiveCharacterTextSplitter`. In general, I followed [their instruction on their official documentation](https://js.langchain.com/docs/modules/chains/popular/summarize).

```typescript
const textSplitter = new RecursiveCharacterTextSitter({
  chunkSize: 1000,
});
const docs = await textSplitter.createDocuments([cleanText]);
```

### Use LangChains summarization function

LangChain has a built-in function to summarize the text, `loadSummarizationChain`, which requires an LLM. Since we have a function `readFromStream`, we can stream the result from the `loadSummarizationChain`. And the rest stays as it is

```typescript
const llm = new OpenAI({
  openAIApiKey,
  streaming: true,
});

const summarizeChain = loadSummarizationChain(llm, {
  type: "map_reduce",
});

const stream = (await summarizeChain.stream({
  input_documents: docs,
})) as ReadableStream;

// Respond with the stream
const response = new StreamingTextResponse(stream);
if (response.ok && response.body) {
  return response.body;
}
```

### Modifikation on `readFromStream`

```javascript
export async function readFromStream(/* Parameters */) {
  // -  const decoder = new TextDecoder();
  // +
  // - const chunk = decoder.decode(value);
  // +
  const chunk = value.text;
}
```

Apparently, the `OpenAI` of LangChain differs from that `OpenAI` of Vercel’s AI SDK.

## Let’s build

Okay, let’s build everything

```sh
bun build src/index.ts --outfile dist/index.js --outdir dist &\
bun build src/popup.ts --outfile dist/popup.js --outdir dist
```

But the `index.js` throws an error 🤔

![ReferenceError that BasePromptTemplate before initialization](https://assets.vrite.io/646ce5fc07ef9ba4530fd23b/Bk-mm1xZgmOjCSdP9aDr3.png)

`Uncaught ReferenceError: Cannot access ‘BasePromptTemplate’ before initialization` It seems like Chrome does not hoist classes or functions of JavaScript Extensions 🤪

I couldn’t find a way how to change that in Bun. That’s why I had to script it myself.

## Conclusion

In conclusion, this project involves parsing an external website and using AI to summarize its content. We explored different options for leveraging OpenAI’s Large Language Model (LLM) and used Vercel's AI SDK for its streaming capabilities. We also discussed strategies for dealing with long texts, such as splitting the text into chunks or using LangChain's summarization function. This part of the series also shows how to create a popup for entering the OpenAI token and how to handle limitations on the number of tokens that can be sent. Finally, we encountered an error when building the project and will explore ways to fix it in the next part

Find the repository [here](https://github.com/jolo-dev/worth-the-click).

In the next part, I will try to fix that error.

Developing your own Chrome Extension in Bun and Typescript (Part 2)

JoLo — Sat, 02 Mar 2024 21:43:45 +0000

In the previous part of the series, we learned about the structure of building a Chrome extension. We are ready to build and structure our first Chrome Extension with that knowledge. Let’s get started.

Idea

This is the idea of the project

Getting Started

First, we create an empty directory with a manifest.json. Initially, we want to inject a script to the current page in the tab by using content_scripts.



{
  "manifest_version": 3,
  "name": "Link previewer",
  "version": "0.0.1",
  "description": "It sneak preview the link by mouse hovering and show key facts using OpenAI GPT model.",
  "icons": {
    "16": "images/icon-16.png",
    "32": "images/icon-32.png",
    "48": "images/icon-48.png",
    "128": "images/icon-128.png"
  },
  "content_scripts": [{
    "js": ["dist/index.js"]
  }]
}

Note that I started with a dist/index.js. This is where we put the bundled code into. For now, let’s create a src/index.ts. Now, we can add Bun by bun init . It will ask if you want to use Typescript. Go ahead and use it. Then, we need to adjust the package.json.



{
  // ..
  "scripts": {
    "dev": "bun build --watch src/index.ts --outfile dist/index.js"
  }
  // ..
}

We want to plan Typescript, so let’s install it: bun install -D chrome-types.
Now, we need to add the types to the tsconfig.json



{
  // tsconfig.json
  // ..
  "types": ["chrome-types"]
}

We need that chrome- object. Otherwise, our IDE may yell at me.

If you enter their code from their Chrome Extension Getting Started page, Typescript reveals so many errors🫢

Developing

Okay, it’s time to get our hands dirty. Before that, we need to load an unpacked extension:

Open chrome://extensions in a new tab
Enable the Developer Mode and click on the Load unpacked

Now, go to the directory of your extension and click on the reload button

You need to reload the extension every time you change, which is quite annoying. Extension Reloader is another extension that can do that for you.

Start Bun

Do you remember the scripts in the package.json from above? First, you get Hot Module reloading whenever a change happens on that file. Second, Bun is bundling the index.ts to index.js and put it into the dist- folder.



bun dev

Add a listener on each link

From our idea, we want to show a tooltip whenever we hover over a link on that page. In doing that, we have to add a listener.



const links = document.querySelectorAll('a')

console.log(links) // Debugging purpose

Go ahead and console.log it and check the links. The querySelectorAll returns a list of Anchor elements.
But here is a little problem. We get a NodeList that is not iterable, and what if an Anchor tag does not href , which we need in our case? So, let’s modify it a bit



const links = Array.from(document.querySelectorAll("a")).filter((link) =>
  link.hasAttribute("href"),
); // Create an Array from an iterable object

// to verify
links.forEach((link) => {
  console.log(link.href);
});

We can add an event listener whenever the mouse enters the link.



const links = Array.from(document.querySelectorAll('a')).filter(link => link.hasAttribute('href'));

links.forEach(link => {
    link.addEventListener('mouseenter', () => {
        console.log(link.href);
    });
});

Each link gets an event listener mouseenter whenever the mouse is entering or hovering over the link.

But what if the page has many links? On Arc, you can hold shift on a link, but it seems to be impossible with vanilla JavaScript. Let’s extend it and add a timer when the user has been on the link for 3 seconds.



const links = Array.from(document.querySelectorAll('a')).filter(link => link.hasAttribute('href'));

links.forEach(link => {
    link.addEventListener('mouseenter', () => {
        console.log(link.href);
        const timer = setTimeout(function() {
            // Here we put the logic after 3000 ms aka 3 seconds
        }, 3000); // Adjust the time (in milliseconds) as needed

        link.addEventListener("mouseleave", function() {
            // Clear the timer if the mouse leaves the link before the specified time
            clearTimeout(timer);
        });
    });
});

We execute the logic after 3 seconds via setTimeout and add another event listener when the user leaves the mouse after leaving the link.

Show the Tooltip

Now, we want to add the tooltip. The approach is that we create a tooltip element, but where to add it? What happens if we hover on the same link again?

The idea is that we create the tooltip and put the element at the bottom of the <body> .

Here, we outsource the code logic in tooltip.ts, to make it more readable. In addition, we create some listeners on the link we’ve just hovered over.



// in tooltip.ts
export function createTooltip(link: HTMLAnchorElement) {
    const tooltip = document.createElement('div');
    tooltip.classList.add('tooltip');
    tooltip.dataset.url = link.href;
    tooltip.innerHTML = 'This is a tooltip';
    document.body.appendChild(tooltip);
    createTooltipAction(link, tooltip);
    return tooltip;
}


function createTooltipAction(link: HTMLAnchorElement, tooltip: HTMLElement) {
    function onMouseEnter() {
        console.log('onMouseEnter');
    }

    function onMouseMove(event: MouseEvent) {
        console.log('onMouseMove');
        tooltip.style.backgroundColor = 'white';
        tooltip.style.color = 'black';
        tooltip.style.display = 'block';
        tooltip.style.position = 'absolute';
        tooltip.style.top = `${event.pageY - 25}px`;
        tooltip.style.left = `${event.pageX - 10}px`;
    }

    function onMouseLeave() {
        console.log('onMouseLeave');
        tooltip.style.display = 'none';
    }

    link.addEventListener('mouseenter', onMouseEnter);
    link.addEventListener('mousemove', onMouseMove);
    link.addEventListener('mouseleave', onMouseLeave);

    return {
        destroy() {
            link.removeEventListener('mouseenter', onMouseEnter);
            link.removeEventListener('mousemove', onMouseMove);
            link.removeEventListener('mouseleave', onMouseLeave);
        },
    };
}

Notice that the tooltip contains the attribute data-url={link.href} . That helps us to find the tooltip and avoid recreating it.



// in index.ts
import { createTooltip } from './tooltip';

const links = Array.from(document.querySelectorAll('a')).filter(link => link.hasAttribute('href'));

links.forEach(link => {
    link.addEventListener('mouseenter', () => {
        const tooltip = document.querySelector<HTMLElement>(
          `[data-url="${link.href}"]`,
        );
        if (tooltip === null) {
          createTooltip(link);
        }
    });
});

Let’s add a nice skeleton animation when the tooltip appears



// tooltip.ts
export function createTooltip(link: HTMLAnchorElement) {
    // ...
    createTooltipSkeleton();
    return tooltip;
}

function createTooltipSkeleton() {
    let linkElement = document.createElement("style");
    linkElement.innerHTML = `
      .tooltip {
        width: 220px;
        height: 80px;
        border-radius: 5px;
      }
      .tooltip .avatar {
        float: left;
        width: 52px;
        height: 52px;
        background-color: #ccc;
        border-radius: 25%;
        margin: 8px;
        background-image: linear-gradient(90deg, #ddd 0px, #e8e8e8 40px, #ddd 80px);
        background-size: 600px;
        animation: shine-avatar 1.6s infinite linear;
      }
      .tooltip .line {
        float: left;
        width: 140px;
        height: 16px;
        margin-top: 12px;
        border-radius: 7px;
        background-image: linear-gradient(90deg, #ddd 0px, #e8e8e8 40px, #ddd 80px);
        background-size: 600px;
        animation: shine-lines 1.6s infinite linear;
      }
      .tooltip .avatar + .line {
        margin-top: 11px;
        width: 100px;
      }
      .tooltip .line ~ .line {
        background-color: #ddd;
      }

      @keyframes shine-lines {
        0% {
          background-position: -100px;
        }
        40%, 100% {
          background-position: 140px;
        }
      }
      @keyframes shine-avatar {
        0% {
          background-position: -32px;
        }
        40%, 100% {
          background-position: 208px;
        }
      }
      `;
    // Append the link element to the head of the document
    document.getElementsByTagName("head")[0].appendChild(linkElement);
}

At this point, we can ask if a framework like React or Vue is not a better choice for better maintenance. But since we use Bun, it is supposed to bundle .tsx files out of the box. That is unfortutately not the case as you need a third party library such as React or Preact. I chose the latter: bun add -D preact and adjust the tsconfig.json :



{
  "compilerOptions": {
    // ...
    /* Preact */
    "jsx": "react-jsx",
    "jsxImportSource": "preact",
    "baseUrl": "./",
    "paths": {
      "react": ["./node_modules/preact/compat/"],
      "react-dom": ["./node_modules/preact/compat/"]
    }
  }
}

Now, we can rewrite the Tooltip.tsx:



import * as React from "preact";

export default function Tooltip(props: { link: HTMLAnchorElement }) {
  console.log("Tooltip", props.link.href);
  const tooltip = React.createRef();
  createTooltipSkeleton();
  function onMouseMove(event: MouseEvent) {
    console.log("onMouseMove");
    tooltip.current.style.backgroundColor = "white";
    tooltip.current.style.color = "black";
    tooltip.current.style.display = "block";
    tooltip.current.style.position = "absolute";
    tooltip.current.style.top = `${event.pageY - 100}px`;
    tooltip.current.style.left = `${event.pageX - 100}px`;
  }

  function onMouseLeave() {
    console.log("onMouseLeave");
    tooltip.current.style.display = "none";
  }

  props.link.addEventListener("mousemove", onMouseMove);
  props.link.addEventListener("mouseleave", onMouseLeave);
  return (
    <div className="tooltip" data-url={props.link.href} ref={tooltip}>
      <div className="avatar"></div>
      <div className="line"></div>
      <div className="line"></div>
    </div>
  );
}

The compiler complains if we don’t import React somewhere as if JSX is only possible with React… The VS Code compiler also put React in favor when using JSX

I honestly don’t like that approach. There may be good alternatives, such as VanJS, which does not use JSX, and nanoJSX. VanJS results in a smaller bundle ( < 8kb) **but is not so nicely readable as Preact ( < 19kb**).

Anyway, I will put both codes in the repository.

The result is the same 🤩

Conclusion

The blog post discusses building a basic Chrome extension that displays a tooltip with additional information when the user hovers their mouse over web links. It covers setting up the project structure, adding Typescript for type safety, using Bun to bundle the code, selecting links and adding mouseenter listeners, conditionally displaying a tooltip after 3 seconds, creating the tooltip element and styling it, and positioning the tooltip near the mouse pointer. The post also explores using Preact to manage the tooltip component and compares it to other frameworks like VanJS and NanoJSX that could potentially reduce the bundle size. Overall, the post provides a helpful tutorial for creating a foundational Chrome extension.

Find the repository here.

Check out this repository if you decide to use another framework for your Chrome extension: https://github.com/guocaoyi/create-chrome -ext.

In the next section, we will integrate OpenAI’s SDK and explore the capabilities of Langchain.

Developing your own Chrome Extension - The Theory (Part 1)

JoLo — Sat, 02 Mar 2024 21:21:52 +0000

Google Extensions are powerful tools that enhance Chromium-based Web browsers' functionality and customization options. From blocking ads and managing passwords to organizing bookmarks and adding new functionalities to web applications, Google Extensions offers a wide range of solutions to cater to the needs and preferences of individual users.

A great place to start learning about Google Extensions is their web page. However, I've noticed that their code snippets have several bugs. Furthermore, if you prefer to work with Typescript, you'll find that there aren't any tutorials available on the topic. That's why I've started this series about developing a Chrome extension myself.

Why do I want to Develop a Google Extension?

I have an issue with the numerous newsletters that I receive. Although the titles sound interesting, I don't have enough time to read all of them.

I devised an idea to preview a summary by hovering over the link. I know that Arc Max can perform this function (I had this idea a long time ago 🫢), but it requires using Arc's browser.

In this blog post, we will create a Chrome extension allowing you to preview a link. This is A significant advantage because it will work on all Chromium-based browsers.

Anatomy

Let’s understand how an extension is structured and what files must start.

Manifest v3

The manifest is a file that defines an extension. It provides the extension's metadata and configuration. With their latest version, v3, you can run background tasks with service workers, which can also be used without a network connection by caching assets¹. Furthermore, they add more APIs².

Structure

You define the manifest in a manifest.json



{
  "manifest_version": 3,
  "name": "Minimal Manifest",
  "version": "1.0.0",
  "description": "A basic example extension with only required keys",
  "icons": {
    "48": "images/icon-48.png",
    "128": "images/icon-128.png"
  }
}

But to make it interactive via HTML or JavaScript, the manifest contains different key values to call the correct files.

content_scripts

This feature lets you add static JavaScript or CSS to the current page. You can select the specific pages where the script should run. It can manipulate the DOM, interact with page content, and listen to page events while modifying its appearance.



{
  "manifest_version": 3,
  "name": "Run script automatically",
  "description": "Runs a script on www.example.com automatically when user installs the extension",
  "version": "1.0",
  "icons": {
    "16": "images/icon-16.png",
    "32": "images/icon-32.png",
    "48": "images/icon-48.png",
    "128": "images/icon-128.png"
  },
  "content_scripts": [
    {
      "js": [
        "content-script.js"
      ],
      "css": ["my-styles.css"],
      "matches": [
        "http://*.example.com//"
      ]
    }
  ]
}

But: Limited access to extension APIs
But: Runs in the context of each page can cause conflicts

More information here.

background

The background key is used to specify a javascript file as the extension service worker. A service worker is a background script that acts as the extension's primary event handler. It can handle long-running processes, event handling, and communication with other extensions. Furthermore, it has a broader extension API and browser functionality³



{
  ...
   "background": {
      "service_worker": "service-worker.js",
      "type": "module"
    },
  ...
}

But: It runs continuously and may consume resources
But: Cannot directly interact with web page content

There are many other fundamental values, but content_scripts and background ensure interactivity. Check all the other keys here.

Storage

Another essential part is the storage. You can store data using Local Storage, Session Storage, or IndexedDB. This way, data will be retained even if the user clears browser data. However, the Local Storage and Session Storage can only be accessed from the content_script whereas Service workers can only access IndexedDB and Cache Storage.

If you develop an extension that contains a content script and service worker, then it’s recommended to use IndexedDB (it’s inbuilt-browser storage, so it should be available).

For more information, click here.

Conclusion

In the first part of this series, we learned why I created it and the structure of the Google Chrome Extension manifest file. It explains the basic anatomy of an extension, including the manifest file, which defines metadata and configuration. The manifest contains keys like content_scripts and background to specify JavaScript files that allow interactivity.

Forem: JoLo

Building Confidence with Testcontainers

The Classic Deployment Failure Scenario

Why Integration Tests Are Hard

What Testcontainers Solves

Example: Node.js (Bun) + Redis

Running Testcontainers in CI/CD

When to Use Testcontainers

Do we need AWS Durable Functions when we have Step Functions?

What are Durable Functions?

The Idea

Durable Function

Cannot pass another value to the Callback

Cannot use API Gateway directly in CDK

Use a Qualified ARNs requirement

Not well-structured Documentation

Confusing AWS Console

Step Functions

Conclusion

Why and how to optimize your Lambda

Why do we have a Cold Start in AWS Lambda?

Reducing the Cold Start

Reduce dependencies

Choose the right Package

Use ESM

Use CDK

Choose the optimal configuration for cost efficiency

Lambda Power Tuning

Conclusion

Oh CommonJS! Why are you mESMing with me?! Reasons to ditch CommonJS

Why Do We Need Module Systems?

The Emergence of CommonJS

The Rise of ESM (ECMAScript Modules)

CommonJS is here to stay

Comparison

Embrace ESM!

More Resources

GHosttp

Why?

Cloud Run

Opinionated

Requirements

Getting Started

Arguments

PR and contributions are welcome

What's next?

Don't (.git)ignore .vscode

Understanding the Importance of Configuration

Recommending Extensions

Code Snippets

Launching a Fully Fledged IDE

Conclusion

Cloud Tools You Probably Haven't Heard Of

Komiser

Steampipe

StackQL

ChatWithCloud

Conclusion

Bonus: Create Inventory with AWS Console 1

Developing your own Chrome Extension - Fetch with a Proxy and Cloudflare Workers (Part 5)

Cloudflare Workers as Proxy

Adding Hono

Adding CORS

Conclusion

Developing your own Chrome Extension - Fixing Errors with ts-morph and using Buns API (Part 4)

Idea

What’s the Error?

Using ts-morph

Final step- Bundling again

Add Watcher

Adjust the Script part

The Full build.ts

Another issue

Conclusion

Developing your own Chrome Extension with OpenAI and Langchain (Part 3)

Idea

Parsing Websites

Adding AI to it

Vercel’s AI SDK

LangChain

Bonus: Create Inventory with AWS Console ¹

Using `ts-morph`

The Full `build.ts`