DEV Community: Paula Santamaría

Debugging TypeScript projects with VSCode in 2023

Paula Santamaría — Sun, 16 Apr 2023 17:19:34 +0000

I finally decided to invest some time in properly setting up a debugger for my Node + TS projects. console.log is cool and all, but it just wasn't cutting it anymore.

So, I've been reading documentation (plus so many GitHub issues), and trying different solutions, and I ended up with a config that I'm actually happy with!

Keep reading to learn how to:

Create a project with Node.js and TypeScript.
Install a package (ts-node-dev) and configure it so it can run your project and auto-restart on save.
Configure the debugger in VSCode so it uses ts-node-dev to both enable the debugging of .ts files and provide auto-restarts.
Finally, stop relying on console.log('here!') to debug your code :D

Initialize the project

Create a directory for your project and initialize it:

mkdir ts-starter
cd ts-starter
npm init -y

Install TypeScript

Install TypeScript and the type definitions for node:

npm install typescript @types/node --save-dev

Setup your tsconfig

To create the tsconfig.json file, run the following command:

npx tsc --init

The default tsconfig.json generated should look something like this:

{
    "compilerOptions": {
        "target": "ES2016",
        "module": "commonjs",
        "esModuleInterop": true,
        "forceConsistentCasingInFileNames": true,
        "strict": true,
        "skipLibCheck": true 
    }
}

Install ts-node-dev

Were going to hook up ts-node-dev with the VSCode debugger to get both the debugger and auto-restarts working!

Start by installing the package:

npm install ts-node-dev --save-dev

To quickly try it out, we can create a new script in the package.json:

"scripts": {
    "dev": "ts-node-dev --respawn src/index.ts"
},

Now lets write some code to run!

Create the src directory and add the following code:

// index.ts

interface Game {
  name: string;
  genre: string;
  platform: string;
}

const game: Game = {
  name: "Super Mario",
  genre: "Platformer",
  platform: "Nintendo",
};

console.log(game);

Were adding some types so we can make sure the compiler is working properly.

Finally, run the dev script from your terminal:

npm run dev

You should see something like this:

And finally, change the values in your game constant and save the file, to see the automatic restarts in action!

Nice, we can see how the app auto-restarts after we make changes!

Set up the VSCode Debugger

First, lets generate a launch.json file. To do that:

Open the command palette (Ctrl + Shift + P or Cmd + Shift + P on Mac) and select Debug: Add Configuration
On the next step, select Node.js for the Debugger

You should get an auto-generated launch.json file, like this one:

{
    "version": "0.2.0",
    "configurations": [
        {
            "type": "node",
            "request": "launch",
            "name": "Launch Program",
            "skipFiles": [
                "<node_internals>/**"
            ],
            "program": "${workspaceFolder}\\\\src\\\\index.ts",
            "outFiles": [
                "${workspaceFolder}/**/*.js"
            ]
        }
    ]
}

Replace it with the following configuration:

{
    "version": "0.2.0",
    "configurations": [
        {
            "type": "node",
            "request": "launch",
            "name": "Launch + auto-restart",
            "runtimeExecutable": "${workspaceRoot}/node_modules/.bin/ts-node-dev",
            "args": [
                "--respawn",
                "${workspaceRoot}/src/index.ts" 
            ]
        }
    ]
}

The main properties to notice here are:

runtimeExecutable: By default, this would be node, but we are replacing it with ts-node-dev
args: Were adding the --respawn flag, which tells ts-node-dev to restart the process when files change, and then we add the path to our startup file.

Essentially, these two properties produce a result similar to the ts-node-dev --respawn src/index.ts script we set up earlier in the package.json.

Now, lets try it!

Press F5 to start the debugger. You should see the output on VSCode's integrated terminal:

Try adding a breakpoint, and then make some changes and save:

The app should restart and hit the breakpoint!

That's it!

What I love about this config is how simple it is. All we needed was ts-node-dev, a few tweaks to the debugger config file, and it just works!

Although, to be completely honest, I'll probably still use console.log('here') every now and then, just for old times' sake.

My TypeScript book: typescriptgamified.com

A Twitch chatbot powered by Notion

Paula Santamaría — Tue, 15 Feb 2022 12:00:47 +0000

AchoBot is an open-source Twitch chatbot I built for myself. It allows you to manage your chatbot's commands using Notion:

It relies on the power of Notion Databases to manage command responses, permissions, and documentation.

Table of contents

The repo
Features
Development
Try it
Stream

The repo

Check the repo here 👇

pawap90 / acho-bot

🐶💬 A Twitch chatbot powered by Notion

Use Notion to configure your Twitch chatbot commands!

Features

Manage your Twitch Chatbot from Notion

Add, update or delete commands in a Notion database. AchoBot will use the information from Notion to answer your viewers when they invoke a command.

Assign Permissions to each Command

The database includes a Permissions column where you can specify who can invoke each command. Leave it empty, and everyone will have access to it. The column accepts one or more of the following values:

Broadcaster
Moderator
Subscriber
Viewer

Specific user permissions

You can also create commands that can only be invoked by a single specific user. To do that use the value usr:<username>, for example: usr:paulasantamaria

Commands

…

View on GitHub

Features

Here's the complete list of features:

Manage your Twitch Chatbot from Notion

Add, update or delete commands in a Notion database. AchoBot will use the information from Notion to answer your viewers when they invoke a command.

Assign Permissions to each Command

The database includes a Permissions column where you can specify who can invoke each command. Leave it empty, and everyone will have access to it.

Specific user permissions

You can also create commands that can only be invoked by a single specific user. To do that use the value usr:<username>, for example: usr:paulasantamaria

Commands view

Navigate to /commands to get a list of every public command. Your viewers can use it to see the available commands.
Also, you can navigate to /commands?mode=image to get a ready-to-download image you can add to your Twitch panels.

Scripted commands

You can specify the type of command in the "Type" column. Available options are:

Text commands return a plain text response. E.g: "Welcome to the stream".

Scripted commands can implement some logic (JavaScript) and receive parameters.

For example, imagine the following command !say <text>:

(context) => {
    const textToPrint = context.params.text;
    return `You said: ${textToPrint}`;
}

When a viewer invokes it: !say hello
Output: You said: hello

This feature is new and still has some limitations and issues. Writing code in a Notion DB cell is not ideal 😅.

Single account

The chatbot service will work only for the accounts and channels specified in the environment variables.
If any other account tries to log in using the chatbot authorization endpoints, it will get an authorization error.

The service is not currently designed to handle multiple accounts. This is a limitation, but it also makes the hosting and configuration of the service easier.

Status view

Use the status view to see if your bot's Twitch account is correctly authorized.
You can use this view in OBS to get real-time feedback on your chatbot status (it auto-updates every minute).

Built-in commands

Built-in commands are defined in the codebase instead of Notion. They usually require more logic and access to resources unavailable to the Notion commands. There are currently two built-in commands that you can use:

!help prints a list of available commands.
!refresh invalidates the command cache, so next time a command is triggered, the app needs to go to Notion to retrieve the commands, thus updating them to the latest version. Only available for Broadcaster and Moderators.

Placeholder commands

Some commands are triggered via code but defined in Notion. This allows AchoBot to react to certain events (like a user logging in or subscribing) while also allowing each user to specify what they want AchoBot to do in each case.
Right now, the only placeholder command is:

!welcome: Executed when AchoBot joins the chat room immediately after a stream starts. If you define this command in Notion when the bot logs in, it can say hi and leave some relevant information in the chat. E.g., "Hi, I'm AchoBot! Type !help to see what I can do".

Development

AchoBot runs on Node.js. It was developed with TypeScript and uses Nodemon to run the development server. It relies on tmi.js to connect and interact with Twitch's chat.

How it works

Once the service starts, AchoBot retrieves the commands from Notion (and other sources) and stores them in cache. When viewers execute a command, we search for it in the cache and execute it to generate a response:

Extensible

The project is designed to be easily extensible. It uses the command pattern to define the list of commands. You can extend this list using different strategies depending on what you aim to achieve. To know more: Extend AchoBot

Try it

Here's a detailed step-by-step guide on how to run AchoBot: AchoBot Setup - Full Guide

Stream

I developed this chatbot live on stream. Join me if you are interested in live coding sessions where I experiment with different tech stacks and build open-source software!

👉 twitch.tv/paulasantamaria

Right now, I'm working on a new portfolio with Svelte-kit, markdown, and TailwindCSS.

Using GitHub Actions to turn contributors into heroes of an open source game

Paula Santamaría — Thu, 09 Dec 2021 01:05:34 +0000

My Workflow

