DEV Community: Guillermo Peralta Scura

How a DevTools Extension is Made

Guillermo Peralta Scura — Tue, 07 Jul 2020 11:58:02 +0000

I've never built any browser extension, much less one for the Devtools.

Out of curiosity I started looking around and I've found the Google Chrome DevTools Extensions docs that served as an introduction of the different parts involved, but it wasn't enough to get on my feet and start developing my own.

The problem was that I lacked knowledge about the basic concepts behind a browser extension.

The complete Google Chrome extensions documentation is extensive, and in many cases serves more like an API reference rather than a guide, but it gave me a broad picture about the multiple moving parts that are involved, and to learn that you even need to build an intercommunication bus between the different components of the extension.

But beyond that, there wasn't a good resource for me to have a complete picture of what was required and what would be the most useful for a DevTools extension since it's a subset of what browser extensions can do.

A pragmatic way to learn about all of this that I decided to take is through open-source code. Initially, I started looking into the React DevTools, but since it's part of the React monorepo it would take some time to identify each of the relevant packages.

Fortunately for my needs, the Vue DevTools repo is self-contained, allowing me to examine it in complete isolation from other parts of the Vue code.

This is a guide through the main parts of the official Vue DevTools extension to learn from it and understand a successful approach for building these kinds of tools.

I hope that this way you can learn with a real-world example what exactly each file does, and how everything fits together. This guide isn't Vue specific in any way, You don't need to be familiar with Vue at all to follow and hopefully learn something from this guide.

This guide is divided under different sections and goes step by step with links to the official source code and analyzing some relevant snippets along the way.

Let's dive right into it!

Vue Devtools Overview
- Manifest file
- Types of scripts
- Vue DevTools architecture
Vue detector
Background script
Hook
DevTools page
Backend and Frontend
- Bridge
Proxy
Frontend
Backend

Vue Devtools Overview

The code, which is hosted on GitHub, is organized as a monorepo consisting of different packages, under the /packages directory.

I followed the manual installation instructions and I was able to get a development version of the extension up and running on my browser.

By following those instructions I learned that we should start by looking into the shell-chrome directory, as the starting point of this journey. Here we find the manifest.json file, which contains all the metadata related to the browser extension.

Manifest file

Here we can find some relevant entry points:

  "devtools_page": "devtools-background.html",
  "background": {
    "scripts": [
      "build/background.js"
    ],
    "persistent": false
  },
    "content_scripts": [
    {
      "matches": [
        "<all_urls>"
      ],
      "js": [
        "build/hook.js"
      ],
      "run_at": "document_start"
    },
    {
      "matches": [
        "<all_urls>"
      ],
      "js": [
        "build/detector.js"
      ],
      "run_at": "document_idle"
    }
  ]

Each of those specified files can be seen as different entry points because browser extensions are composed of multiple scripts that run in different contexts.

Before jumping into studying these files in detail, I'll like to briefly focus on the build tooling for this project.

Notice how all of these paths start with build/ but we don't have a build directory inside shell-chrome. Let's take a quick look at our inner package.json file to understand why:

// shell-chrome/package.json

{
  "name": "@vue-devtools/shell-chrome",
  "version": "0.0.0",
  "dependencies": {
    "@vue-devtools/app-backend": "^0.0.0",
    "@vue-devtools/app-frontend": "^0.0.0",
    "@vue-devtools/shared-utils": "^0.0.0"
  },
  "devDependencies": {
    "@vue-devtools/build-tools": "^0.0.0",
    "webpack": "^4.19.0",
    "webpack-cli": "^3.1.0"
  }
}

It defines other packages from the monorepo as dependencies. The internal packages are those prefixed with @vue-devtools.

The way this monorepo is structured is by using Yarn workspaces. Let's go to the root package.json of the whole project:

  "workspaces": [
    "packages/*"
  ],

Everything under the packages directory is part of this monorepo. Now let's see what the main build script looks like:

"build": "cd packages/shell-chrome && cross-env NODE_ENV=production webpack --progress --hide-modules"

That's it! Now we know that inside packages/shell-chrome the project is using Webpack to produce a build. So that's when the build folder must be being created.

Analyzing the whole build process of this extension is out of scope for this post but if you're interested in learning more about it, this webpack.config.js file is a good place to start.

Types of scripts

The main type of scripts we are going to see are the following:

As part of this guide, I'll be introducing each one of them the moment we come across them on our journey through the Vue DevTools extension.

Now, let's jump into the actual logical architecture of this extension.

Vue DevTools architecture

Each different type of script represents a different entry point for a browser extension.

Vue detector

Let's start by looking at src/detector.js. This is a content script.

Content scripts are the parts of an extension that are running in the context of the current web page. They can query the DOM, make changes to it, and communicate with the parent extension context.

Unlike regular page scripts, they have one important limitation. Content scripts live in "isolated worlds". They can't access variables created by other scripts, even if those variables are added to the window global.

To workaround the "isolated worlds" limitation, detector.js includes this helper:

// shell-chrome/src/detector.js

function installScript (fn) {
  const source = ';(' + fn.toString() + ')(window)'

  if (isFirefox) {
    window.eval(source) // in Firefox, this evaluates on the content window
  } else {
    const script = document.createElement('script')
    script.textContent = source
    document.documentElement.appendChild(script)
    script.parentNode.removeChild(script)
  }
}

It wraps the provided fn function on a IIFE string to add it on the page. Now it can run just like any other regular script on the page.

// shell-chrome/src/detector.js

if (document instanceof HTMLDocument) {
  installScript(detect)
  installScript(installToast)
}

detector.js injects two functions using this technique, detect and installToast. These are known as... injected scripts.

The pattern of injected scripts is unofficial, but it became an ad-hoc standard by the community, based on the common case of needing to run scripts on the current page with full access to the window global and changes performed by other scripts.

I'll start with the installToast injected script. This function adds a __VUE_DEVTOOLS_TOAST__(message, type) method to the window object so that messages like "Remote Devtools Connected" can be shown. Its code is part of the app-backend package of the repo, under the toast.js module. Seeing a reference to "backend" might seem odd at this point. Don't worry too much about it now, we are going to explain it later.

The main code of the detector content script, however, is contained on the detect function (see the source code here). It polls the document for 10 seconds and checks for one of these possibilities:

window.__NUXT__ or window.$nuxt are detected.
There's an element inside the DOM tree that contains a __vue__ property.

In either case, the Vue constructor is extracted and postMessage is used to send a message to the window (i.e. from the injected script to the content script).

detector.js attaches an onMessage event listener to handle messages received from the injected scripts:

// shell-chrome/src/detector.js

window.addEventListener('message', e => {
  if (e.source === window && e.data.vueDetected) {
    chrome.runtime.sendMessage(e.data)
  }
})

You might be wondering what's that chrome global object, where does it come from? That's the "magic" of a content script. Content scripts have access to the Chrome Extension API. In this case, chrome.runtime.sendMessage is used to send the message received from the injected script to the background script.

Background script

Wait, what's a background script? Well, it's another type of script present in browser extensions.

A background script acts like an event listener which stays dormant until an event fires from either the DevTools page or a content script. It's used as a central message bus that communicates with the different scripts of our extension. They run in the context of the browser.

In the future, service workers are going to be used instead of background scripts as part of Google Chrome extensions. This change is part of a set of changes that are tracked under Manifest version 3 for extensions.

