DEV Community: Plasmo

HOWTO: Injecting UI into Website with Browser Extension

Louis — Fri, 22 Jul 2022 16:17:00 +0000

TL,DR:

pnpm create plasmo inject-ui
cd inject-ui
touch content.tsx

content.tsx

const Overlay = () => (<h1>HELLO WORLD</h1>)
export default Overlay

pnpm dev

Load the extension in Chrome, refresh and you should see HELLO WORLD injected into the top of the webpage.

Explanations

Browser extensions can inject DOM elements into a website using a content script. However, the injected element might inherit the website's style without proper encapsulation. This is often undesirable for any site-agnostic browser extension.

There are 3 solutions to the problem above:

A. Render the element with a style tag that does css unset.

A is often seen employed by ad. It works well for self-contained, simple components that render images. However, it is very hard to leverage a design system that has inherited styling, since the unset cascades down. Unless you have a dedicated style injection scheme, it is very difficult to use and the extra style tag makes the code not very clean.

B. Render the element inside an iframe.

B isolates the element well and is the go-to technique of many old browser extensions. However, the iframe container can be hard to work with when trying to blend the injected component seamlessly into the website. Iframe's elements are nested inside an inner document within its frame, with its own head and body. This makes it tricky to style and control elements inside the iframe, as well as align them with the elements of the website.

C. Render the element inside a Shadow DOM.

C is the best technique for web extension. Introduced as the key part of the web component API, the idea is that the shadow DOM is a separate DOM attached to the underlying main DOM. Nothing inside it can affect the main world. The Plasmo framework uses this technique behind the scene to enable seamless injection of React component into any webpage. We call this feature "content script UI."

Building a Modern React Chrome Extension with a New Framework

stefàn — Tue, 31 May 2022 13:59:14 +0000

When I first started building Chrome extensions, I was so annoyed with the boilerplate.

It was frustrating to configure the manifest.json, pointing it to the correct files. You had to read at least 4 blog posts to figure out how to do it correctly. The annoyance compounded if you tried to use modern JavaScript frameworks like React. Now you needed to deal with Webpack, and figure out how that played into the manifest.json story.

We decided to tackle this problem by building a framework for browser extension development called Plasmo. It's a different way of thinking about browser extensions, and if you're used to building extensions, some things might look a bit weird.

If you want to follow along, run:

pnpm dlx plasmo init

Looking at the directory plasmo init generated, you might notice there is no manifest.json.

This is one of the key features of the Plasmo Framework -- we auto-generate the manifest.json so you can focus on building cool stuff rather than caring about where to point content_scripts to, and what the schema format should look like.

The idea is simple: you add a file called popup.tsx exporting a React component, and Plasmo will understand it's a popup page. It'll register it in the manifest and write the code to automatically mount the component into your popup view.

The same is true for content.ts, background.ts, and options.tsx. The framework understands what these files are, and automatically builds the manifest with them in mind.

If you have multiple scripts, you can use contents/, options/, and popups/ directories to get the same effect.

Key Principles:

No manifest.json file

We strongly believe the manifest.json file is a leaky abstraction. That's why we built the framework to generate as much of the manifest as possible.

We've still got a bit of a way to go, but we've automated a large chunk of it out.

It's good to have opinions

This framework is not for everybody, and that's completely okay. Our goal is not to make a framework that caters to everyone's needs. Instead, we're focusing on people who want to build production-grade extenisons using React quickly.

If someone wanted to build a minimalist extension that used vanilla Javascript, this framework would not be for them.

MV3 Only

Manifest version 3 is the future. Let's embrace it and build good tooling around it to enable people to build amazing products.

Docs

Check out our docs to see other cool features we have. We're constantly iterating and improving, so if you have feedback, would love to hear it!

HOWTO: Consuming CJS in a Typescript module

Louis — Wed, 26 Jan 2022 12:36:00 +0000

At Plasmo we leverage Typescript for our web projects.
CJS project like humanparser would have example like this:

const human = require('humanparser');
const fullName = 'Mr. William R. Hearst, III';
const attrs = human.parseName(fullName);

console.log(attrs);

The require statement is how we import the humanparser module into a CJS codebase. This statement can be translated into TypeScript/ESM 2 ways:

import * as humanParser from 'humanparser'

import humanParser from 'humanparser'

Which is it?

The answer lies in the source code of the humanparser module itself. This is an artifact from the evolution of ES, from ES3-> ES5 -> ES6 and beyond (now ESM). There were a couple of ways a module could be exported.

The first, commonly used during the transition between ES3 -> ES5 (early nodejs days), was to assign an entry function or object into module.exports global:

module.exports = stuff

In this example, the module.exports global was used to bridge into the require statement. Because module.exports represent "everything" that was exported from this module, we must use the import all statement:

import * as humanParser from 'humanparser'

The * represents the module.exports object.

Another way, which occurred during the transition between ES5->ES6, is to export a default property as the entry for your module:

module.exports = {
    default : stuff
}

This assigned stuff into the defaults property exported by the module. The reason why this was done is because in ES6, when doing:

import humanParser from 'humanparser'

The above code is actually importing the default props exported by a module. (The export statement in ES6 would be: export default stuff). The import statement above is doing something like this in equivalent CJS code:

const humanParser = require('humanparser').default

Now, back to humanparser's source code, their export statement looks like this:

const parser = module.exports = {};
parser.parseName = function(){}
parser.getFullestName = (str) => {}
parser.parseAddress = (str) => {}

Because there's no default prop being exported, we can import the parser two ways, either importing the whole object:

import * as parser from "humanparser"

OR, importing the props that was exported separately:

import {parseName, parseAddress} from "humanparser"

Personally, I like to import the named export, it helps with code intelligent, and I don't have to deal with the import all module namespace issue.

Back Story

Back in the olden day, pre-2015 to be exact, where angular.js were still trendy, react was still the new kid in the block, and people were comparing Corodva phonegap to react native, there was a transition from ES3/ES5 (commonJS or CJS) to ES6 (ES2015, or ESM, or MJS - modulejs). I suspect whoever named the extension was a huge fan of the late pop king.

Cautions

If you are looking at new projects, be cautious of pure ESM module. They will only allow you to import them with:

import mod from "module-name"

The tricky part is that, your project must also be a module - i.e, it cannot be compiled into common js (which converted all import statement into cjs require call). It must be an MJS/ecmascript module file (with the .mjs extension) OR that your package.json have specified the module property. Otherwise, it would simply fail to compile, and you won't be able to import it using require because ESM code looks like this:

export default stuff

Instead of this:

module.exports = stuff

In the CJS example, module.exports are bridged into the require statement for importing in other modules. Meanwhile, in the ESM example, the stuff is being exported by the export statement , and thus can only be imported via the import statement.

The dilemma here is that if you're using TypeScript and was hoping that it would play well with ESM only module, you are in for some sour candy - it does not. Typescript compiler doesn't yet care if a module it imported is ESM or not - it converts all to CJS import unless you configured it properly. You would also need to tell nodejs to use an experimental flag when running your compiled code: https://nodejs.org/api/esm.html#customizing-esm-specifier-resolution-algorithm

P.s: this post is a brain-dump. If it's useful, you're welcome. If not, here's the MIT license for this otherwise unreadable post:

Copyright 2022 L❤☮🤚

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.