We already know open source contributors are the heroes of the tech industry. They make our lives easier with their libraries, frameworks, and more. I wanted to use this opportunity to make them into a more literal type of hero inside a game.

So, here's how it works:

My GitHub Actions workflow extracts information from the contributor's PR and uses it to dynamically generate a file that the game will use after being deployed.
To obtain this information from the PR the workflow uses GitHub's API through octokit/request-action@v2.x and saves the relevant data using environment variables that are then used to generate a Contributor.ts file.

Then the workflow builds the whole project, including the generated file, and deploys it to GitHub Pages. So the latest deployment includes the latest PR and contributor information!

Finally, the workflow also generates a copy of each contribution and stores it in an "archive" folder that can be accessed from the deployed website, so contributors can access their contributions live even after another merged PR overrode them.

So, if you contributed, you can always access the deployment from your contribution in https://pawap90.github.io/space-commit/archive/{your-username}.

The game is called "Space commit". It's a simple, side-scroller, open-source game I developed especially for this submission. For the development I used Phaser with TypeScript, ESLint, and Snowpack. I decided to make our heroes astronauts because I thought it captured the essence of open source contributors: They are explorers and science lovers; They get themselves in unexplored territories and enjoy learning.

Here's a quick demo:

Submission Category:

Wacky Wildcards

Yaml File or Link to Code

name: CICD
on:
  push:
    branches: [ main ]

  workflow_dispatch:

jobs:

  build:
    runs-on: ubuntu-latest
    steps:

      # Retrieve contribution data from GitHub API
      - uses: octokit/request-action@v2.x
        name: Retrieve contribution data
        id: get_contribution_data
        with:
          route: GET /repos/{owner}/{repo}/commits/{commit_sha}/pulls
          owner: pawap90
          repo: space-commit
          commit_sha: ${{ github.sha }}
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

      # Generate env variables to easily access the contribution data
      - name: Store contribution data in env vars
        run: | 
          echo "username=${{ fromJson(steps.get_contribution_data.outputs.data)[0].user.login }}" >> $GITHUB_ENV
          echo "avatar_url=${{ fromJson(steps.get_contribution_data.outputs.data)[0].user.avatar_url }}" >> $GITHUB_ENV
          echo "commit_sha=${{ github.sha }}" >> $GITHUB_ENV
          echo "message=${{ fromJson(steps.get_contribution_data.outputs.data)[0].title }}" >> $GITHUB_ENV


      - name: Print collected data 
        run: | 
          echo "data collected 
                username ${{ env.username }}
                avatar ${{ env.avatar_url }}
                commit sha ${{ env.commit_sha }}
                message ${{ env.message }}"

      - uses: actions/checkout@v2
      - uses: actions/setup-node@v2
        with:
          node-version: '14'
          cache: 'npm'

      - name: Generate contributor file 
        run: |
          echo "export const Contributor = {
              username: '${{ env.username }}',
              avatar_url: '${{ env.avatar_url }}',
              commit: '${{ env.commit_sha }}',
              message: '${{ env.message }}'
          };" > src/Contributor.ts

      - name: Build project 🔧
        run: | 
          npm install
          npm run build

      # Deploy latest contribution to GitHub pages
      - name: Deploy 🚀
        uses: JamesIves/github-pages-deploy-action@4.1.5
        with:
          branch: gh-pages
          folder: _build
          clean: true
          clean-exclude: archive

      # Store build permanently in archive folder so everyone can check previous contributions by username
      - name: Send to archive 📁
        uses: JamesIves/github-pages-deploy-action@4.1.5
        with:
          branch: gh-pages 
          folder: _build
          clean: true
          clean-exclude: archive
          target-folder: archive/${{ env.username }}

Additional Resources / Info

Here's the game repo where this workflow is used: github.com/pawap90/space-commit

And you can play the latest version here: pawap90.github.io/space-commit

Also, I built most of this game live on Twitch. You can check it our here: twitch.tv/paulasantamaria

Create games using TypeScript, Snowpack, and ESLint with this template

Paula Santamaría — Sun, 16 May 2021 15:00:22 +0000

NOTE: ⚠️ The GitHub template presented in this post was archived. I created a new one that has exactly the same features (TS, ESLint, hot reload, GitHub Pages) but instead of Snowpack uses Vite, since Snowpack is now deprecated.

I also took the opportunity to update all dependencies to the latest available version:

pawap90 / phaser3-ts-vite-eslint

A modern Phaser template with TypeScript, Vite, ESLint, and GitHub Pages

A modern Phaser 3 template: Phaser 3 + TypeScript + Vite + ESLint + GitHub Pages

Table of contents

Dependencies

Node.js
npm

Quick start

Get this template: Press over the "Use this template" button. This will allow you to create a new repo with this project's structure on your Github account. Then you can clone it to your local machine.

Alternatively, you can clone this repo to your machine using the following command.

git clone https://github.com/pawap90/phaser3-ts-vite-eslint.git

Install dependencies: Run the following command from the project's root folder:

npm install

Start the local development server:

npm run dev

Go to your browser and navigate to http://localhost:5173. You should see this beauty:

Project structure

├── /.github
│   └── /workflows
│           ├── build.yml
│           └── deploy.yml
├── /public
│       ├── acho.png
│       └── ground.png
├── /src
│   ├── /scenes
│

…

View on GitHub

If you follow me on Twitter or Instagram, you may know I've been trying out Phaser lately.

Phaser is an open-source game framework that allows you to develop games using HTML and Javascript.

I've always been interested in Game development, but I hadn't found the time in the past to really get into it. I tried some things with Unity over the years, but I was focused on University and work, so those projects always got left behind at some point. Now that I graduated, I have more time to explore these kinds of things.

So I started going through some tutorials and doing some experiments with the framework. To get started, all you need is a local web server and getting Phaser through NPM or a CDN, for example. Browsing online, I found some templates that used No.jsde as a web server and installed Phaser through NPM, so I decided to make my own template using a modern tech stack.

And here it is:

pawap90 / phaser3-ts-snowpack-eslint

A modern Phaser 3 template with TypeScript, Snowpack & ESLint

Warning

This repository has been archived.

If you're looking for a Phaser Template, please use this one: github.com/pawap90/phaser3-ts-vite-eslint

A modern Phaser 3 template: Develop your game using Typescript, keep your codebase clean with ESLint, and enjoy lightning-fast live updates thanks to Snowpack.

Table of contents

Dependencies

Node.js
npm

Quick start

Get this template: Press over the "Use this template" button. This will allow you to create a new repo with this project's structure on your Github account. Then you can clone it to your local machine.

Alternatively, you can clone this repo to your machine using the following command.

git clone https://github.com/pawap90/phaser3-ts-snowpack-eslint.git

Install dependencies: Run the following command from the project's root folder:

npm install

Start the local development server:

npm start

Go to your browser and navigate to http://localhost:8000. You should see…

View on GitHub

About the template

This template allows you to develop your game using TypeScript, keep your codebase clean with ESLint, and enjoy lightning-fast live updates thanks to Snowpack.

I decided to use TypeScirpt instead of JavaScript after doing some tutorials. I tried both options, and I just felt more comfortable with TypeScript.

Build it with Snowpack

When the time came to choose a bundler, I decided to give Snowpack a try since I've heard many good things about it. And honestly, I was blown away by how fast it is. The development server starts in 14ms on my machine, and the live updates are fantastic. I can play around with Phaser and see every update on the browser almost instantly.

I also used Snowpack's built-in optimizations to minify and bundle the build and make it lighter for production. This Snowpack feature is not yet production-ready (according to the docs), but I've done a few tests, published some sample games, and I haven't had any issues with it so far.

Minimalistic

The template is very minimalistic, meaning that it only has what's needed to run and build the project, plus a Sample scene to check everything is working correctly.

Project structure

├───public/                         Public static files
│   ├───assets/                     Sample assets
│   │   ├───banner.png
│   │   ├───acho.png
│   │   └───ground.png
│   └───index.html                  HTML file where our game will be loaded
├───src/                            Game logic goes here
│   ├───scenes/                     Game scenes
│   │   ├───InitialScene.ts         Initial sample scene
│   │   └───PreloaderScene.ts       Scene preloader
│   └───Main.ts                     Phaser game configuration
├───.eslintignore                   Files that should be ignored by ESLint  
├───.eslintrc.js                    ESLint configuration file
├───.gitignore                      Files that should not be pushed to the repo
├───package.json                    Project scripts, dependencies and metadata
├───snowpack.config.js              Snowpack configuration file
└───tsconfig.json                   Typescript configuration file

You can remove everything in the public/assets folder. But I recommend you first run the project once and make sure everything is installed and running properly.