This background script, in particular, has a chrome.runtime.onMessage listener registered that can be used by any process that is part of the extension. Here it's only used by detector.js, so its code is not large:

// shell-chrome/src/backgroound.js

chrome.runtime.onMessage.addListener((req, sender) => {
  if (sender.tab && req.vueDetected) {
    const suffix = req.nuxtDetected ? '.nuxt' : ''

    chrome.browserAction.setIcon({
      tabId: sender.tab.id,
      path: {
        16: `icons/16${suffix}.png`,
        48: `icons/48${suffix}.png`,
        128: `icons/128${suffix}.png`
      }
    })
    chrome.browserAction.setPopup({
      tabId: sender.tab.id,
      popup: req.devtoolsEnabled ? `popups/enabled${suffix}.html` : `popups/disabled${suffix}.html`
    })
  }
})

That's the logic that makes the Vue DevTools extension icon colorful when Vue is detected on the current page, and as you can see, even the HTML file for the corresponding popup is referenced.

That's enough background script for now 😅. Later on, we are going to explore the rest of it.

Hook

Like detector.js, there was another content script declared on the manifest file. Remember, these are our entry points). This is hook.js.

// shell-chrome/src/hook.js

import { installHook } from '@back/hook'

This is the only line of specific code. The rest of the logic that you can check if you inspect its source code, is just the very same logic to inject a script that is used on detector.js.

I suspect that the installScript definition that we studied earlier could be extracted to a common module and imported from both content scripts. Might be something nice to try and perhaps send a PR for 👀.

@back on the @back/hook module path is an alias that is defined using Webpack. They are defined here. @back points to app-backend/src, so to learn more about installHook we need to open the hook.js module.

As the comments on top of that file explain, this is mainly an event emitter implementation that is exposed under the __VUE_DEVTOOLS_GLOBAL_HOOK__ global variable:

// app-backend/src/hook.js

Object.defineProperty(target, '__VUE_DEVTOOLS_GLOBAL_HOOK__', {
  get () {
    return hook
  }
})

After defining the event emitter, a listener for the init event is added:

// app-backend/src/hook.js

hook.once('init', Vue => {
  hook.Vue = Vue

  Vue.prototype.$inspect = function () {
    const fn = target.__VUE_DEVTOOLS_INSPECT__
    fn && fn(this)
  }
})

A Vue property is set on hook. It's a very important property since it's the main reference to the Vue instance of the currently inspected page.

I was confused for some time at this point. We already had detector.js that knows when there's a Vue instance, but it never invokes __VUE_DEVTOOLS_GLOBAL_HOOK__ in any way. What's going on here? When is this "init" event emitted? After a lot of debugging around the vue-devtools repository, I wasn't able to find it, it was surely not related to detector.js in any way, but where was the call to emit this event?

After A LOT of debugging, I found out that I wasn't looking at the correct place at all. Turns out it's done by the Vue runtime itself!!!

Here's the code under the core Vue repo:

import { devtools, inBrowser } from 'core/util/index'

/// ...

if (config.devtools) {
  if (devtools) {
    devtools.emit('init', Vue)
  } else if (
    process.env.NODE_ENV !== 'production' &&
    process.env.NODE_ENV !== 'test'
  ) {
    console[console.info ? 'info' : 'log'](
      'Download the Vue Devtools extension for a better development experience:\n' +
      'https://github.com/vuejs/vue-devtools'
    )
  }
}

Aha! devtools.emit('init', Vue) is the call that starts the magic. But what exactly is this config.devtools object?

If we follow the codebase we can check that the devtools object is defined to something familiar to us:

// detect devtools
export const devtools = inBrowser && window.__VUE_DEVTOOLS_GLOBAL_HOOK__

It's the exact window.__VUE_DEVTOOLS_GLOBAL_HOOK__ reference injected by the hook.js file that we saw earlier. Now we're closing the loop!

And that's it for the initial content scripts that unconditionally run for every web page we visit while the Vue DevTools extension is active. We also got to know our background script.

DevTools page

This journey continues by looking at the devtools_page property defined in the manifest file. It specifies a page that will be used when the user opens the DevTools panel of the browser (e.g. using the Ctrl/⌘ + J keys combination). Usually, that page only inserts a <script> tag that will handle all the actual logic that we want to run in the DevTools window context. In our case, this is the devtools_background.js file. That file is what is known as a devtools script:

// shell-chrome/src/devtools-background.js

// This is the devtools script, which is called when the user opens the
// Chrome devtool on a page. We check to see if we global hook has detected
// Vue presence on the page. If yes, create the Vue panel; otherwise poll
// for 10 seconds.

Those are the top comments of the file. Pretty self-explanatory! The "global hook" refers to window.__VUE_DEVTOOLS_GLOBAL_HOOK__.Vue, that as we just saw, will be defined if the Vue runtime emits the "init" event.

You can check the createPanelIfHasVue function to learn more about their polling mechanism (Recursive calls to setTimeout with 1000 ms of delay until a counter increments up to 10, effectively trying for 10 seconds).

Here's what then happens when Vue is detected:

chrome.devtools.panels.create(
  'Vue', 'icons/128.png', 'devtools.html',
  panel => {
    // panel loaded
    panel.onShown.addListener(onPanelShown)
    panel.onHidden.addListener(onPanelHidden)
  }
)

That's all the code that is required to add a new panel to the Chrome DevTools window! We define the title of the tab, its icon, the page to render and a callback to be invoked after creation.

Backend and Frontend

The actual DevTools panel is unsurprisingly, a regular Vue.js SPA. The HTML on devtools.html is mainly a placeholder to be filled once Vue takes over:

<body>
  <div id="container">
    <div id="app"></div>
  </div>
  <script src="./build/devtools.js"></script>
</body>

The SPA initialization logic is under the src/devtools.js script:

// shell-chrome/src/devtools.js

import { initDevTools } from '@front'
import Bridge from '@utils/bridge'

