DEV Community: Corentin Le Berre

Plasmo - a new way to create modern browser extensions

Corentin Le Berre — Thu, 07 Sep 2023 20:21:43 +0000

Context

I have had the opportunity to develop a new AI-based solution recently to enhance sellers' performance when using online conferencing platforms such as Zoom. After technical analysis, we concluded that the most effective approach is to create a browser extension for Chrome.

Okay, but how do I create a Chrome extension? Can I use React or other tools I'm accustomed to? It is entirely possible, but setting one up can be time consuming and diverge from the standard configuration. While researching how to integrate React easily into my project, I encountered Plasmo. This framework promises to supercharge your extension with a set of features that I'll detail in this article.

Introduction

Plasmo is an open-source tool with great documentation. It has a strong opinion on project architecture and configuration (no, you don't need to touch the usual manifest file). I don't think it is for everyone, but I found it pleasant to work with, especially if your codebase is growing rapidly. The team also offers SaaS for easier extension testing and deployment but is not included in today's topic.

Currently in version 0.82, Plasmo supports React, Svelte, and Vue out of the box providing live reloading and Hot Module Replacement for the ease of use. The tool makes it easy to compile the code, therefore enabling the compatibility with Chrome, Firefox and Safari, ensuring interoperability and consistency across platforms.

In this article, I'll show you how to quickly create your first Plasmo project with React and Typescript. The code will be provided on this repo.

Create your first extension

Today, we're going to work together on creating a straightforward and enjoyable Plasmo extension – something fun like replacing the 𝕏 logo with the old blue and black Twitter logo, or even using a logo of your choice. The goal is to familiarize ourselves with the sharing mechanics of storage and understand how Plasmo allows us to interact with content scripts and popups easily.

Our focus will be on the Popup and Content Script aspects. We will explore these specific components in detail (you can also interact with the Background service worker, Tabs and Options easily). Our primary attention will be paid to understanding how modifications of the popup interface should be made in popup.tsx, and how content script enhancements belong in content.tsx.

👉 Create the project

npm create plasmo plasmo-intro
cd plasmo-intro
npm run dev

You will then have the following file structure :

📦 plasmo-intro  
┣ 📂 assets  
┣ 📂 build
┣ 📜 package.json  
┣ 📜 popup.tsx
┣ 📜 README.md  
┗ 📜 tsconfig.json

Now you can load the extension in your favorite browser

👉 Customise the Popup

The popup is what shows up when you click on the extension in your browser. All the code needed can be found in popup.tsx.

This code defines an UI component that displays a set of radio buttons, each representing a different Twitter logo.

👉 Add the logic and styling

Plasmo provides utilities to ease communication between your popup, content script and the rest of your extension. We're going to add Plasmo Storage to our project to preserve a state in the browser. It will be used to pass the icon we want to display on x.com between the popup and the content script.

npm install @plasmohq/storage

more docs about Plasmo storage here

// package.json

{
  "name": "plasmo-intro",
  ...
  "manifest": {
    "host_permissions": [
      "https://twitter.com/*",
      "https://x.com/*"
    ],
    "permissions": [
      "storage"
    ]
  }
}

Browsers and Mobile apps need to explicitly declare features that you want to use for security reasons. That's why you will need to specify it in the permissions section of the manifest in the package.json.

Now we can use the useStorage hook to manipulate a preserved state in our react components.

import { useStorage } from "@plasmohq/storage/hook"

const [logo, setLogo] = useStorage("logo", "original")

To make our application more user-friendly, we can add our different SVG and custom styles in popup.tsx.

Users can now select a logo, and the chosen option will be stored and managed using the useStorage hook from the @plasmohq/storage library.

To make this code type safe you should define a type LogoType in types.ts containing all of your different logo.

Finally your popup should look like this👇

Now that we've managed the popup, we'll move on to the more important task which is to modify the x.com page.

👉 Customise the Content Script to modify x.com behaviors

To modify the integrity of a web page you will need to add the "scripting" permission to the manifest.

Plasmo manages different lifecycles to help you mount and unmount components in the content script. The global process is well described in their docs.

To make it concise, you need to create or locate an anchor on the website. In our case, it will be the x.com logo with the selector [aria-label="X"]. You can then access the local element to modify or replace it by mounting your own component.

In summary, the code below defines a custom getRootContainer function that asynchronously looks for a specific HTML, with the attribute aria-label set to "X". Once the element appears on the page, the interval is cleared and our new logo is replaced.

The SVG logos are being dynamically rendered by the components mounted on the page, based on the value that we stored in local storage using popup.tsx.

Now that everything's configured, the extension should be fully functional and will allow you to replace the x.com logo dynamically according to your preferences. The final step is to build your project and make it available to the world. 🥳

👉 Build the project

Plasmo provides the ability to build your project for different browsers, through the plasmo package command. By default, only the Chrome artifact is built.

npm run build

After the build, you will then have the following file structure :

📦 plasmo-intro  
┣ 📂 build
 ┣ 📂 chrome-mv3-dev 
 ┗ 📂 chrome-mv3-prod

Finally, you can zip the prod folders and share it as is or publish it on the Chrome web store.

To go further

In this article, I chose a relatively simple example to illustrate Plasmo's key features. If you're interested in the subject, I implore you to take a closer look at their well structured documentation. They also provide a Github repository with over 50 powerful templates, including Supabase, Tailwind, NextJS, Svelte, React-Router etc.

Conclusion

Plasmo shows great potential for developing modern extensions without compromising the browsing experience. It allows you to create extensions for different platforms, but you need to be aware of cross-browser API limitations. Despite some unexpected behavior in dev mode, the tool offers several benefits, including rich documentation, an active community, and simplified manifest management. Additionally, it provides SaaS for testing and deployment of extensions across different online stores. This can be very valuable for development teams.

Despite some challenges, Plasmo framework presents itself as a promising solution for the development of modern extensions!

Streamline your CI/CD Pipeline with Git-diff-script-exclusions

Corentin Le Berre — Tue, 05 Sep 2023 20:01:54 +0000

If you've ever experienced the pain of running a build pipeline or test suite only to realize that none of the modified files affected the functionality you're testing, you'll appreciate the usefulness of git-diff-script-exclusions.

This command-line interface (CLI) tool allows you to compare two git commits and see if the modified files are strictly limited to the excluded paths you've configured. If so, you can avoid running unnecessary scripts, saving valuable time in your CI pipeline.

The CLI is simple to use, and it can be installed globally or used via npx. Before running the tool, you'll need to configure the exceptions in the git-diff-script-exclusions.conf.json file. This file stores the paths to the files and directories that should be excluded from consideration.

The format is straightforward, as shown below 👇

    {
    "exceptions": [
            "docs/*",
            "git-diff-script-exclusions.conf.json"
            "src/ressource/application.yml"
        ]
    }

You can specify folders or files for exceptions, and the CLI will check whether any modified files fall within these paths.

To use the tool, simply execute the following command, replacing source_commit_sha and target_commit_sha with the relevant SHA or branch name 👇

$: npx git-diff-script-exclusions --source source_commit_sha --target targe_commit_sha

Target argument is optional, by default it will take the head of your branch.

The CLI will output the modified files in the newest commit and whether they're strictly contained within the configured exceptions. For instance, if you see onlyExceptions: true, it means the modified files are within the exceptions you've specified, and you can safely skip the script.

The tool can also be integrated into your CI pipeline. The examples below show how to use it in GitLab and GitHub Actions.

👉 GitLab

stages:
  - test

test:
  stage: test
  image:
    name: node:lts
  script:
    - npm install -g git-diff-script-exclusions
    - echo 'Checking if tests need to be executed...'
    - GIT_DIFF_SCRIPT_EXCLUSIONS=$(npx git-diff-script-exclusions --source $CI_COMMIT_SHA)
    - echo $GIT_DIFF_SCRIPT_EXCLUSIONS
    - >
      if grep -q "onlyExceptions: true" <<< "$GIT_DIFF_SCRIPT_EXCLUSIONS"; then
        echo 'Tests are not required';
      else
        echo 'Launching tests...';
        npm ci
        npm test
      fi;

👉 GitHub

name: Run Test

jobs:
  test:
    runs-on: ubuntu-latest

    steps:
    - uses: actions/checkout@v2
    - uses: actions/setup-node@v3
      with:
        node-version: 16
    - name: Install dependencies
      run: npm install -g git-diff-script-exclusions
    - name: Launch tests if needed
      run: |
        echo "Checking if tests need to be executed..."
        GIT_DIFF_SCRIPT_EXCLUSIONS=$(npx git-diff-script-exclusions --source $GITHUB_REF)
        echo $GIT_DIFF_SCRIPT_EXCLUSIONS
        if grep -q "onlyExceptions: true" <<< "$GIT_DIFF_SCRIPT_EXCLUSIONS"; then
          echo "Tests are not required"
        else
          echo "Launching tests..."
          npm ci
          npm test
        fi

If you wish to contribute to this project, you may do so as the repository is open for contributions. If you have an idea for a new feature or bug fix, please open an issue on our GitHub page. We appreciate contributions. Thank you!

Thank you for reading this article. If you need more information, feel free to check out the Git-diff-script-exclusions repo.

Enhance your Docsify experience with your own plugin

Corentin Le Berre — Mon, 09 Jan 2023 20:28:55 +0000

Docsify is a popular and lightweight documentation generator that allows you to easily create beautiful, intuitive documentation sites based on your markdown documentations. It includes features like a search function, a table of contents, and the ability to customize the look and feel of the site using templates and custom CSS. Thanks to that it's a popular choice for open-source documentation sites and other purposes.

If you want to extend Docsify's features, you can use community plugins or create your own Docsify plugin.

In this post I'll guide you to create your first Docsify plugin and deploy it to NPM.

Requirements : Node 16

To simplify the process, I've made a preconfigured workspace. To use it just clone the repository below and use it as a starting point for your own plugin 👇

npx degit corentinleberre/create-docsify-plugin my-plugin
cd my-plugin

Structure of the project

Here is the structure of this template. The code is stored in the src folder.

📦create-docsify-plugin
┣ 📂src
┃ ┣ 📂plugin
┃ ┃ ┣ 📜main.js
┃ ┃ ┗ 📜my-plugin.js
┃ ┣ 📂test
┃ ┃ ┗ 📜my-plugin.spec.js
┃ ┣ 📜README.md
┃ ┗ 📜index.html
┣ 📜package.json
┣ 📜README.md
┗ 📜vite-config.js

We use Vite as a dev server. This allows you to take advantage of hot reloading in development and easily build and minify code with Rollup integration. Vitest is also provided, so you can write tests in the matching folder.

Write your plugin

👉 Run the dev server

npm run dev

Pass props to your plugin

You can pass props to your plugin this way 👇

// src/index.html

<script>
  ...
  window.$docsify = {
      name: "My plugin documentation website",

      // props
      myPlugin: {
          hello: "world",
      },
  };
  ...
</script>

These props will be accessible through the docsify global object in your plugin 👇

// src/plugin/main.js
const docsify = window.$docsify || {};

const props = docsify.myPlugin || {};

Interact with Docsify lifecycle hooks

Docsify lifecycle hooks are provided threw the hook argument passed to the plugin function. To have more detail about lifecycle hooks check out the official doc.

You can attach your function to 6 differents lifecycle hooks allowing your to modify the state of the app.

Below is the example included in the template for this project.

const myPlugin = (props = { hello: "" }) => (hook) => hook.init(() => {
    console.log(`hello ${props.hello}`);
});

This is a function that will be called once when the Docsify script is initialized on the first load of the application. This function will simply display the parameter provided in the browser console.

The example is deliberately very simple here, but it's possible to modify the rendering of Docsify. By example you can add a button to copy and paste the current paragraph when hovering the content or add a custom footer on each page.

Detailed example

Here is a detailed example coming from the official documentation interacting with two different Hooks beforeEach and afterEach. The goal is to add an edit button and a footer to each of your page.

Replace my-plugin.js with this content 👇

const editOnGitPlugin = (props = { repoUrl }) => (hook, vm) =>
    hook.beforeEach((html) => {
      let editUrl = props.repoUrl + vm.route.file;
      let editLinkMarkdown = "[📝 Edit on Github](" + editUrl + ")\n";

      return editLinkMarkdown + html;
});

const customFooterPlugin = (props = { title, link }) => (hook) =>
    hook.afterEach((html) => {
      let footer = [
        "<hr/>",
        "<footer>",
        `<span>${props.title}</span>`,
        `<span><a href="${props.link}" target="_blank">✨</a></span>`,
        "</footer>",
      ].join("");

      return html + footer;
});

export { editOnGitPlugin, customFooterPlugin };

You may noticed that we pass the vm property to the plugin, it's the current Docsify instance. It give us access to some property as the current file rendered.

Replace main.js with this content 👇

import { editOnGitPlugin, customFooterPlugin } from "./my-plugin";

const docsify = window.$docsify || {};

const props = { editOnGitPlugin: docsify.editOnGitPlugin, customFooterPlugin: docsify.customFooterPlugin } || {};

docsify.plugins = [].concat(docsify.plugins || [], editOnGitPlugin(props.editOnGitPlugin), customFooterPlugin(props.customFooterPlugin));

Replace the Docsify script section in index.html with this content 👇

<script>
    window.$docsify = {
        name: "Docsify-plugin-playground",
        repo: "",
        editOnGitPlugin: {
            repoUrl: "https://github.com/docsifyjs/docsify/blob/master/docs/",
        },
        customFooterPlugin: {
            title: "My awesome custom footer ",
            link: "https://github.com/docsifyjs/awesome-docsify",
        },
    };
</script>

You can now see the edit button on top of the page. On click you'll be redirect to the markdown file you want to modify on your Git repo.
The second plugin add a footer providing some informations.

Here are detailed examples of plugins made that I've made using this template if you need some inspiration👇

Test your plugin

You can test your plugin using Playwright. We provide a simple test file that test the plugin function in src/my-plugin.spec.js.

👉 Run the tests

npm run test

Deploy your plugin

To deploy this package on npm, you will need to have an account on npmjs.com. Once you have an account, follow these steps:

👉 Build the project with npm run build

You have the choice to deliver it as a CommonJS, ESModule, IIFE or UMD. By default, two artifacts CJS and ESM are generated. You can modify that in vite-config.js.

📦dist
 ┣ 📜my-plugin.cjs
 ┗ 📜my-plugin.js

👉 Run npm publish

You can now access your package on npm with this url 👉 https://www.npmjs.com/package/my-docsify-plugin.

To use this package on your website we will use Jsdelivr.com. It will act as Content Delivery Network proxying your npm package enabling you to use this script directly in the browser.

You can get your plugin threw this url 👉https://cdn.jsdelivr.net/npm/my-docsify-plugin@version/dist/my-plugin.js

Now your users just have to add this url directly in their Docsify index.html page to use your plugin 👇

<script src="//cdn.jsdelivr.net/npm/my-docsify-plugin@version/dist/my-plugin.js"></script>

If you specified "main": "dist/my-plugin.js" in package.json, you could also access it directly with this url 👉 https://cdn.jsdelivr.net/npm/my-docsify-plugin@1.0.0

Conclusion

Thank you for reading this article. If you need more information, feel free to check out the Docsify's plugin documentation.

Deploy your side project in 10 minutes with Fly.io

Corentin Le Berre — Mon, 28 Nov 2022 21:29:13 +0000

In this post, I will aim on giving your the keys to deploy quickly your API online using Fly.io platform.

First, what is Fly.io ? Like classic cloud platform as AWS/GCP/Azure, Fly.io enables you to deploy your application/api/microservices/database on the cloud. But unlike these, it stands out for its simplicity.

You can deploy a lot of different technologies such as Php/Python/Deno/Node/Go etc threw automatic templates or even use a Dockerfile. It's really easy to use thanks to the CLI and documentation provided. This enables you to deploy and scale your app worldwide and close to your users without worrying about network, DNS or security. It also provides lots of metrics about your application with an integrated Graphana on your dashboard. With the free tier, you can host 2 projects.

👉 To have more details about those features just check their website

In this article, I will deploy a simple Node.js server written in Typescript, focusing only on the steps necessary for deployment. For more information feel free to consult their documentation.

Prerequisites

Have a Node environment installed and Docker if you want to test your build locally.

👉 Install fly cli tools 👇

Flyctl is a command-line utility that lets you work with the Fly.io platform, from creating your account to deploying your applications.

$: brew install flyctl

🐧$: curl -L https://fly.io/install.sh | sh

🪟$: iwr https://fly.io/install.ps1 -useb | iex

Create our app

You can clone this project on Github or copy the code below 👇

📦 Structure of the project

📦beekeeper
 ┣ 📂src
 ┃ ┗ 📜main.ts
 ┣ 📜Dockerfile
 ┣ 📜fly.toml
 ┣ 📜package-lock.json
 ┣ 📜package.json
 ┗ 📜tsconfig.json

Part 1 : Create the Node.JS API

👉 Init a npm project

$: npm init

👉 Add this configuration in package.json

{
  /***/
  "type": "module",
  "scripts": {
    "dev": "ts-node src/main.ts",
    "build": "rm -rf dist && tsc --build",
    "start": "node dist/src/main.js"
  }
  /***/
}

👉 Install dependencies

$: npm install express
$: npm install -D typescript ts-node @types/node @types/express

👉 Configure Typescript compiler in tsconfig.json

{
    "compilerOptions": {
        "module": "ESNext",
        "moduleResolution": "Node",
        "esModuleInterop": true,
        "rootDir": "./src",
        "outDir": "./dist/src",
    },
    "ts-node": {
        "esm": true
    }
}

👉 Create the express api in src/main.ts. It's a simple server made for a beekeeper that allows him to know the state of his hives. It exposes a single access point via /api/hives.

import express from "express";
import { Express, Request, Response } from "express";

const app: Express = express();
const port = process.env.PORT || 8080;

const bees = (n: number): string => Array(n).fill("🐝").join("");

const getHives = (req: Request, res: Response): void => {
  const hives = {
    "🇫🇷": bees(150),
    "🇨🇦": bees(40),
    "🇯🇵": bees(10),
  };
  res.status(200).json(hives);
};

app.get("/api/hives", getHives);

app.listen(port, () =>
  console.log(`🍯 Beekeeper is running on http://localhost:${port}`)
);

You can now run the app with npm run dev

Part 2 : Build the app with Docker

⚠️ Your Docker Daemon need to be working to execute these commands

👉 Build the image locally

$: docker build -t beekeeper .

👉 Verify if the image has been created

$: docker images | grep beekeeper
beekeeper    latest    2dc2439eaec3   1 min ago      118MB

👉 Test the server locally

$: docker run -it -p 8080:8080 beekeeper

You should get the state of the Hives when fetching your local endpoint 👇

Part 3 : Deploy the app worldwide

👉 Log-in or create your Fly.io account

$: flyctl auth login
$: flyctl auth signup

👉 Use the cli to the app and follow the steps below 👇

$: flyctl launch

Answer no to .dockerignore
Define the app name to the name of your project
Deploy the app in the region of your choice. You can add more or change it later
Answer no to Postgresql and Redis database
Answer yes to deploy now

It may take 1 or 2 minutes to create your project and build your Docker image with Fly remote builders (optional). If it succeed, you should see this in your terminal 👇

--> Building image done
==> Pushing image to fly
The push refers to repository [registry.fly.io/beekeeper]
deployment-01GJY6F3Y3707JXJ7PTZQKFS57: digest: sha256:722fe804f091c9fd33b789ac9c06ae68af87d1e6c6720025bdb33da0bf13fe1d size: 1991
--> Pushing image done
image: registry.fly.io/beekeeper:deployment-01GJY6F3Y3707JXJ7PTZQKFS57
image size: 118 MB
==> Creating release
--> release v1 created

--> You can detach the terminal anytime without stopping the deployment
==> Monitoring deployment

 1 desired, 1 placed, 0 healthy, 1 unhealthy [health checks: 1 total, 1 critical]
Failed Instances

You can detach the terminal now and check the status of your app with flyctl status.

Your app is now online ! Lets try to access it.

Go to your dashboard and click on the app you created.
You should see a lot of information about your app including the bandwidth and cpu/ram used.
You should find your app url in the "Hostname" box. Click on it and add /api/hives at the end.

Tadaam, you should see lots of bees, your app is deployed 🥳 !

To redeploy the app after a change in your code or conf use fly deploy.

Conclusion

I hope you learned some new stuff in this post. I focused on a simple case and the mandatory steps to deploy our application. If you need more information, feel free to check out the bonus section or the fly.io documentation.

Bonus

Configurations

The CLI tools generate for you fly.toml a configuration file used to describe your app on their platform. Here you can define ports, env variables, deploy and runtime options, the protocol used, etc. More info here.

Example of fly.toml generated for this project 👇

# fly.toml file generated for beekeeper

app = "beekeeper"
kill_signal = "SIGINT"
kill_timeout = 5
processes = []

[env]
  PORT=8080

[experimental]
  allowed_public_ports = []
  auto_rollback = true

[[services]]
  http_checks = []
  internal_port = 8080
  processes = ["app"]
  protocol = "tcp"
  script_checks = []
  [services.concurrency]
    hard_limit = 25
    soft_limit = 20
    type = "connections"

  [[services.ports]]
    force_https = true
    handlers = ["http"]
    port = 80

  [[services.ports]]
    handlers = ["tls", "http"]
    port = 443

  [[services.tcp_checks]]
    grace_period = "1s"
    interval = "15s"
    restart_limit = 0
    timeout = "2s"

Regions

You can currently deploy your apps in 26 differents regions with the command flyctl regions add.

👉 Add Paris and Tokyo as new regions

flyctl regions add cdg nrt

👉 Check regions

flyctl regions list

CI/CD

Fly provide remote builder so it's easy to integrate it with Gitlab or Github CI/CD pipelines. More info here and here.