Clean and safe

It's focused on keeping the codebase clean and safe, thanks to TypeScript and ESLint.

TypeScript's configuration contains some flags that set some checks like "strict" and "noImplicitAny" to reduce errors. You can always change that in the tsconfig.json file if you prefer different settings.

I also added a prebuild script that uses tsc and ESLint to compile and lint the project before building it to ensure the build is safe to publish.

So when you run npm run build, the prebuild will be executed first and fail if there are errors. This script could be easily executed in a CI pipeline, for example, to make sure you don't merge or deploy the project if there are issues.

ESLint

I added ESLint to keep the codebase clean and consistent. The configuration can be found in .eslint.js in case you want to add your own rules or modify something.

There are also a few scripts I added to the package.json to check for errors or styling issues:

# Print the list of problems found
npm run lint

# Some of the issues can be automatically fixed using:
npm run lint:fix

Beautiful and classy 🧐🎩

Once you clone the template and install the dependencies, you'll be blessed with this beauty:

If you want to know more about my Game Dev journey, follow me on Instagram or Twitter. I'll be sharing my progress, tips, and tricks, and probably lots of bloopers and fails.

5 Ideas to set your portfolio apart

Paula Santamaría — Mon, 26 Apr 2021 15:01:17 +0000

Tired of building TO-DO lists and e-commerce sites? One of these Chrome extension ideas could help you set your portfolio apart! 👩‍💻

All you need to know to build your first Chrome Extension is the basics of HTML, JavaScript, and CSS! These are a few fun ideas I came up with that can be created using only those technologies.

If you're having doubts, check out my video Creating a simple Chrome Extension in 2 minutes.

1. Dark mode for your favorite website

Do you regularly use a website that you love but doesn't have dark mode?

With Chrome extensions, you can create your own CSS stylesheet that overrides some styles in a particular website. This allows you to apply dark mode styles over the website when your extension is enabled.

To achieve that, you should use Content Scripts.

Tip: Set "run_at": "document_end" in the content_scripts object in the manifest.json so your styles override the site's.

For this project, you'll need to learn about:

Content Scripts

2. Weather App

You could create an extension that shows the current weather for a particular location on your browser.

You'll need to call an API to retrieve the weather info: OpenWeatherMap API is a good option. They have a free plan.

Get the latest weather updates every few minutes in the background using an alarm from the chrome.alarms API handled by a Service Worker.

Store the results using the chrome.storage API and display them in your extension's Action Popup.

To call the API, you can use fetch, and you'll need to add something like the following to your manifest.json:

"host_permissions": ["https://some-weather-api.com/*"]

For this project you'll need to learn about:

3. Show today's calendar.

You could get easy access to your Calendar events for the day, showing them in your Browser through an Extension.

As with the previous idea, you'll need to get the data from an external API (Google Calendar's or your favorite calendar API) every few minutes in the background using an alarm from the chrome.alarms API and a Service Worker.

You'll also need to store the results of the API request using chrome.storage. Remember that Service Workers can be unloaded when the extension goes idle, so you can't just store the calendar events in a variable declared in your Service Worker.

Display the events with their title, time, guests, etc., in your extension's Action Popup.

You can also use chrome.notifications API to show a message to the user a few minutes before the event.

For this project you'll need to learn about:

4. Daily coffee

Show the user a random coffee recipe to try every day.

In this case, you don't need to call an external API (at least at first). You could just store a list of your favorite recipes in a JSON array in your extension and use a Math.random() to get a random item from the array every day.

Display the coffee recipe with a nice picture in the Action Popup.

To make it more robust, you could use chrome.storage to store the last coffee recipe shown and the date to make sure of two things:

A single coffee recipe is shown every day.
We don't get the same recipe two days in a row.

For this project you'll need to learn about:

chrome.action API
chrome.storage API (optional)

5. E-Commerce wishlist

Allow users to add products from Amazon, eBay, etc., to their wishlist: When a user finds a product they're interested in, they add it to their wishlist using a keyboard shortcut or from the Action popup.

The Action popup also shows the previously added items and allows the user to remove them.

The user should also be able to navigate to each product page in case they want to buy it. For this, you should use chrome.tabs.create.

You'll need to store links, name, and price for each product using chrome.storage API.

For this project you'll need to learn about:

chrome.action API
chrome.storage API
chrome.tabs API - Particularly the create method

I hope this post was helpful and inspires you to work on your next project! If you're interested in learning about Chrome extensions, check out my series about it where I create a simple chrome extension and gradually improve it. At the same time, I explore most of the chrome APIs and concepts required to build the ideas mentioned in this post.

You can also check out my video Creating a simple Chrome Extension in 2 minutes to get a grasp of the process.

Icons by Smashicons & Freepik on Flaticon.com

Command-Line Interfaces: Structure & Syntax

Paula Santamaría — Mon, 19 Apr 2021 12:30:30 +0000