initDevTools({
  connect (cb) {
    // 1. inject backend code into page
    injectScript(chrome.runtime.getURL('build/backend.js'), () => {
      // 2. connect to background to setup proxy
      const port = chrome.runtime.connect({
        name: '' + chrome.devtools.inspectedWindow.tabId
      })
      let disconnected = false
      port.onDisconnect.addListener(() => {
        disconnected = true
      })

      const bridge = new Bridge({
        listen (fn) {
          port.onMessage.addListener(fn)
        },
        send (data) {
          if (!disconnected) {
            port.postMessage(data)
          }
        }
      })
      // 3. send a proxy API to the panel
      cb(bridge)
    })
}

After all the initial boilerplate, here is where stuff gets interesting 🎉. This DevTools extension follows a model based on two main actors: backend and frontend.

We can think of this like any regular client/server application where these two parts interchange information with each other. In our case, the "frontend" is the Vue DevTools panel itself, and our backend is a pair of content and injected scripts that run in the context of the inspected web page.

devtools.js adds the src/backend.js injected script to the page. Afterward, it establishes a connection to the background script and initializes an instance of a custom Bridge class registering two callbacks on it, listen and send, based on messages received from and sent to the background script respectively.

Before diving further into the frontend, let's take a look at what happens on src/backend.js:

// shell-chrome/src/backend.js

function sendListening () {
  window.postMessage({
    source: 'vue-devtools-backend-injection',
    payload: 'listening'
  }, '*')
}
sendListening()

The window (of the inspected page) is used as a communication mechanism. As soon as this script starts, this {source: 'vue-devtools-backend-injection', payload: 'listening'} message is sent.

// shell-chrome/src/backend.js

window.addEventListener('message', handshake)

function handshake (e) {
  if (e.data.source === 'vue-devtools-proxy' && e.data.payload === 'init') {
    window.removeEventListener('message', handshake)

    let listeners = []
    const bridge = new Bridge({
      listen (fn) {
        const listener = evt => {
          if (evt.data.source === 'vue-devtools-proxy' && evt.data.payload) {
            fn(evt.data.payload)
          }
        }
        window.addEventListener('message', listener)
        listeners.push(listener)
      },
      send (data) {
        window.postMessage({
          source: 'vue-devtools-backend',
          payload: data
        }, '*')
      }
    })

    // ...[some code ignored]

    initBackend(bridge)
  } else {
    sendListening()
  }
}

Just like on the DevTools panel, here a Bridge instance registering a pair of listen/send callbacks is constructed. However, instead of relying on the background script to propagate the messages, the window itself is used to listen to MessageEvents or trigger postMessage accordingly.

Bridge

Here is the Bridge constructor itself that both backend and frontend are using:

// shared-utils/src/bridge.js

import { EventEmitter } from 'events'

const BATCH_DURATION = 100

export default class Bridge extends EventEmitter {
  send (event, payload) {
    // ...
  }

  // Log a message to the devtools background page.
  log (message) {
    this.send('log', message)
  }

  _flush () {
    // ...
  }

  _emit (message) {
    // ...
  }

  _send (messages) {
    // ...
  }

  _nextSend () {
    // ...
  }
}

Bridge is an event emitter! And it's the main communication mechanism between the backend and the frontend.

Remember how as part of the Devtools panel initialization, on src/devtools.js, a background script connection was established?

// shell-chrome/src/devtools.js

// 1. inject backend code into page
injectScript(chrome.runtime.getURL('build/backend.js'), () => {
  // 2. connect to background to setup proxy
  const port = chrome.runtime.connect({
    name: '' + chrome.devtools.inspectedWindow.tabId
  })

Here is how the background script reacts to that:

// shell-chrome/src/background.js

chrome.runtime.onConnect.addListener(port => {
  let tab
  let name
  if (isNumeric(port.name)) {
    tab = port.name
    name = 'devtools'
    installProxy(+port.name)
  } else {
    tab = port.sender.tab.id
    name = 'backend'
  }

  if (!ports[tab]) {
    ports[tab] = {
      devtools: null,
      backend: null
    }
  }
  ports[tab][name] = port

  if (ports[tab].devtools && ports[tab].backend) {
    doublePipe(tab, ports[tab].devtools, ports[tab].backend)
  }
})

If port.name from the incoming connection to the background script is numeric, then it's assumed to be the Devtools panel and thus, installProxy is invoked (the + prefixed to port.name is used to coerce the string value to a number).

// shell-chrome/src/background.js

function installProxy (tabId) {
  chrome.tabs.executeScript(tabId, {
    file: '/build/proxy.js'
  }, function (res) {
    if (!res) {
      ports[tabId].devtools.postMessage('proxy-fail')
    } else {
      console.log('injected proxy to tab ' + tabId)
    }
  })
}

Proxy

installProxy adds a new content script: src/proxy.js. Unlike the two initial content scripts that are declared on the manifest.json file and are executed on every page load, this one is dynamically added using the chrome.tabs.executeScript API under the condition we saw earlier. Let's analyze what's this proxy.js content script is about:

// shell-chrome/src/proxy.js

const port = chrome.runtime.connect({
  name: 'content-script'
})

port.onMessage.addListener(sendMessageToBackend)
window.addEventListener('message', sendMessageToDevtools)
port.onDisconnect.addListener(handleDisconnect)

In the first place, proxy.js also connects to the background script and then sets up a listener for messages that the background script sends, in which case it forwards the message to the backend. Also, a listener for messages received from the inspected web page is set, in which case it forwards the message to the frontend - a.k.a. the Devtools panel.

// shell-chrome/src/proxy.js

sendMessageToBackend('init')

function sendMessageToBackend (payload) {
  window.postMessage({
    source: 'vue-devtools-proxy',
    payload: payload
  }, '*')
}

This might result familiar: An init message is sent to the backend, which is, as we saw earlier, what src/backend.js was waiting for on its handshake function to continue its initialization.

// shell-chrome/src/proxy.js

function sendMessageToDevtools (e) {
  if (e.data && e.data.source === 'vue-devtools-backend') {
    port.postMessage(e.data.payload)
  } else if (e.data && e.data.source === 'vue-devtools-backend-injection') {
    if (e.data.payload === 'listening') {
      sendMessageToBackend('init')
    }
  }
}

For propagating messages back to the frontend, it uses the connection to the background script. Despite its name, there's one case it sends an 'init' message to the backend instead. If the message received from the window is a 'listening' one. This is a special message that is sent by the backend itself to signal it's waiting for initialization.

Even though the Bridge instances are constructed on src/devtools.js and src/backend.js, they both send those instances to the respective frontend and backend packages of the extension through callbacks.

In the case of src/devtools.js:

// shell-chrome/src/devtools.js

import { initDevTools } from '@front'

initDevTools({
  connect (cb) {
    injectScript(chrome.runtime.getURL('build/backend.js'), () => {
      // ...
      const bridge = new Bridge({
        // ...
      })
      cb(bridge)
    })
  }

In the case of src/backend.js:

// shell-chrome/src/backend.js

import { initBackend } from '@back'

function handshake (e) {
  if (e.data.source === 'vue-devtools-proxy' && e.data.payload === 'init') {
    // ...
    const bridge = new Bridge({
      // ...
    })

    // ...
    initBackend(bridge)
  }
}

So now that both the frontend and backend implementations hold instances to their respective communication bridge, we can take a look at how they use it.

Frontend

Let's take a look at the initDevTools function of app-frontend/src/index.js:

// app-frontend/src/index.js

export function initDevTools (shell) {
  initStorage().then(() => {
    initApp(shell)
    shell.onReload(() => {
      if (app) {
        app.$el.classList.add('disconnected')
        app.$destroy()
      }
      window.bridge.removeAllListeners()
      initApp(shell)
    })
  })
}

shell is the object literal constructed on shell-chrome/src/devtools.js that contains some methods that are invoked here.

initStorage uses the chrome.storage API as a storage mechanism.

initApp is where the UI magic happens:

// app-frontend/src/index.js

function initApp (shell) {
  shell.connect(bridge => {
    window.bridge = bridge
  // ...

The assignment where the fundamental communication link is established here, window.bridge = bridge. Now it's available on the global context of the Devtools panel.

// app-frontend/src/index.js

    initSharedData({
      bridge,
      Vue,
      persist: true
    }).then(() => {
      if (SharedData.logDetected) {
        bridge.send('log-detected-vue')
      }

      const store = createStore()

      bridge.once('ready', version => {
        store.commit(
          'SHOW_MESSAGE',
          'Ready. Detected Vue ' + version + '.'
        )
        bridge.send('events:toggle-recording', store.state.events.enabled)

        if (isChrome) {
          chrome.runtime.sendMessage('vue-panel-load')
        }
      })
    // ...

A set of shared data between the frontend and the backend is initialized. Once it's done, a Vuex store is created (after all, the devtools panel is a regular Vue.js app!) and a listener for the ready event is added.

You can explore what's this "shared data" consists of by going to shared-utils/src/shared-data.js. As part of the shared data initialization, more messages are transmitted using the bridge:

// shared-utils/src/shared-data.js

bridge.on('shared-data:load', () => {
  // Send all fields
  Object.keys(internalSharedData).forEach(key => {
    sendValue(key, internalSharedData[key])
  })
  bridge.send('shared-data:load-complete')
})

bridge.on('shared-data:init-complete', () => {
  clearInterval(initRetryInterval)
  resolve()
})

bridge.send('shared-data:master-init-waiting')

// In case backend init is executed after frontend
bridge.on('shared-data:slave-init-waiting', () => {
  bridge.send('shared-data:master-init-waiting')
})

Going back to the frontend, here are some additional listeners that are set up:

// app-frontend/src/index.js

// ...
bridge.on('instance-details', details => {
  store.commit('components/RECEIVE_INSTANCE_DETAILS', parse(details))
})

bridge.on('toggle-instance', payload => {
  store.commit('components/TOGGLE_INSTANCE', parse(payload))
})

bridge.on('vuex:init', () => {
  store.commit('vuex/INIT')
})

bridge.on('vuex:mutation', payload => {
  store.dispatch('vuex/receiveMutation', payload)
})

bridge.on('router:changed', payload => {
  store.commit('router/CHANGED', parse(payload))
})

bridge.on('routes:init', payload => {
  store.commit('routes/INIT', parse(payload))
})

bridge.on('routes:changed', payload => {
  store.commit('routes/CHANGED', parse(payload))
})

// ...

Those are just some examples of some hooks that are added so that the backend can instruct devtools about state mutations and router changes.

After all of this, the Vue app is mounted into the div element with id app defined on devtools.html, and that's it! You can keep exploring the different Vue components, Vuex mutations, bridge events and messages sent, etc.

Backend

Now it's the turn of the backend, what's happens on app-backend/src/index.js?

// app-backend/src/index.js

const hook = target.__VUE_DEVTOOLS_GLOBAL_HOOK__

export function initBackend (_bridge) {
  bridge = _bridge

  if (hook.Vue) {
    isLegacy = hook.Vue.version && hook.Vue.version.split('.')[0] === '1'
    connect(hook.Vue)
  } else {
    hook.once('init', connect)
  }

  initRightClick()
}

Great, a reference to the bridge is also stored and a check exists to know if the Vue instance was already detected. In case it hasn't, we wait for it. Otherwise, we proceed to connect to it.

// app-backend/src/index.js

function connect (Vue) {
  initSharedData({
    bridge,
    Vue
  }).then(() => {
    // ...

Here the same shared data is also initialized, like what we saw for the frontend (hence, why it's been given that name). Then:

// app-backend/src/index.js

hook.currentTab = 'components'
bridge.on('switch-tab', tab => {
  hook.currentTab = tab
  if (tab === 'components') {
    flush()
  }
})

// the backend may get injected to the same page multiple times
// if the user closes and reopens the devtools.
// make sure there's only one flush listener.
hook.off('flush')
hook.on('flush', () => {
  if (hook.currentTab === 'components') {
    flush()
  }
})

Some listeners are set up using the bridge and setting the currentTab property of the hook (window.__VUE_DEVTOOLS_GLOBAL_HOOK__) to know when to perform a 'flush' (which is a Vue instance status sync cycle where the component tree structure is sent over to the devtools, to avoid dealing with stale data).

// app-backend/src/index.js

bridge.on('select-instance', id => {
  currentInspectedId = id
  const instance = findInstanceOrVnode(id)
  if (!instance) return
  if (!/:functional:/.test(id)) bindToConsole(instance)
  flush()
  bridge.send('instance-selected')
})

bridge.on('scroll-to-instance', id => {
  const instance = findInstanceOrVnode(id)
  if (instance) {
    scrollIntoView(instance)
    highlight(instance)
  }
})

bridge.on('filter-instances', _filter => {
  filter = _filter.toLowerCase()
  flush()
})

bridge.on('refresh', scan)

Additional listeners are added, that allows the inspected page to respond to DOM instructions sent from the devtools panel. Such as scrolling to a component, scan the page for root Vue instances, or select a component instance.

After the backend initialization ends, a ready event is sent through the bridge:

// app-backend/src/index.js

bridge.send('ready', Vue.version)

That, if you remember from earlier, is picked up on the frontend.

That's it for our backend initialization walkthrough! I'd highly recommend you to keep exploring the multiple aspects of the extension, such as the Vuex initialization and routing initialization logic, and study the different interactions between the frontend and the backend.

Conclusion

And here is where this journey ends!

When I started studying how a production-level developer tools extension was made, I never imagined it would have this level of complexity and moving parts.

I hope that this write-up can be helpful if you're thinking about making the Vue Devtools even better, or if you need to build an awesome new Devtools extension for your use case

I realized that there aren't that many resources available explaining the different aspects of one so perhaps this can help a bit :)

Thank you for reading and have a nice day!

Your CSS as source of truth for color themes

Guillermo Peralta Scura — Sun, 02 Feb 2020 23:53:37 +0000

Supporting multiple color themes for your site can make it more attractive and accessible to users. Every bit of customization you can add to their experience is something that is well appreciated. In this post, I'll show a small technique I used recently to easily manage multiple themes using a single style sheet and CSS custom properties.

For this example, I have multiple color themes defined like this in my CSS style sheet:

.theme-white {
  --base: 0, 0%;
  --lightness: 100%;
  --color: #1098ad;
}

.theme-dark {
  --base: 210, 10%;
  --lightness: 23%;  
  --color: white;
}

.theme-red {
  --base: 0, 100%;
  --lightness: 32%;
  --color: white;
}

/* etc */

I'm using the hue-saturation-lightness model here for colors. In the --base custom property I'm defining the hue and saturation for the primary color of the theme. What's great about it is that once you define your base colors in terms of hue and saturation, you can add variations for accents and highlights just by adjusting the lightness percentage (i.e. the --lightness property). The --color custom property in my particular case is just the secondary color I'm using for text, for my use case the good old hexadecimal notation was fined.

body {
  --bgColor: hsl(var(--base), var(--lightness));
  --darkerBg: hsl(var(--base), calc(var(--lightness) - 10%));
  background-color: var(--bgColor);
  color: var(--color);
}

The --bgColor and --darkerBg properties are just derived from the --base and lightness variables. I find that this technique eases consistency when thinking about themes.

We need to get a list of all the available themes that we can change between. One way to do it is to maintain an array where we manually specify all of our available themes. However, this would mean that once we add or remove themes on our style sheet we would also need to add it in our script.

An alternative I've found useful is to read the defined themes from our style sheet. This way, every time the defined themes change, we won't need to adapt anything from our script and it will just work™:

function getAvailableThemes() {
  const mainStylesheet = Array.from(document.styleSheets).find(
    s => s.title === "main"
  )

  const rules = Array.from(mainStylesheet.rules)

  // All themes are class selectors that start with "theme-"
  return rules
    .filter(
      r =>
        Boolean(r.selectorText) &&
        r.selectorText.includes("theme-")
    )
    // get name without dot prefix on a capture group
    .map(r => r.selectorText.match(/\.([^\s]*)/)[1])
}

const themes = getAvailableThemes()

getAvailableThemes will give us an array like ["theme-white", "theme-dark", "theme-red", "theme-orange", "theme-blue", "theme-purple"].

🌮 Note: It's also possible to use data attributes and retrieve those from JavaScript instead of class selectors if you'd like to.

To toggle between the themes, I use a button with the following handler attached to it:

const themeToggle = document.getElementById("change-theme")

const themes = getAvailableThemes()

themeToggle.addEventListener("click", function toggleTheme() {
  const currentTheme =  Array.from(document.body.classList).find(val => themes.includes(val)) ||
    defaultTheme
  const idx = themes.indexOf(currentTheme)
  const nextIdx = (idx + 1) % themes.length
  document.body.className = themes[nextIdx]
})

We can determine the default theme to use with the help of the prefers-color-scheme CSS media feature:

const mediaQuery = matchMedia("(prefers-color-scheme: dark)")
let defaultTheme = mediaQuery.matches ? "theme-dark" : "theme-white"

mediaQuery.addEventListener("change", val => {
  defaultTheme = mediaQuery.matches ? "theme-dark" : "theme-white"
})

If the user has defined "dark mode" on their operating system settings, we will be using those unless they switch to another one!

The full example ⬇️

I added additional code to store the selection on localStorage so that we can retrieve it on repeated visits. Hopefully, the idea of parsing the content of the style sheet to have a single source of truth is appealing to you!

Comparing React Hooks with Vue Composition API

Guillermo Peralta Scura — Fri, 06 Sep 2019 14:29:00 +0000

Vue recently presented the Composition API RFC, a new API for writing Vue components inspired by React Hooks but with some interesting differences that I will discuss in this post. This RFC started with a previous version called Function-based Component API that received lots of criticism from certain part of the community, based on the fear of Vue starting to be more complicated and less like the simple library that people liked in the first place.

The Vue core team addressed the confusion around the first RFC and this new one presented some interesting adjustments and provided further insights on the motivations behind the proposed changes. If you are interested in giving some feedback to the Vue core team about the new proposal you can participate in the discussion on GitHub.

Note: The Vue Composition API is a work in progress and is subject to future changes. Nothing regarding the Vue Composition API is 100% sure until Vue 3.0 arrives.

React Hooks allow you to "hook into" React functionalities like the component state and side effects handling. Hooks can only be used inside function components and allows us to bring state, side-effects handling and much more to our components without the need to create a class for them. The community fell in love with them immediately since their introduction in 2018.

The adoption strategy prepared by the React core team was to not deprecate Class Components so you could update the React version, start trying Hooks in new components and keep your existing components without any modification.

So, let's get started studying the different aspects of React Hooks and Vue Composition API and remark certain differences that we might find along the way ⏯

React Hooks

Example:

import React, { useState, useEffect } from "react";

const NoteForm = ({ onNoteSent }) => {
  const [currentNote, setCurrentNote] = useState("");
  useEffect(() => {
    console.log(`Current note: ${currentNote}`);
  });
  return (
    <form
      onSubmit={e => {
        onNoteSent(currentNote);
        setCurrentNote("");
        e.preventDefault();
      }}
    >
      <label>
        <span>Note: </span>
        <input
          value={currentNote}
          onChange={e => {
            const val = e.target.value && e.target.value.toUpperCase()[0];
            const validNotes = ["A", "B", "C", "D", "E", "F", "G"];
            setCurrentNote(validNotes.includes(val) ? val : "");
          }}
        />
      </label>
      <button type="submit">Send</button>
    </form>
  );
};

useState and useEffect are some examples of React Hooks. They allow it to add state and run side-effect in function components. There are additional hooks that we will see later and you can even create custom ones. This opens new possibilities for code reusability and extensibility.

Vue Composition API

Example:

<template>
  <form @submit="handleSubmit">
    <label>
      <span>Note:</span>
      <input v-model="currentNote" @input="handleNoteInput">
    </label>
    <button type="submit">Send</button>
  </form>
</template>

<script>
import { ref, watch } from "vue";
export default {
  props: ["divRef"],
  setup(props, context) {
    const currentNote = ref("");
    const handleNoteInput = e => {
      const val = e.target.value && e.target.value.toUpperCase()[0];
      const validNotes = ["A", "B", "C", "D", "E", "F", "G"];
      currentNote.value = validNotes.includes(val) ? val : "";
    };
    const handleSubmit = e => {
      context.emit("note-sent", currentNote.value);
      currentNote.value = "";
      e.preventDefault();
    };

    return {
      currentNote,
      handleNoteInput,
      handleSubmit,
    };
  }
};
</script>

Vue Composition API is centered around a new component option called setup. It provides a new set of functions for adding state, computed properties, watchers and lifecycle hooks to our Vue components.

This new API won't make the original API (now referred to as the "Options-based API") disappear. The current iteration of the proposal allows developers to even combine both components APIs together.

Note: you can try this in Vue 2.x using the @vue/composition-api plugin.

Execution of the code

The setup function of the Vue Composition API is called after the beforeCreate hook (in Vue, a "hook" is a lifecycle method) and before the created hook. This is one of the first differences we can identify between React Hooks and Vue Composition API, React hooks run each time the component renders while the Vue setup function only runs once while creating the component. Because React Hooks can run multiple times, there are certain rules the render function must follow, one of them being:

Don’t call Hooks inside loops, conditions, or nested functions.

Here is a code example straight from React docs that demonstrates this:

function Form() {
  // 1. Use the name state variable
  const [name, setName] = useState('Mary');

  // 2. Use an effect for persisting the form
  if (name !== '') {
    useEffect(function persistForm() {
      localStorage.setItem('formData', name);
    });
  }
  // 3. Use the surname state variable
  const [surname, setSurname] = useState('Poppins');

  // 4. Use an effect for updating the title
  useEffect(function updateTitle() {
    document.title = `${name} ${surname}`;
  });

  // ...
}

React internally keeps track of all the hooks we are using in our component. In this example, we are using four hooks. Notice how the first useEffect invocation is done conditionally, and since on the first render the name state variable will be assigned the default value of 'Mary' the condition will be evaluated to true and React will know that it needs to keep track of all of these four hooks in order. But what happens if on another render name is empty? Well, in that case, React won't know what to return on the second useState hook call 😱. To avoid this and other issues, there is an ESLint plugin that is strongly recommended when working with React Hooks and is included by default with Create React App.

What if we just want to run the effect if name is not empty then? We can simply move it inside the useEffect callback:

useEffect(function persistForm() {
  if (name !== '') {
    localStorage.setItem('formData', name);
  }
});

Going back to Vue, something equivalent to the previous example would be this:

export default {
  setup() {
    // 1. Use the name state variable
    const name = ref("Mary");
    // 2. Use a watcher for persisting the form
    if(name.value !== '') {
      watch(function persistForm() => {
        localStorage.setItem('formData', name.value);
      });
    }
   // 3. Use the surname state variable
   const surname = ref("Poppins");
   // 4. Use a watcher for updating the title
   watch(function updateTitle() {
     document.title = `${name.value} ${surname.value}`;
   });
  }
}

Since the setup method will only run once, we can make use of the different functions that are part of the Composition API (reactive, ref, computed, watch, lifecycle hooks, etc.) as part of loops or conditional statements. However, the if statement will also only run once, so it won't react to changes to name unless we include it inside of the watch callback:

watch(function persistForm() => {
  if(name.value !== '') {
    localStorage.setItem('formData', name.value);
  }
});

Declaring state

useState is the main way to declare state with React Hooks. You can pass the initial value as an argument to the call and if the computation of the initial state is expensive you can express it as a function that will only be executed during the initial render.

const [name, setName] = useState("Mary");
const [age, setAge] = useState(25);
console.log(`${name} is ${age} years old.`);

It returns an array with the state as the first element and a setter function in second place. Usually, you use Array destructuring to grab them.

A handy alternative is using useReducer that accepts a Redux-like reducer and an initial state in its more usual variant. There's also a variant with lazy initialization:

const initialState = {count: 0};

function reducer(state, action) {
  switch (action.type) {
    case 'increment':
      return {count: state.count + 1};
    case 'decrement':
      return {count: state.count - 1};
    default:
      throw new Error();
  }
}
const [state, dispatch] = useReducer(reducer, initialState);

You can then use the dispatch function like dispatch({type: 'increment'});.

Vue works differently due to its reactive nature. You have two main functions to declare state: ref and reactive.

ref returns a reactive object where the inner value it contains is accessed by its value property. You can use ref with primitive values or objects and in the case of objects, they are made deeply reactive.

const name = ref("Mary");
const age = ref(25);
watch(() => {
  console.log(`${name.value} is ${age.value} years old.`);
});

reactive on the other hand can only take an object as its input and returns a reactive proxy of it. Note that the reactivity affects all nested properties.

const state = reactive({
  name: "Mary",
  age: 25,
});
watch(() => {
  console.log(`${state.name} is ${state.age} years old.`);
});

The RFC has a whole section comparing ref and reactive. It ends up with a summary of possible approaches for using them:

Use ref and reactive just like how you'd declare primitive type variables and object variables in normal JavaScript. It is recommended to use a type system with IDE support when using this style.

Use reactive whenever you can, and remember to use toRefs when returning reactive objects from composition functions. This reduces the mental overhead of refs but does not eliminate the need to be familiar with the concept.

Something to keep in mind when using ref is that you need to remember to access the contained value by the value property of the ref (except in templates, where Vue allows you to omit it). Whereas with reactive you will lose reactivity if you destructure the object. So you need to have a reference to the object and access the state properties you defined through it.

The Composition API provides two helper functions for dealing with refs and reactive objects. isRef can be used to conditionally grab the value property if needed (e.g. isRef(myVar) ? myVar.value : myVar) and toRefs converts a reactive object to a plain object where all of its properties are automatically transform to refs. Particularly useful when returning from custom composition functions (and thus allowing destructuring to be used from the caller side and keep reactivity).

function useFeatureX() {
  const state = reactive({
    foo: 1,
    bar: 2
  })

  return toRefs(state)
}

const {foo, bar} = useFeatureX();

How to track dependencies

The useEffect Hook in React allows us to run certain side effect (like making a subscription, data fetching or using Web APIs such as storage) after each render and to optionally run some cleanup before the next execution of the callback or when the component will unmount. By default, all useEffect registered functions will run after each render but we can define the actual state and props dependencies so that React skips the execution of a certain useEffect hook if the relevant dependencies haven't changed (e.g. a render was made because of another piece of state update). Going back to our previous Form example we can pass an array of dependencies as the second argument of the useEffect hook:

function Form() {
  const [name, setName] = useState('Mary');
  const [surname, setSurname] = useState('Poppins');
  useEffect(function persistForm() {
      localStorage.setItem('formData', name);
  }, [name]);

  // ...
}

This way, only when name changes we will update the localStorage. A common source of bugs with React Hooks is forgetting to exhaustively declare all of our dependencies in the dependencies array. You can end up with your useEffect callback not being updated with the latest dependencies and referring instead to stale values from previous renders. Fortunately, the eslint-plugin-react-hooks includes a lint rule that warns about missing dependencies.

useCallback and useMemo also use an array of dependencies argument to decide if they should return the same memoized version of the callback or value respectively than the last execution or not.

In the case of Vue Composition API, we can use the watch function to perform side effects in response to props or state changes. Thanks to the reactivity system of Vue the dependencies will be automatically tracked and the registered function will be called reactively when the dependencies change. Going back to our example:

export default {
  setup() {
    const name = ref("Mary");
    const lastName = ref("Poppins");
    watch(function persistForm() => {
      localStorage.setItem('formData', name.value);
    });
  }
}

After the first time our watcher runs, name will be tracked as a dependency and when its value changes at a later time, the watcher will run again.

Access to the lifecycle of the component

Hooks represent a complete switch of the mental model when dealing with lifecycle, side effects and state management of your React component. Ryan Florence, an active member of the React community, expressed that there is a mental shift to be made from class components into hooks, and as the React docs point out:

If you’re familiar with React class lifecycle methods, you can think of useEffect Hook as componentDidMount, componentDidUpdate, and componentWillUnmount combined.

It is possible, however, to control when useEffect will run and bringing us closer to the mental model of running side effects in lifecycles:

useEffect(() => {
  console.log("This will only run after initial render.");
  return () => { console.log("This will only run when component will unmount."); };
}, []);

But once again, it's more idiomatic when using React Hooks to stop thinking in terms of lifecycle methods but to think about what state our effects depend on. By the way, Rich Harris, the creator of Svelte published some insightful slides he presented at an NYC React meetup where he explores the compromises React is making to enable new features in the future (e.g. concurrent mode) and how Svelte differs from that. It will help you understand the shift from thinking in components with lifecycle where side effects happen to side effects being part of the render itself. Sebastian Markbåge from the React core team, further expands here on the direction React is taking and compromises with reactivity systems like Svelte or Vue.

Vue Component API in the other hand, still gives us access to lifecycle hooks (the equivalent name that lifecycle methods get in the Vue world) with onMounted, onUpdated and onBeforeUnmount, etc:

setup() {
  onMounted(() => {
    console.log(`This will only run after initial render.`); 
  });
  onBeforeUnmount(() => {
    console.log(`This will only run when component will unmount.`);
  });
}

So in the case of Vue the mental model shift is rather one of stop thinking of organizing the code by which component options (data, computed, watch, methods, lifecycle hooks, etc.) they belong to, towards one where you can have different functions each dealing with a specific feature. The RFC includes a thorough example and comparison of organizing by options vs. organizing by logical concerns. React Hooks also have this benefit and is something that was also well received by the community from the ground up.

Custom code

One aspect that the React Team wanted to focus with Hooks is to provide developers with a nicer way of writing reusable code than previous alternatives adopted by the community, like Higher-Order Components or Render Props. Custom Hooks are the answer they came up with.

Custom Hooks are just regular JavaScript functions that make use of React Hooks inside of it. One convention they follow is that their name should start with use so that people can tell at a glance that it is meant to be used as a hook.

export function useDebugState(label, initialValue) {
  const [value, setValue] = useState(initialValue);
  useEffect(() => {
    console.log(`${label}: `, value);
  }, [label, value]);
  return [value, setValue];
}

This tiny example Custom Hook can be used as a replacement of useState while logging to the console when the value changes:

const [name, setName] = useDebugState("Name", "Mary");

In Vue, Composition Functions are the equivalent of Hooks with the same set of logic extraction and reusability goals. As a matter of fact, we can have a similar useDebugState composition function in Vue:

export function useDebugState(label, initialValue) {
  const state = ref(initialValue);
  watch(() => {
    console.log(`${label}: `, state.value);
  });
  return state;
}

// elsewhere:
const name = useDebugState("Name", "Mary");

Note: By convention composition functions also use use as a prefix like React Hooks to make it clear it's a composition function and that it belongs in setup

Refs

Both React useRef and Vue ref allow you to reference a child component (in the case of React a Class Component or component wrapped with React.forwardRef) or DOM element that you attach it to.

React:

const MyComponent = () => {
  const divRef = useRef(null);
  useEffect(() => {
    console.log("div: ", divRef.current)
  }, [divRef]);

  return (
    <div ref={divRef}>
      <p>My div</p>
    </div>
  )
}

Vue:

export default {
  setup() {
    const divRef = ref(null);
    onMounted(() => {
      console.log("div: ", divRef.value);
    });

    return () => (
      <div ref={divRef}>
        <p>My div</p>
      </div>
    )
  }
}

Note that in the case of Vue, allocating template refs with JSX on the render function returned by setup() is not supported on the @vue/composition-api Vue 2.x plugin, but the above syntax will be valid in Vue 3.0 according to the current RFC.

The useRef React Hook is not only useful for getting access to DOM elements though. You can use it for any kind of mutable value that you want to keep between renders but aren't part of your state (and thus won't trigger re-renders when they are mutated). You can think about them as "instance variables" that you would have in a Class Component. Here is an example:

const timerRef = useRef(null);
useEffect(() => {
  timerRef.current = setInterval(() => {
    setSecondsPassed(prevSecond => prevSecond + 1);
  }, 1000);
  return () => {
    clearInterval(timerRef.current);
  };
}, []);

return (
  <button
    onClick={() => {
      clearInterval(timerRef.current);
    }}
  >
    Stop timer
  </button>
)

And in the Vue Composition API, as we saw in almost all of our examples earlier in this post, ref can be used to define reactive state. Template refs and reactive refs are unified when using the Composition API.

Additional functions

Since React Hooks run on each render there's no need to an equivalent to the computed function from Vue. You are free to declare a variable that contains a value based on state or props and it will point to the latest value on each render:

const [name, setName] = useState("Mary");
const [age, setAge] = useState(25);
const description = `${name} is ${age} years old`;

In the case of Vue, the setup function only runs one. Hence the need to define computed properties, that should observe changes to certain state and update accordingly (but only when one of their dependencies change):

const name = ref("Mary");
const age = ref(25);
const description = computed(() => `${name.value} is ${age.value} years old`);

As usual, remember that refs are containers and the value is accessed through the value property ;)

But what happens if calculating a value is expensive? you wouldn't want to compute it every time your component renders. React includes the useMemo hook for that:

function fibNaive(n) {
  if (n <= 1) return n;
  return fibNaive(n - 1) + fibNaive(n - 2);
}
const Fibonacci = () => {
  const [nth, setNth] = useState(1);
  const nthFibonacci = useMemo(() => fibNaive(nth), [nth]);
  return (
    <section>
      <label>
        Number:
        <input
          type="number"
          value={nth}
          onChange={e => setNth(e.target.value)}
        />
      </label>
      <p>nth Fibonacci number: {nthFibonacci}</p>
    </section>
  );
};

useMemo also expects a dependencies array to know when it should compute a new value. React advice you to use useMemo as a performance optimization and not as a guarantee that the value will remain memoized until a change in any dependency occurs.

As a side note: Kent C. Dodds has a really nice article explaining many situations where useMemo and useCallback aren't necessary.

Vue's computed perform automatic dependency tracking so it doesn't need a dependencies array.

useCallback is similar to useMemo but is used to memoize callback functions. As a matter of fact useCallback(fn, deps) is equivalent to useMemo(() => fn, deps). The ideal use case of it is when we need to maintain referential equality between renders, e.g. we are passing the callback to an optimized child component that was defined with React.memo and we want to avoid it to re-render unnecessarily. Due to the nature of the Vue Composition API, there is no equivalent to useCallback. Any callback in the setup function will only be defined once.

Context and provide/inject

React has the useContext hook as a new way to read the current value for the specified context. The value to return is determined, as usual, as the value prop of the closest <MyContext.Provider> component in the ancestors tree. It's equivalent to static contextType = MyContext in a class or the <MyContext.Consumer> component.

// context object
const ThemeContext = React.createContext('light');

// provider
<ThemeContext.Provider value="dark">

// consumer
const theme = useContext(ThemeContext);

Vue has a similar API called provide/inject. It exists in Vue 2.x as components options but a pair of provide and inject functions are added as part of the Composition API to be used inside a setup function:

// key to provide
const ThemeSymbol = Symbol();

// provider
provide(ThemeSymbol, ref("dark"));

// consumer
const value = inject(ThemeSymbol);

Note that if you want to retain reactivity you must explicitly provide a ref/reactive as the value.

Exposing values to render context

In the case of React since all of your Hooks code is on the component definition and you return the React elements that you would like to render in the same function, you have full access to any value in the scope as you would in any JavaScript code:

const Fibonacci = () => {
  const [nth, setNth] = useState(1);
  const nthFibonacci = useMemo(() => fibNaive(nth), [nth]);
  return (
    <section>
      <label>
        Number:
        <input
          type="number"
          value={nth}
          onChange={e => setNth(e.target.value)}
        />
      </label>
      <p>nth Fibonacci number: {nthFibonacci}</p>
    </section>
  );
};

In the case of Vue if you have your template defined in the template or render options or if you are using Single File Components you need to return an object from the setup function containing every value that you want to expose to the template. Your return statement can potentially end up being verbose since you could potentially want to expose many values and this is a point to be aware of as mentioned in the RFC:

<template>
  <section>
    <label>
      Number:
      <input
        type="number"
        v-model="nth"
      />
    </label>
    <p>nth Fibonacci number: {{nthFibonacci}}</p>
  </section>
</template>
<script>
export default {
  setup() {
    const nth = ref(1);
    const nthFibonacci = computed(() => fibNaive(nth.value));
    return { nth, nthFibonacci };
  }
};
</script>
}

One way to achieve the same behavior present in React is returning a render function from the setup option itself:

export default {
  setup() {
    const nth = ref(1);
    const nthFibonacci = computed(() => fibNaive(nth.value));
    return () => (
      <section>
        <label>
          Number:
          <input
            type="number"
            vModel={nth}
          />
        </label>
        <p>nth Fibonacci number: {nthFibonacci}</p>
      </section>
    );
  }
};

However, templates are way more popular in Vue so exposing an object with values is certainly going to be something that you will encounter a lot with Vue Composition API.

Conclusion

These are exciting times for both frameworks. Since the introduction of React Hooks in 2018, the community has built amazing things on top of them and the extensibility of Custom Hooks allowed for many open source contributions that can be easily added to our projects. Vue is taking inspiration from React Hooks and adapting them in a way that feels nice for the framework and serves as an example of how all of these different technologies can embrace change and share ideas and solutions. I can't wait for Vue 3 to arrive and see the possibilities that it unlocks.

Thank you for reading and keep building awesome stuff 🚀

rm -rf overdose

Guillermo Peralta Scura — Tue, 20 Aug 2019 01:43:34 +0000

The rm command on Unix and the -rf flags are like bread and butter. At least for me, it's hard to imagine running the rm command without those flags. As a matter of fact, it became like an instinct and almost as if the command was always rm -rf.

If you know what you are doing, you can be safe running the full command like that all the time, but I should know myself better and recognize that it is going to be way better for me to think twice before hitting the Enter key. Let me tell you about what happened to me a few weeks ago when I lost a whole day of progress on a project running on a Google Compute Cloud instance for which I was paying 1.5 USD an hour. Essentially, running an rm -rf command without giving it second thoughts made me lose around 15 USD. Which is not a lot of money compared to what happened to Pixar for running this exact same command a few years ago.

An introduction to `rm`

The way I usually used rm -rf is extremely simple:

rm -rf directory_to_delete/

I just specified the path to the directory I wanted to remove recursively and I'm done! Great 💯💯💯. To gain more context let's break the command step by step:

rm: As its own manual (for the BSD version) says:

The rm utility attempts to remove the non-directory type files specified on the command line. If the permissions of the file do not permit writing, and the standard input device is a terminal, the user is prompted (on the standard error output) for confirmation.

So there you go, the basic command to remove files in Unix.

-r: Recursively remove directories. Remember how rm attempts to remove non-directory type files? Well, with this flag it will remove directories (and their contents).
-f: Never prompt for confirmation, even if the file that it's attempting to delete do not permit writing.

Don't try this at `/home`

Let's set up a test environment to show you the silly mistake I made the other day. I will spin up an Ubuntu container using Docker, but if you like you could use any Virtual Machine, Cloud Instance, a disk partition of your old laptop with a Linux distro you use for experiments, anything you like. Just avoid playing with rm on your main machine, especially near your important files, please 🙏.

I'll start by running an interactive Ubuntu session with docker and creating a basic file structure:

$ docker run -it --rm ubuntu
root@ubuntu:/# cd home/
root@ubuntu:/home# mkdir my-files
root@ubuntu:/home# cd my-files
root@ubuntu:/home/my-files# mkdir pictures
root@ubuntu:/home/my-files# mkdir music
root@ubuntu:/home/my-files# mkdir code
root@ubuntu:/home/my-files# mkdir docs
root@ubuntu:/home/my-files# cd docs
root@ubuntu:/home/my-files/docs# mkdir pdfs
root@ubuntu:/home/my-files/docs# mkdir business
root@ubuntu:/home/my-files/docs# mkdir tmp

OK, so far we are just creating a bunch of directories. The structure is as follows:

|- my-files
|   |- pictures
|   |- music
|   |- code
|   |- docs
|   |   |- pdfs
|   |   |- business
|   |   |- tmp

Now imagine that we would like to get rid of the tmp directory under the /docs directory (funnily enough, this was actually what I was trying to do!), we can achieve this by doing:

rm -rf /home/my-files/docs/tmp

We could also do it using relative paths, so for instance, if our current working directory is /home/my-files/docs we could do instead rm -rf tmp/.

Now, here comes what I did wrong the time I was trying to delete my tmp directory:

rm -rf /home/my-files/docs/tmp\

Can you spot the difference with the original command? It's just a character! Right before I pressed the Enter key I accidentally pressed the key right above it in my Macbook keyboard, the backslash character \. What's so special about the backslash character on a bash command? It escapes the next character to avoid it to be interpreted by the shell. So in my case when I pressed the Enter key my rm command didn't run yet.

Hmm. That could be potentially good, right? Actually, yes! That little mistake can give you one more chance to review that the line you've written is correct and if you spot any typo, disregard it before doing any damage 🙂. The problem is that, if you happen to not be paying enough attention (which was definitely my case), you could end up not realizing that your rm command didn't run yet and move to the next command as if everything went smoothly. And what happens if the next command you run is a cd (change directory)? 🤔 let's go ahead and try it:

root@ubuntu:/# rm -rf /home/my-files/docs/tmp\
> cd /home/my-files

Run it and... all of our folders are gone 😱

Wh...what happened?

Remember how we said that the \ made the shell ignore the next character? Well... That means that our previous command is equivalent to this:

rm -rf /home/my-files/docs/tmpcd /home/my-files

I didn't know that rm could be used to remove multiple directories at the same time, but it turns out it is possible. So here we are trying to delete two directories: /home/my-files/docs/tmpcd (which doesn't exist since the cd suffix shouldn't be there) and... /home/my-files 😱😱😱😱. So, even if I originally was extremely confident about running rm -rf /home/my-files/docs/tmp since of course I wanted to remove that directory and thus the -f flag wouldn't be a problem, I wasn't aware that the shell didn't run the command yet, so the cd /home/my-files of the next line wasn't interpreted as a change directory command.

What can I do to prevent this?

First of all, have frequent backups and test recover from them from time to time. If possible, make sure to have more than one physical copy of your files and also store what you can in a secure cloud. Mistakes, accidents, and disk issues happen and you never know when.

If your platform is running the GNU version of rm you can use the -I (uppercase i) flag instead of -f and you will receive a prompt before the actual execution of the destructive action (unless you are trying to remove less than 4 files and not recursively). It's similar to -i (lowercase i) but far less annoying and is perfect for the situation described in this post.

Let's see it in action:

root@ubuntu:/# rm -rI /home/my-files/docs/tmp\
> cd /home/my-files
rm: remove 2 arguments recursively?

If we were using the -I flag, we would be surprised to see the rm confirmation prompt after what we thought was a cd command. It gives us much higher chances of catching this kind of errors and in general, it gives us one more chance of thinking about what we are about to do.

BUT... it's not available by default on macOS ☹️. The thing is that the rm implementation found on macOS is the BSD one, that doesn't support the -I flag. If you use homebrew you can install rm (and many other GNU coreutils) with brew install coreutils and the GNU rm version will be available as grm. You can then alias it to rm if you'd like.

If you would rather keep the native implementation of rm I would suggest using the Z shell as a shell with the oh-my-zsh framework installed. There, you can find many amazing themes to customize your shell with different backgrounds, icons and what's important for avoiding the mistake that concerns us the most in this post: the prompt.

I personally use the agnoster theme, and it gives you a really distinctive prompt that makes it far easier to me to identify when I'm continuing the same command of the previous line or if I'm actually in a new line.

In the screenshot, there is a main prompt filled with blue with the current working directory and an undecorated prompt with a > sign indicating that we are continuing the line before.

As a third option, you could try to use external CLI tools that instead of removing the files, move them to the trash bin instead. One of the most popular is trash-cli that is available for macOS, Linux, and Windows. The author of that tool, Sindre Sorhus, also wrote a guide with other tricks to avoid accidents with rm.

I hope this post gives you more options for the next time you are tempted to use rm -rf and please remember to be careful out there 🔥!

DEV Community: Guillermo Peralta Scura

How a DevTools Extension is Made

Table of contents

Vue Devtools Overview

Manifest file

Types of scripts

Vue DevTools architecture

Vue detector

Background script

Hook

DevTools page

Backend and Frontend

Bridge

Proxy

Frontend

Backend

Conclusion

Your CSS as source of truth for color themes

Comparing React Hooks with Vue Composition API

React Hooks

Vue Composition API

Execution of the code

Declaring state

How to track dependencies

Access to the lifecycle of the component

Custom code

Refs

Additional functions

Context and provide/inject

Exposing values to render context

Conclusion

rm -rf overdose

An introduction to rm

Don't try this at /home

Wh...what happened?

What can I do to prevent this?

An introduction to `rm`

Don't try this at `/home`