If you are a developer, chances are you have used or read about CLIs already (maybe to execute git or npm commands or in some library's documentation).

I work with multiple CLIs every day (docker, dotnet, npm, git, etc.), but I had never stopped to learn much about their structure or syntax until recently. Reading documentation and examples is usually enough to get by.

However, I'm currently developing my own CLI for a personal project, so I decided to learn more about CLI design, structure, syntax, and conventions. I did my research, which I documented and decided to share here in this post.

1. Introduction
- 1.1. Structure
2. Arguments
3. Options
- 3.1. Flags
4. The --help flag
- 4.1. Common aliases for the --help flag:
- 4.2. Levels of verbosity
- 4.3. The help command
5. CLI description syntax conventions
- 5.1. Required Parameters
- 5.2. Optional Parameters
- 5.3. Arguments that can receive many values
- 5.4. Mutually exclusive arguments
Conclusion
6. References

1. Introduction

A CLI or Command Line Interface is an application that handles user interaction through the Command Line.

They don't have graphics (except, maybe, for ASCII Art 😂).
All the information is presented to the user in the form of text and the user interacts with it by typing in commands.

CLIs can be faster than GUIs for certain tasks (especially for monotonous tasks and when you're already familiar with the commands). One of the main advantages they have over GUI is that they're easier to *automate* (running "npm install" in a CI pipeline could be a lot trickier without a CLI).

1.1. Structure

Most CLIs are designed with the following structures:

<command> [arguments] [options]
- Example: ls /home/dir --all
<program> <command> [arguments] [options]
- Example: git fetch origin main --depth=10
<program> [arguments] [options]
- Example: docker -v

Commands are usually represented as verbs and programs as nouns (as they are usually a short version of the program's name). There are some cases where a second (or third, or more) noun is used to narrow the scope in which the command will operate, for example:



docker container start

Here, we have the program (docker), the context (container), and the command (start).

2. Arguments

Arguments in a CLI allow users to send data to the application, sometimes in a command context. They are often called positional arguments because they are identified by their position, which means users must write the value for each argument in the correct position.



mycli command argValue1 argValue2
              |_______| |_______|
                  0         1

They can be required or not. If they are not required, the command's behavior may vary in the absence of the parameter, often using a default value instead.



# No argument provided -> Installs all dependencies from the package.json
> npm install

# Argument value: some-package -> Installs only some-package
> npm install some-package

Another example:




# No arguments -> Uses default remote and branch.
> git fetch

# Passing a specific remote and branch as arguments.
> git fetch origin main

3. Options

Options are named parameters that can be passed to a command and are represented by key-value pairs.

Unlike positional arguments, their position is not important.

You're probably familiar with the following example:



# Key: --message 
# Value: "commit message"
git commit --message "commit message"

Options are usually (not always) used to represent optional parameters. In most cases, if a parameter is required, a positional argument is the best way to go.

Some options have aliases, which are short versions of the same option, easier to type and remember. They're usually identified by a single dash prefix:



# Long version
> mycli --help

# Alias
> mycli -h

Different delimiters are supported, depending on the CLI and Operating System. These are some of the most common:



# Single space
> mycli --file text.txt

# =
> mycli --file=text.txt

# :
> mycli --file:text.txt

3.1. Flags

Options that don't require a value are often called Flags. They are boolean, meaning their presence indicates "true" and their absence "false".

Some examples of commands using flags:



> git push --force

> npm install --save-dev

4. The --help flag

Informing our users about the available commands and their arguments and options can be tricky without a GUI.
That's when the --help flag comes in.

When we include the help flag after a command, we ask the CLI to give us more information about it.
Usually, this information will include a short description of the command, arguments, options, and aliases.

Example:



> npm install --help

4.1. Common aliases for the --help flag:



-help, -h, -?, -H

4.2. Levels of verbosity

Some CLIs allow the user to ask for different levels of help.
For example, the dotnet CLI will print the short version when we use -h or --help , and the long version when we use -H or -HELP.



# Short version
dotnet <command> -h

# Long version
dotnet <command> -H

Similarly, git CLI prints a summary of the command briefly explaining how to use it when we use -h, but redirects to the offline HTML documentation when we use --help:



# Short version
git <command> -h

# Offline HTML docs
git <command> --help

Learning about the different levels of verbosity was really helpful (I've been using it frequently), although it's a shame there's not a standard for it.

4.3. The help command

Some CLIs also provide a help command, which usually gives more detailed information than the --help flag:



program help <command-name>

For example, both dotnet CLI and npm CLI will open a browser and redirect you to the command's full documentation when we use the help command:



dotnet help <command>

npm help <command>

5. CLI description syntax conventions

When reading a CLI's documentation or a "man" page, you'll likely come across a particular syntax used to describe commands, their arguments, and options (located often under "Synopsis").
I used to not pay much attention to it (other than trying and figuring out the general anatomy of the command) and going straight to the examples. But after learning about it and how to interpret it, these descriptions have become much more useful to me.

5.1. Required Parameters

Required parameters are often represented using just the name of the param, although in some cases, you may find them between angle brackets:

dotnet new <template>: We can't create a new dotnet project without specifying a template.
mv source dest: When moving a file/directory, we must specify the source and destination parameters.

5.2. Optional Parameters

Optional parameters are most commonly represented using square brackets: mycli command [optionalParameter]

docker container ls [options] We can add some flags and options to alter the command's behavior.
git remote [-v | --verbose] We can use -v or --verbose to get more information about each git remote.

5.3. Arguments that can receive many values

Ellipses indicate the argument/option expects many values. It can be applied to optional or required parameters

Here's how it looks like applied to optional parameters:



mycli command [parameter...]

The previous statement tells us our parameter expects 0 to N values.

Required parameters that receive many values are usually represented in one of two ways. Here is one of them:



mycli command <myParameter> [myParameter...]

This statement tells us the command receives at least a single value for <myParameter> but can also receive more values, represented by [myParameter...] resulting in 1 to N values.

Here's an example from the Docker CLI:



docker container start <container> [container...]

When executing the start command, we must specify at least one container, but we can also start more than one in the same command.

The second way of representing required parameters with many 1 to N values is as follows:

mycli command <myParameter...>
Or: mycli command myParameter...

Since we are not using square brackets, it's clear myParameter is required, which indicates it needs at least one value (1 to N).

Here's an example:



mkdir directory...

We need to specify at least one directory to create when using mkdir, but we can also create more than one.

5.4. Mutually exclusive arguments

Some arguments cannot be used together in the same command. Their exclusive relationship is represented using pipes:



mycli command [ --option1 | --option2 ]

The square brackets tell us we don't have to use any of those options, and the pipe tells us that, if we decide to use them, we can't use them both at the same time. So any of the following are valid:

mycli command
mycli command --option1
mycli command --option2

But the following would be invalid:

mycli command --option1 --option2

An example from git commit:



git commit [ -a | --interactive | --patch ]

The previous statement tells us we can use any of those flags (-a, --interactive or --patch ) but not together
Also, the square brackets indicate we can also decide not to use any of them.

Here's what happens when we try to use -a and --patch together:



> git commit -a --patch 

fatal: Only one of --include/--only/--all/--interactive/--patch can be used.

This syntax is often used to represent aliases: git remote [ - v | --verbose ]. Both flags are valid individually, but it doesn't make sense to use them simultaneously.

Similarly, there are cases when at least one option must be included. In those cases, we use vertical bars, and we group the parameters using curly brackets or parentheses, like so:

mycli command { --option1 | --option2 }
Or: mycli command ( --option1 | --option2 )

The curly brackets or parentheses indicate that at least one option must be included.

Here's an example from git remote:



git remote set-head <name> (-a | --auto | -d | --delete | <branch>)

The parenthesis indicates that we must choose at least one of those options
The pipes tell us we can't choose two or more of them

If we don't use any of the required options, we get this error:



> git remote set-head origin 

usage: git remote set-head <name> (-a | --auto | -d | --delete | <branch>) 
    -a, --auto            set refs/remotes/<name>/HEAD according to remote 
    -d, --delete          delete refs/remotes/<name>/HEAD

Another example from dotnet new:



dotnet new <template> [-lang|--language {"C#"|"F#"|VB}]

So, the square brackets indicate that passing a -lang or --language is optional
The curly braces and pipe indicate that we must choose between C#, F#, and VB.

Conclusion

I know I could have developed my CLI without stopping to learn any of this. After all, there are libraries that would take care of the syntax and interpretation of commands. Nonetheless, I found it extremely interesting, and I have been using this new knowledge a lot after acquiring it. Finding and reading CLIs documentation has become a lot easier, and I learned many tips that will definitely help me develop a better, more intuitive CLI following the conventions and standards described in this article.

6. References

Chrome Extensions: Migrating to Manifest v3

Paula Santamaría — Fri, 26 Mar 2021 11:05:12 +0000

Manifest v3 has been available since the release of Chrome 88 earlier this year. If you're planning on building a Chrome extension or if you're currently building one, you should learn about this new version of the Chrome Extensions Manifest in order to benefit from the new features and vision.

In this post, we'll go through a brief overview of Manifest v3, then we'll take a look at the Migration Checklist to learn everything we'll need to change to migrate our sample extension. Finally, we'll apply the changes step by step so at the end, our sample extension will be successfully migrated to Manifest v3!

1. Manifest v3 Overview

Chrome Extensions launched a decade ago, and, according to the docs, Manifest V3 represents one of the biggest shifts in the extensions platform since then. It includes many changes that bring Chrome Extensions closer to the modern web (like promises and service workers!).

1.1. Three pillars

As stated in the docs, Manifest v3 is a step forward in Chrome Extensions' strategic direction. The main focus of this vision is in the following 3 pillars:

Privacy: The idea here seems to be to let the user know about the extension's activities and how their information is used. And also reduce the need for extensions to have access to user data persistently.
Security: Extensions will be required to follow stricter protocols, and, for example, they won't be allowed to access scripts from outside the extension context.
Performance: Keep good performance in all devices and avoid performance issues when extensions are installed.

They also state that they will preserve the "webbiness" of Chrome extensions to keep the barriers for developers low and benefit from the advances of the web.

Finally, they say the idea is to keep the platform capable, powerful, and feature-rich so developers can keep delivering value to users through it.

1.2. Main changes

Background pages/scripts are replaced by Service workers.

Much like background pages, service workers are scripts that run in the background and are independent of web pages. They don't need interaction with the website or a user.

ℹ️ Fun fact! Service workers were inspired by the background pages in Chrome Extensions.

The new `declarativeNetRequest` API handles Network request modification.

This new API is focused on privacy. The request will still be able to be modified and blocked, but in a privacy-preserving way.

This API is an improvement from the old webRequest API that fixes privacy, performance, and compatibility issues.

Remotely-hosted code is no longer allowed

This change came to improve security. Since all the code will be available in the extension package, extensions will be more reliably and efficiently reviewed before they are made available for the users.

The alternative recommended for extensions that require some feature to be handled remotely is using remote configuration files.

Added Promise support for many APIs

We can finally use promises in some of chrome APIs! 🎈 This was something I was really looking forward to.

Callbacks are still supported, so you don't need to refactor all your code right away.

Other minor changes

The browserAction API and pageAction API are now unified in a single API called action.
The Web-accessible resources are no longer available to all websites, which allowed extensions to use fingerprinting to track users.
The method executeScript() was moved from the tabs API into a new scripting API and no longer allows string scripts. You must provide a script file path or a function.
Host permissions are specified separately from the permissions property in the manifest.json.
The content_security_policy used to be a string, now it's an object, and you must specify the extension pages (HTML files and service workers) covered by the policy.

2. Migrating "Acho, where are we?" to Manifest v3

Now that we know the highlights of Manifest v3 and its vision, we can move on to migrate our sample extension.

2.1. Migration checklist

When migrating our extension to manifest v3, the first thing we should do is check the Manifest V3 migration checklist. I'll mark each bullet with ✅ when the change applies to our extension or ❌ when it doesn't:

❌ Do you have host permissions in your manifest?

✅ Are you using background pages?

Replace background.page or background.scripts with background.service_worker in manifest.json. Note that the service_worker field takes a string, not an array of strings.
Remove background.persistent from manifest.json.
Update background scripts to adapt to the service worker execution context.

✅ Are you using the browser_action or page_action property in manifest.json?

Since these two APIs were unified into a single action API, we must replace these properties with action.

✅ Are you using chrome.browserAction or chrome.pageAction JavaScript API?

Migrate to the chrome.action API.

❌ Are you currently using the blocking version of chrome.webRequest?

❌ Are you using these scripting/CSS methods in chrome.tabs API?

❌ Are you executing remote code or arbitrary strings?

❌ Are you executing functions that expect an MV2 background context?

❌ Are you making CORS requests in content scripts?

❌ Are you using a custom content_security_policy in manifest.json?

2.2. Applying the changes described in the Checklist

Let's review each point from the previous section in-depth and apply the appropriate changes.

2.2.1. Set the Manifest version to 3

In the manifest.json file, set the value of manifest_version to "3".

2.2.2. Replacing background pages with service workers

As we replace our background page with a service worker, we must remember two things:

Service workers are terminated when inactive and restarted when they're needed again.
Service workers don't have access to the DOM.

This won't be a problem for us since when I created our background script, I already knew this change was coming, and so I made sure to keep those 2 things in mind in the original design of my background script.

The first change we need to do is rename the background.js script to service-worker.js.

Now we'll set our new service worker in the manifest.json file. To do that, we must replace the old background property with the following:

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

Now, notice that the service_worker property is a string. So we can't declare more than one file there (as far as I know, I didn't find much about this issue in the docs). Because of this change, I couldn't add the other two scripts I needed: acho.js and page.service.js. So I found a new way to include them and call them from service-worker.js: Simply use the importScripts() method at the top of the service-worker.js script:

// service-worker.js
importScripts('acho.js', 'page.service.js');

/* More code */

You can see all the changes I applied to replace my background script with a service worker in this commit.

2.2.3. Replacing "browser_action" by "action" in the manifest

Since these two APIs were unified into a single action API, we must change the property browser_action to action in our manifest.json file:

{
    "action": {
        "default_popup": "popup.html",
        "default_icon": {
            "16": "images/icon16.png",
            "24": "images/icon24.png",
            "32": "images/icon32.png"
        }
    }
}

See the commit.

2.2.4. Use the "action" API instead of the "browserAction" API

Similarly to the previous section, we must use the new unified action API.

In our sample extension, we had only used the browserAction API to set the badge color and text, so we'll replace those lines:

// acho.js

class Acho {

    /* More code */

    growl = () => {
        chrome.action.setBadgeBackgroundColor({ color: '#F00' }, () => {
            chrome.action.setBadgeText({ text: 'grr' });
        });
    }

    quiet = () => {
        chrome.action.setBadgeText({ text: '' });
    }

    /* More code */
}

Note: The text property is now required in the setBadge method, so we can no longer use chrome.action.setBadgeText({ }); to clear the badge text.

See the commit.

2.2.5. Specify an URL pattern for Web-accessible resources

This one wasn't in the Checklist, but I realized I needed to make a change because when I tried the extension, I got an error that said: "Invalid value for 'web_accessible_resources[0]'. Entry must be a dictionary value".

So, I figure out we must explicitly define which pages will have access to our resources. This is done via the matches property (similarly to content scripts). Here's how the new web_accessible_resources property looks like in the manifest.json:

{
    "web_accessible_resources": [
        {
            "matches": ["<all_urls>"],
            "resources": ["images/icon32.png"]
        }
    ]
}

See the commit.

2.2.6. Replace the command "_execute_browser_action" with "_execute_action"

This one wasn't in the Checklist either, and I also couldn't find anything related to this change in the docs, but I figure out the change through my own intuition 😂.

We used to have a command defined in our manifest.json called _execute_browser_action that automatically (without adding any extra code) will trigger our extension's popup (browser action).

After updating to Manifest v3, this command wasn't working, and I figured it was because of the merge between browserAction and pageAction into the new action API. So I changed _execute_browser_action to _execute_action, and it worked 🎉.

{
    "commands": {
        "_execute_action": {
            "suggested_key": {
                "default": "Alt+Shift+1"
            }
        }
    }
}

2.2.7. Refactor to use promises

Finally, after everything else was working, I decided to refactor my code to use promises in the APIs that support them.

Here are some examples:

// Using callback:
chrome.action.setBadgeBackgroundColor({ color: '#F00' }, () => {
    chrome.action.setBadgeText({ text: 'grr' });
});

// Using promises:
await chrome.action.setBadgeBackgroundColor({ color: '#F00' });
await chrome.action.setBadgeText({ text: 'grr' });

// Optional callback:
chrome.tabs.create({ url: ev.srcElement.href, active: false });

// Using promises:
await chrome.tabs.create({ url: ev.target.href, active: false });

// Using callback:
    chrome.tabs.query(query, (tabs) => {
        // callback logic
    });
});

// Using promises:
const tabs = await chrome.tabs.query(query);

Remember: You don't need to refactor your code to use promises right away. Callbacks are still supported in Manifest v3.

One thing to notice is that I couldn't make promises to work with the chrome.storage API. This may be one of the APIs that don't support promises yet, but I couldn't find more information on the subject in the docs.

Here's the commit if you're interested.

Done!

Our sample extension was successfully migrated to Manifest v3.

The repo

You can find this and all of the examples of this series in my repo:

pawap90 / acho-where-are-we

Acho (a cute pup) tells you the title of the current page on your browser. A sample chrome extension.

Hope you found this article useful!

💬 Let me know what you think in the comments!

Chrome Extensions: Adding a badge

Paula Santamaría — Fri, 19 Mar 2021 00:08:25 +0000

I thought I should add some new fun features to our sample extension to explore a few more things that can be done with Chrome extensions. I was curious about badges because they seem like an interesting tool to communicate changes in the state of our extension to our users.

About badges

Badges appear over the Browser Action Icon and include a short text.

The text can include a number of characters, but the badge will only show the amount that fits in that tiny space (the docs say around 4, but I could fit a maximum of 6). The characters that don't fit won't be visible, so try to keep your badge text short.

To create a badge all we need to do is set the text, like so:



chrome.browserAction.setBadgeText({ tabId: myTabId, text: 'grr' });
// or to add it to all tabs:
chrome.browserAction.setBadgeText({ text: 'grr' });

The tabId is optional, but when included, the text specified for the badge will only be visible when that particular tab is active.
The text is optional too, but the badge won't be visible if we don't include it.

So, to hide the badge all we need to do is set the text for that particular tab to null:



chrome.browserAction.setBadgeText({ tabId: myTabId, text: null });
// or, the shorter version:
chrome.browserAction.setBadgeText({ tabId: myTabId });
// or to remove it from all tabs:
chrome.browserAction.setBadgeText({ });

For extra customization, we can also change the background color of the badge (the default is blue):



chrome.browserAction.setBadgeBackgroundColor({ color: '#F00' }, () => {
    // callback
});

Updating our sample extension

You see, 🐶 Acho gets impatient whenever a new page or tab is loaded and we don't ask him about it right away (I mean, it's his job!). So we'll give him a tool to express himself:

When a new tab is created, or the active tab gets updated, Acho will let us know he's ready to work by creating a badge.
After his job is done, the badge will disappear.

Here's how it will look:

So first, we'll update the Acho class acho.js to give him the ability to growl and be quiet:



// acho.js
class Acho {

    growl = () => {
        chrome.browserAction.setBadgeBackgroundColor({ color: '#F00' }, () => {
            chrome.browserAction.setBadgeText({ text: 'grr' });
        });
    }

    quiet = () => {
        chrome.browserAction.setBadgeText({});
    }
}

Then we'll listen for the tabs.onCreated and tabs.onUpdated events in our background.js, and when they're fired we'll let Acho growl using the growl method we just added:



// background.js
chrome.tabs.onUpdated.addListener((tabId, changeInfo, tab) => {
    new Acho().growl();
});

chrome.tabs.onCreated.addListener(tab => {
    new Acho().growl();
});

And finally, we'll ask Acho to be quiet when he fulfills his job. This must be done both in the background.js file and the popup.js file since Acho can do his job through the browser action (popup) or a command handled in the background script.

In the background script, we must add a new line at the end of our barkTitle method. So, once the notification is sent, we can remove the badge:



// background.js
const barkTitle = async () => {
    const acho = new Acho();
    const tab = await acho.getActiveTab();

    chrome.tabs.sendMessage(tab.id, {
        tabTitle: tab.title
    });

    await PageService.savePage(tab.title, tab.url);

    acho.quiet();   // 👈
}

In the popup.js, we will remove the notification after loading all the info in the popup:



// popup.js
document.addEventListener('DOMContentLoaded', async () => {

    const dialogBox = document.getElementById('dialog-box');

    const acho = new Acho();
    const tab = await acho.getActiveTab();
    const bark = acho.getBarkedTitle(tab.title);

    dialogBox.innerHTML = bark;

    // Store page.
    await PageService.savePage(tab.title, tab.url);

    // Display history.
    await displayPages();

    // Clear history
    const clearHistoryBtn = document.getElementById('clear-history');
    clearHistoryBtn.onclick = async () => {
        await PageService.clearPages();
        await displayPages();
    };

    acho.quiet();   // 👈
});

Done!

That's it! We learned how to add a badge, hide it and change its color, and now Acho can express his frustration when we don't let him fulfill his purpose 😂.

The repo

You can find this and all of the examples of this series in my repo:

pawap90 / acho-where-are-we

Acho (a cute pup) tells you the title of the current page on your browser. A sample chrome extension.

Publishing a Chrome Extension

Paula Santamaría — Fri, 12 Mar 2021 11:10:57 +0000

This series wouldn't be complete without a post about how to publish a Chrome Extension, so here it is!

1. Prepare the extension to be published

We need to create a .zip file containing the source code for our extension. The only required file is the manifest.json, but we'll need to include the whole project if we want everything to work correctly.

We'll later upload this file to the Chrome Developer Dashboard.

2. Create a Chrome developer account

To register as a Chrome Web Store developer, we'll need to access the developer console.
Once we do that, we'll have to accept the Developer Agreement and Privacy Policies and pay the $5 registration fee (a one-time payment).

Don't forget to access the Account panel and fill in your email address. If you don't, you won't be able to publish an extension.

3. Publish the extension

We'll go to the "Items" panel and click over the "New Item" button to publish our extension.
We'll see a modal where we'll drop our .zip file (the one created in step 1).

After uploading the file, we'll be redirected to the "Store Listing" form. Here we'll have to fill all required fields, which include:

Name
Description
Category
Language
Small Icon (128 x 128 px)
At least one Screenshot

After filling all the required fields, we should go ahead and do the same on the "Privacy practices" form. Here we'll need to explain the purpose of the extension and justify why we need each of the permissions we listed in our manifest.json.

Host Permission Justification
Given that we added a content script with access to all the web pages visited by our users in this example, we'll need to justify why we need that, and our extension will take longer to get verified.

After completing all fields in both forms, check the buttons at the top-right of the screen:

If the button "Submit for review" is greyed out, click over "Why can't I submit?" to learn what's missing.

Once we've met all the requirements, click "Submit for review":

Now our extension is submitted, and we just need to wait for it to be reviewed and approved!

In this case, since we added a content script that requires access to all web pages, we'll need to wait a little longer for the review.

The repo

You can find all of the examples of this series in my repo:

pawap90 / acho-where-are-we

Acho (a cute pup) tells you the title of the current page on your browser. A sample chrome extension.

Chrome extensions: Local storage

Paula Santamaría — Wed, 24 Feb 2021 11:34:40 +0000

I'm back with another post about Chrome extensions! This time I wanted to explore how to store data locally using the chrome.storage API.

In this post, we're going to add yet another feature to our original extension (Acho, where are we?). This new feature will store the Title and URL of the page each time we call Acho to tell us where we are. We will then list all of the pages and allow the user to navigate to one of them or clear the list.

Here's a quick demo:

So let's get started!

1. Add the storage permission to the manifest.json

As usual, the first thing we need to update is our manifest.json. This time we're going to add the storage permission:



{
    "manifest_version": 2,
    "name": "Acho, where are we?",
    ... 
    "permissions": [
        "tabs",
        "storage"   // 👈
    ]
}

This will allow our extension to use the storage API.

2. Create the Page Service

Since we already know how to reuse code in chrome extensions, we will create the data access logic in a separate class called PageService. Here we will add the following methods:

getPages: Will return the list of stored pages.
savePage: Will receive the page data and store it.
clearPages: Will remove all the pages from the storage.

About the storage API

The chrome.storage API allows us to store objects using a key that we will later use to retrieve said objects. This API is a bit more robust than the localStorage API, but it's not as powerful as an actual database, so we will need to manage some things ourselves.

To save an object we will define a key-value pair and use the set method. Here's an example:



const key = 'myKey';
const value = { name: 'my value' };

chrome.storage.local.set({key: value}, () => {
  console.log('Stored name: ' + value.name);
});

And to retrieve our value we will use the get method and the key:



const key = 'myKey';
chrome.storage.local.get([key], (result) => {
  console.log('Retrieved name: ' + result.myKey.name);
});

Finally, to clear the storage we have two options:



// Completely clear the storage. All items are removed.
chrome.storage.local.clear(() => {
    console.log('Everything was removed');
});

// Remove items under a certain key
const key = 'myKey';
chrome.storage.local.remove([key], (result) => {
  console.log('Removed items for the key: ' + key);
});

Another thing to have in mind when working with this API is error handling. When an error occurs using the get or set methods, the property chrome.runtime.lastError will be set. So we need to check for that value after calling the get/set methods. A few examples:



const key = 'myKey';
const value = { name: 'my value' };

chrome.storage.local.set({key: value}, () => {
    if (chrome.runtime.lastError)
        console.log('Error setting');

    console.log('Stored name: ' + value.name);
});

chrome.storage.local.get([key], (result) => {
    if (chrome.runtime.lastError)
        console.log('Error getting');

    console.log('Retrieved name: ' + result.myKey.name);
});

Don't worry, I promise the actual implementation will be better than a console.log.

And, before we move on to the real implementation, I wanted to show you something else. I like to work with async/await instead of callbacks. So I created a simple function to promisify the callbacks and still handle errors properly. Here it is:



const toPromise = (callback) => {
    const promise = new Promise((resolve, reject) => {
        try {
            callback(resolve, reject);
        }
        catch (err) {
            reject(err);
        }
    });
    return promise;
}

// Usage example: 
const saveData = () => {
    const key = 'myKey';
    const value = { name: 'my value' };

    const promise = toPromise((resolve, reject) => {
        chrome.storage.local.set({ [key]: value }, () => {
            if (chrome.runtime.lastError)
                reject(chrome.runtime.lastError);

            resolve(value);
        });
    });
}

// Now we can await it:
await saveData();

You can replace chrome.storage.local with chrome.storage.sync to sync the data automatically to any Chrome browser where the user is logged into (if they have the sync feature enabled). But keep in mind that there are limits, as specified in the official documentation.

chrome.storage.local also has limits in the amount of data that can be stored, but that limit can be ignored if we include the unlimitedStorage permission in the manifest.json (check the docs).

Let's move on to our actual implementation!

PageService class

As I said before, our PageService will have 3 methods to store, retrieve and remove our pages. So here they are:



const PAGES_KEY = 'pages';

class PageService {

    static getPages = () => {
        return toPromise((resolve, reject) => {
            chrome.storage.local.get([PAGES_KEY], (result) => {
                if (chrome.runtime.lastError)
                    reject(chrome.runtime.lastError);

                const researches = result.pages ?? [];
                resolve(researches);
            });
        });
    }

    static savePage = async (title, url) => {
        const pages = await this.getPages();
        const updatedPages = [...pages, { title, url }];

        return toPromise((resolve, reject) => {

            chrome.storage.local.set({ [PAGES_KEY]: updatedPages }, () => {           
                if (chrome.runtime.lastError)
                    reject(chrome.runtime.lastError);
                resolve(updatedPages);
            });
        });
    }

    static clearPages = () => {
        return toPromise((resolve, reject) => {
            chrome.storage.local.remove([PAGES_KEY], () => {
                if (chrome.runtime.lastError)
                    reject(chrome.runtime.lastError);
                resolve();
            });
        });
    }
}

A few things to notice about this class:

We are using the toPromise function we talked about earlier.
We are storing an array of pages, so every time we add a new page to the storage, we need to retrieve the entire array, add our new element at the end and replace the original array in storage. This is one of a few options I came up with to work with arrays and the chrome.storage API since it doesn't allow me to directly push a new element to the array.

3. Make our PageService available to our components

As we saw in the previous posts of this series, we need to make some changes to allow our new class to be used by our extension's different components.

First, we will add it as a script to our popup.html so we can later use it in popup.js:



<!-- popup.html -->

<!DOCTYPE html>
<html lang="en">
<head>
    ...
</head>
<body>
    ...
    <script src='popup.js'></script>
    <script src='acho.js'></script>
    <script src='page.service.js'></script> <!-- 👈 -->
</body>
</html>

This will allow us to save pages, retrieve them and clear them from the browser action.

And finally, we'll add it as a background script in our manifest.json so we can also call the savePage method from our background script when the user uses the shortcut:



{
    "manifest_version": 2,
    "name": "Acho, where are we?",
    ...
    "background": {
        "scripts": [ 
            "background.js", 
            "acho.js", 
            "page.service.js" // 👈
        ],
        "persistent": false
    },
    ...
}

4. Update our popup.js

Now let's update our popup.js to add the new features.



document.addEventListener('DOMContentLoaded', async () => {

    const dialogBox = document.getElementById('dialog-box');

    const acho = new Acho();
    const tab = await acho.getActiveTab();
    const bark = acho.getBarkedTitle(tab.title);

    dialogBox.innerHTML = bark;

    // Store page.
    await PageService.savePage(tab.title, tab.url);

    // Display history.
    await displayPages();

    // Clear history.
    const clearHistoryBtn = document.getElementById('clear-history');
    clearHistoryBtn.onclick = async () => {
        await PageService.clearPages();
        await displayPages();
    };
});

const displayPages = async () => {
    const visitedPages = await PageService.getPages();
    const pageList = document.getElementById('page-list');
    pageList.innerHTML = '';

    visitedPages.forEach(page => {
        const pageItem = document.createElement('li');
        pageList.appendChild(pageItem);

        const pageLink = document.createElement('a');
        pageLink.title = page.title;
        pageLink.innerHTML = page.title;
        pageLink.href = page.url;
        pageLink.onclick = (ev) => {
            ev.preventDefault();
            chrome.tabs.create({ url: ev.srcElement.href, active: false });
        };
        pageItem.appendChild(pageLink);
    });
}

So in the previous code, we are using our three methods from PageService to add the current page to the storage, list the pages on the screen and allow the user to navigate them, and clear the list.

We use the displayPages method to display the pages: To do that we retrieve the list of pages and generate a <li> element and an <a> element for each page. It's important to notice that we need to override the onclick event on our <a> element because if we leave the default functionality, the extension will try to load the page inside our popup, which it's not what we want and it will cause an error. Instead, we create a new tab and navigate to the link using chrome.tabs.create.

That's all we need to do to add the new feature to our popup.

5. Saving the page from the background script

Now let's make sure the pages are also stored when we use the command shortcut. To achieve that all we need to do is call the savePage method when the user executes the command:



 //background.js

 chrome.commands.onCommand.addListener(async (command) => {
    switch (command) {
        case 'duplicate-tab':
            await duplicateTab();
            break;
        case 'bark':
            await barkTitle();
            break;
        default:
            console.log(`Command ${command} not found`);
    }
});

const barkTitle = async () => {
    const acho = new Acho();
    const tab = await acho.getActiveTab();

    chrome.tabs.sendMessage(tab.id, {
        tabTitle: tab.title
    });

    await PageService.savePage(tab.title, tab.url); // 👈
}

That's it!

The repo

You can find this and all of the previous examples of this series in my repo:

pawap90 / acho-where-are-we

Acho (a cute pup) tells you the title of the current page on your browser. A sample chrome extension.

Let me know what you think! 💬

Are you working on or have you ever built a Chrome extension?
How do you manage data storage?

Mastering NPM Scripts

Paula Santamaría — Mon, 15 Feb 2021 13:15:23 +0000

You may have come across the scripts property in the package.json file and even write some scripts yourself. But do you know all you can do with NPM Scripts?

I've been using NPM Scripts for years, but I wanted to pass a parameter to a script a few weeks ago and realized I didn't know how to do that. That's when I decided to learn everything I could about NPM scripts and write this article.

In this article, I'll share my research about how to take full advantage of NPM scripts.

Introduction
- npm run
Built-in scripts and Aliases
Executing multiple scripts
Understanding errors
Run scripts silently or loudly
- About log levels
Referencing scripts from files
Pre & Post
Access environment variables
Passing arguments
- Arguments as environment variables
Naming conventions
- Prefixes
Documentation
Conclusion

Introduction

NPM Scripts are a set of built-in and custom scripts defined in the package.json file. Their goal is to provide a simple way to execute repetitive tasks, like:

Running a linter tool on your code
Executing the tests
Starting your project locally
Building your project
Minify or Uglify JS or CSS

You can also use these scripts in your CI/CD pipeline to simplify tasks like build and generate test reports.

To define an NPM script, all you need to do is set its name and write the script in the script property in your package.json file:

{
    "scripts": {
        "hello-world": "echo \"Hello World\""
    }
}

It's important to notice that NPM makes all your dependencies' binaries available in the scripts. So you can access them directly as if they were referenced in your PATH. Let's see it in an example:

Instead of doing this:

{
    "scripts": {
        "lint": "./node_modules/.bin/eslint .",
    }
}

You can do this:

{
    "scripts": {
        "lint": "eslint ."
    }
}

npm run

Now all you need to do is run npm run hello-world on the terminal from your project's root folder.

> npm run hello-world

"Hello World"

You can also run npm run, without specifying a script, to get a list of all available scripts:

> npm run

Scripts available in sample-project via `npm run-script`:
    hello-world
        echo "Hello World"

As you can see, npm run prints both the name and the actual script for each script added to the package.json.

ℹ️ npm run is an alias for npm run-script, meaning you could also use npm run-script hello-world. In this article, we'll use npm run <script> because it's shorter.

Built-in scripts and Aliases

In the previous example, we created a custom script called hello-world, but you should know that npm also supports some built-in scripts such as test and start.

Interestingly, unlike our custom scripts, these scripts can be executed using aliases, making the complete command shorter and easier to remember. For example, all of the following commands will run the test script.

npm run-script test
npm run test
npm test
npm t

Similarly to the test command, all of the following will run the start command:

npm run-script start
npm run start
npm start

For these built-in scripts to work, we need to define a script for them in the package.json. Otherwise, they will fail. We can write the scripts just as any other script. Here's an example:

{
    "scripts": {
        "start": "node app.js",
        "test": "jest ./test",
        "hello-world": "echo \"Hello World\""
    }
}

Executing multiple scripts

We may want to combine some of our scripts and run them together. To do that, we can use && or &.

To run multiple scripts sequentially, we use &&. For example: npm run lint && npm test
To run multiple scripts in parallel, we use &. Example: npm run lint & npm test
- This only works in Unix environments. In Windows, it'll run sequentially.

So, for example, we could create a script that combines two other scripts, like so:

{
    "scripts": {
        "lint": "eslint .",
        "test": "jest ./test",
        "ci": "npm run lint && npm test"
    }
}

Understanding errors

When a script finishes with a non-zero exit code, it means an error occurred while running the script, and the execution is terminated.

That means we can purposefully end the execution of a script with an error by exiting with a non-zero exit code, like so:

{
    "scripts": {
        "error": "echo \"This script will fail\" && exit 1"
    }
}

When a script throws an error, we get a few other details, such as the error number errno and the code. Both can be useful for googling the error.

And if we need more information, we can always access the complete log file. The path to this file is provided at the end of the error message. On failure, all logs are included in this file.

Run scripts silently or loudly

Use npm run <script> --silent to reduce logs and to prevent the script from throwing an error.

The --silent flag (short for --loglevel silent) can be helpful when you want to run a script that you know may fail, but you don't want it to throw an error. Maybe in a CI pipeline, you want your whole pipeline to keep running even when the test command fails.

It can also be used as -s: npm run <script> -s

ℹ️ If we don't want to get an error when the script doesn't exists, we can use --if-present instead: npm run <script> --if-present.

About log levels

We saw how we can reduce logs using --silent, but what about getting even more detailed logs? Or something in between?

There are different log levels: "silent", "error", "warn", "notice", "http", "timing", "info", "verbose", "silly". The default is "notice". The log level determines which logs will be displayed in the output. Any logs of a higher level than the currently defined will be shown.

We can explicitly define which loglevel we want to use when running a command, using --loglevel <level>. As we saw before, the --silent flag is the same as using --loglevel silent.

Now, if we want to get more detailed logs, we'll need to use a higher level than the default ("notice"). For example: --loglevel info.

There are also short versions we can use to simplify the command:

-s, --silent, --loglevel silent
-q, --quiet, --loglevel warn
-d, --loglevel info
-dd, --verbose, --loglevel verbose
-ddd, --loglevel silly

So to get the highest level of detail we could use npm run <script> -ddd or npm run <script> --loglevel silly.

Referencing scripts from files

You can execute scripts from files. This can be useful for especially complex scripts that would be hard to read in the package.json file. However, it doesn't add much value if your script is short and straightforward.

Consider this example:

{
    "scripts": {
        "hello:js": "node scripts/helloworld.js",
        "hello:bash": "bash scripts/helloworld.sh",
        "hello:cmd": "cd scripts && helloworld.cmd"
    }
}

We use node <script-path.js> to execute JS files and bash <script-path.sh> to execute bash files.

Notice that you can't just call scripts/helloworld.cmd for CMD and BAT files. You'll need to navigate to the folder using cd first. Otherwise, you'll get an error from NPM.

Another advantage of executing scripts from files is that, if the script is complex, it'll be easier to maintain in a separate file than in a single line inside the package.json file.

Pre & Post

We can create "pre" and "post" scripts for any of our scripts, and NPM will automatically run them in order. The only requirement is that the script's name, following the "pre" or "post" prefix, matches the main script. For example:

{
    "scripts": {
        "prehello": "echo \"--Preparing greeting\"",
        "hello": "echo \"Hello World\"",
        "posthello": "echo \"--Greeting delivered\""
    }
}

If we execute npm run hello, NPM will execute the scripts in this order: prehello, hello, posthello. Which will result in the following output:

> script-test@1.0.0 prehello
> echo "--Preparing greeting"

"--Preparing greeting"

> script-test@1.0.0 hello
> echo "Hello World"

"Hello World"

> script-test@1.0.0 posthello
> echo "--Greeting delivered"

"--Greeting delivered"

ℹ️ If we run prehello or posthello individually, NPM will not automatically execute any other scripts. It only works if you run the "main" script, in this case, hello.

Access environment variables

While executing an NPM Script, NPM makes available a set of environment variables we can use. These environment variables are generated by taking data from NPM Configuration, the package.json, and other sources.

Configuration parameters are put in the environment using the npm_config_ prefix. Here are a few examples:

{
    "scripts": {
        "config:loglevel": "echo \"Loglevel: $npm_config_loglevel\"",
        "config:editor": "echo \"Editor: $npm_config_editor\"",
        "config:useragent": "echo \"User Agent: $npm_config_user_agent\""
    }
}

Let's see what we get after executing the above commands:

> npm run config:loglevel
# Output: "Loglevel: notice"

> npm run config:editor
# Output: "Editor: notepad.exe"

> npm run config:useragent
# Output: "User Agent: npm/6.13.4 node/v12.14.1 win32 x64"

ℹ️ You can also run npm config ls -l to get a list of all the configuration parameters available.

Similarly, package.json fields, such as version and main, are included with the npm_package_ prefix. Let's see a few examples:

{
    "scripts": {
        "package:main": "echo \"Main: $npm_package_main\"",
        "package:name": "echo \"Name: $npm_package_name\"",
        "package:version": "echo \"Version: $npm_package_version\""
    }
}

The results from these commands will be something like this:

> npm run package:main
# Output: "Main: app.js"

> npm run package:name
# Output: "Name: npm-scripts-demo"

> npm run package:version
# Output: "Version: 1.0.0"

Finally, you can add your own environment variables using the config field in your package.json file. The values setup there will be added as environment variables using the npm_package_config prefix.

{
    "config": {
        "my-var": "Some value",
        "port": 1234
    },
    "script": {
        "packageconfig:port": "echo \"Port: $npm_package_config_port\"",
        "packageconfig:myvar": "echo \"My var: $npm_package_config_my_var\""
    }
}

If we execute both commands we'll get:

> npm run packageconfig:port
# Output: "Port: 1234"

> npm run packageconfig:myvar
# Output: "My var: Some value"

ℹ️ In Windows' cmd instead of $npm_package_config_port you should use %npm_package_config_port% to access the environment variables.

Passing arguments

In some cases, you may want to pass some arguments to your script. You can achieve that using -- that the end of the command, like so: npm run <script> -- --argument="value".

Let's see a few examples:

{
    "scripts": {
        "lint": "eslint .",
        "test": "jest ./test",
    }
}

If I wanted to run only the tests that changed, I could do this:

> npm run test -- --onlyChanged

And if I wanted to run the linter and save the output in a file, I could execute the following command:

> npm run lint -- --output-file lint-result.txt

Arguments as environment variables

Another way of passing arguments is through environment variables. Any key-value pairs we add to our script will be translated into an environment variable with the npm_config prefix. Meaning we can create a script like this:

{
    "scripts": {
        "hello": "echo \"Hello $npm_config_firstname!\""
    }
}

And then use it like so:

> npm run hello --firstname=Paula
# Output: "Hello Paula"

Naming conventions

There are no specific guidelines about how to name your scripts, but there are a few things we can keep in mind to make our scripts easier to pick up by other developers.

Here's my take on the subject, based on my research:

Keep it short: If you take a look at Svelte's NPM Scripts, you'll notice that most script names are one word only. If we can manage to keep our script names short, it'll be easier to remember them when we need them.
Be consistent: You may need to use more than one word to name your script. In that case, choose a naming style and stick to it. It can be camelCase, kebab-case, or anything you prefer. But avoid mixing them.

Prefixes

One convention that you may have seen is using a prefix and a colon to group scripts, for example, "build:prod". This is simply a naming convention. It doesn't affect your scripts' behavior but can be helpful to create groups of scripts that are easier to identify by their prefixes.

Example:

{
    "scripts": {
        "lint:check": "eslint .",
        "lint:fix": "eslint . --fix",
        "build:dev": "...",
        "build:prod": "..."
    }
}

Documentation

Consider adding documentation for your scripts so other people can easily understand how and when to use them. I like to add a few lines explaining each script on my Readme file.

The documentation for each available script should include:

Script name
Description
Accepted arguments (optional)
Links to other documentation (optional): For example, if your script runs tsc --build, you may want to include a link to Typescript docs.

Conclusion

This is all I managed to dig up about NPM Scripts. I hope you find it useful! I certainly learned a lot just by doing this research. It took me way more time than I thought it would, but it was totally worth it.

Let me know if there's anything missing that you'll like to add to make this guide even more complete! 💬

4 podcasts for aspiring entrepreneurs

Paula Santamaría — Thu, 04 Feb 2021 11:53:46 +0000

I love podcasts. I love them for many reasons, but the most important is that a few years ago, listening to podcasts helped me find the motivation I needed to start working on my own projects.

I don't even remember how I first got into it, but somehow I started listening to podcasts about freelancing and entrepreneurship on my bus back home every day after work. Listening to hundreds of stories about different people who managed to make a living in unconventional ways and chasing their dreams was really inspiring and eye-opening. At that point in my life, I had already worked 5 years for a company and was realizing that I didn't want to do the typical 9 to 5 job. These podcasts were precisely the push I needed to move on.

I still have a long way to go with my career, but I'm really happy with how it's developing so far.

So I decided to write this post to share some of my favorite podcasts about entrepreneurship in the hope that they inspire you and give you the courage to keep working towards your dreams too:

1. Hack the Entrepreneur

I've been listening to HTE for years. I never get tired of it. Every episode, the host, Jon Nastor, interviews an entrepreneur. The guests range between solo entrepreneurs and multimillion-dollar startup founders. During these ~40 minute interviews, Jon asks them about their growth, business, motivations, etc.

I found this podcast to be not only inspiring but also really informative. The guests are not always from the tech world, so you may think that their interviews won't give you as much value, but I realized it's the opposite. I learned a lot by listening to how people from different backgrounds manage their business.

Hack the Entrepreneur Website

2. She Did It Her Way

I came across this podcast recently and was instantly hooked. Most episodes are between 15 and 25 minutes long, and every single minute is full of valuable content.

The host, Amanda Boleyn, talks about business and offers practical tips on how to get your own business running. She also interviews other women entrepreneurs who talk about their stories, how they became entrepreneurs, and their businesses.

She Did It Her Way Website

3. The Ground Up Show

One of the things I got interested in when I started thinking about freelancing was minimalism. Many freelancers, digital nomads, and entrepreneurs use minimalism to reduce their living costs and focus on what's important to them.

Matt D'Avella was the filmmaker behind the Netflix documentary about minimalism and later started The Ground Up Show.

In this podcast, Matt meets with creatives and interviews them about their content and their businesses.

You can also watch the interviews on YouTube if you prefer.

The Ground Up Show Website

4. Company of One

The Company of One podcast has only 21 episodes, and they're all great. What I love about this podcast it's how it shows you how business can succeed by challenging the common belief that bigger is better. It's fascinating to see how small businesses can apply creative solutions to solve their issues and succeed.

The host is Paul Jarvis, author of "Company of One: Why Staying Small Is the Next Big Thing for Business." Episodes range between 5 and 15 minutes long and will leave you thinking.

Company of One Podcast Website

What podcasts do you listen to?

I love to learn about new podcasts! Do you have any recommendations?