06/08/2019 Writing Your First Browser Extension Tutorial - Part 1 - DEV Community 👩💻👨💻

2
search

Writing Your First Browser

Extension Tutorial - Part 1
Yechiel Kalmenson Aug 5 ‧8 min read
#javascript #beginners #browsers #webdev

This tutorial is based on a workshop I gave at the Codeland

conference in NYC in 2019.

For the purpose of this tutorial we will use Firefox, though most
concepts carry over to other browsers as well.

What Is A Browser Extension?

In it's most basic form, a browser extension is simply a JavaScript file
that runs code in your browser to modify/improve your browsing
experience.

70 19 120

https://dev.to/yechielk/writing-your-first-browser-extension-part-1-d5e 1/16
06/08/2019 Writing Your First Browser Extension Tutorial - Part 1 - DEV Community 👩💻👨💻

Were you ever looking at a web page and wished you could change 2
search

something about it? Maybe there were too many ads? Perhaps you
didn't like the font? Could be the color theme was too bright?

Whatever the case is if the change you wish to see is something that
can happen in the browser (i.e., it's a change on the front-end that
doesn't involve any of the back-end) then chances are you can write a
browser extension to do it.

Some changes are easier to implement than others, but as a general

rule, if the change is something the web developer could have
implemented using JavaScript, then you can probably write an
extension to do it yourself!

Structure Of A Browser Extensions

Browser Extensions come in a wide range of size and complexity, but
at their heart, they all share the same basic template.

Here is a simple extension:

sample-extension
└───images
│ └───icon-48.png
│ └───icon-96.png
│ └───image1.jpg
│ └───image2.jpg
│
└───manifest.json
└───sample-extnsion.js

70 19 120

https://dev.to/yechielk/writing-your-first-browser-extension-part-1-d5e 2/16
06/08/2019 Writing Your First Browser Extension Tutorial - Part 1 - DEV Community 👩💻👨💻

Thesearch
extension lives in a folder which I called sample-extension . 2

At the heart of the extension is a file called manifest.json . The

manifest is a JSON file that contains the information your browser
needs in order to know when and how to run your extension. We will
take a closer look at the manifest in a moment.

The actual code for your extension lives in a JavaScript file that I
called sample-extension.js .

As your extension starts growing in complexity, you may want to split

your code out into multiple files in sub-directories, but this is for a
fairly simple extension.

Finally, any images you wish to include, including the icons you will
use to promote your extension in the browser add-on store, can go into
a subfolder that I called images .

The Manifest.
The manifest is at the heart of your extension; it's how your browser
knows which code to run, and when and how to run it.

Let's take a look at a sample manifest for a simple extension:

{
"manifest_version": 2,
"name": "<EXTENSION-NAME>",
"version": "1.0",
70 19 120

https://dev.to/yechielk/writing-your-first-browser-extension-part-1-d5e 3/16
06/08/2019 Writing Your First Browser Extension Tutorial - Part 1 - DEV Community 👩💻👨💻

"description": "<A USEFUL DESCRIPTION>", 2

search

"icons": {
"48": "<URL TO AN ICON>",
"96": "<URL TO AN ICON>"
},

"content_scripts": [
{
"matches": ["<URL MATCHER>"],
"js": ["<RELATIVE PATH TO A JS FILE>"]
}
]
}

That looks like a lot! Let's take a look at the relevant parts:

"name" : is the name of your extension (used to list it in your

browser's add-on store).
"version" : is the version of your extension. As you make
improvements, you will bump this number so people can be sure
they are running the latest version.
"description" : is a human-readable description of what your
browser does, so people who come across it in the add-on store
know what it is.
"icons" : this is where you supply icons that will display
together with your extension in the add-on store (the two sizes
are for the add-on store description and a thumbnail).
"content_scripts" : this is the main part of the manifest; it
tells your browser which code to run and when to run it. It
contains two keys:
70 19 120

https://dev.to/yechielk/writing-your-first-browser-extension-part-1-d5e 4/16
06/08/2019 Writing Your First Browser Extension Tutorial - Part 1 - DEV Community 👩💻👨💻

search "matches" : takes an array of URLs in which your 2

extension should run.

"js" : takes an array of paths to JavaScript files that
your browser should run when it encounters one of the
URLs in "matches" .

There are other keys you can provide that represent different functions
your extension can do. They are listed here.

So now that we have all of the information we need let's get coding!

Let's Get Started!

Hello DEV!

We will start with the simplest extension I could think of, the "Hello
World" of browser extensions so to speak.

Let's start by creating a directory for our extension. In your

terminal type:

mkdir first-extension
cd first-extension

Inside the first-extension directory let's create our

manifest:

touch manifest.json
70 19 120

https://dev.to/yechielk/writing-your-first-browser-extension-part-1-d5e 5/16
06/08/2019 Writing Your First Browser Extension Tutorial - Part 1 - DEV Community 👩💻👨💻

Now,
search using your favorite editor open up the manifest we just 2

created and paste in the following JSON (I'm usually not a fan of
copy/pasting code from tutorials; I think by taking the time to
type things out you build muscle memory and retain information
better, but I won't make you type out all this JSON yourself):

{
"manifest_version": 2,
"name": "first-extension",
"version": "1.0",

"description": "Our very first browser extension!",

"content_scripts": [
{
"matches": ["*://*.dev.to/*"],
"js": ["first-extension.js"]
}
]
}

The parts we changed from the generic manifest we saw earlier

are:
We added a name and a description.
We got rid of the icons key being that we aren't using
icons in our extension.
We gave the matches key an array containing the URL
to dev.to, the website our extension will run on.
The three asterisks are wildcards that will match
for: 1) any protocol (HTTP and HTTPS), 2) any
subdomain of dev.to (e.g. shop.dev.to), and 3) any
page on
70 dev.to (e.g.
19 https://dev.to/yechielk).
120

https://dev.to/yechielk/writing-your-first-browser-extension-part-1-d5e 6/16
06/08/2019 Writing Your First Browser Extension Tutorial - Part 1 - DEV Community 👩💻👨💻

search We gave the js key an array containing the filename 2

first-extension.js which is the file where we will

write the code for our extension.
So in other words, what our manifest says is that when our
browser visits any URL that matches the pattern we provided
(i.e. any page on dev.to) it should run the code in the file
first-extension.js .

At this point it might be a good idea to make sure we actually

have a first-extension.js file. Let's go back to our
terminal:

touch first-extension.js

Perfect! We now (technically) have a working browser

extension.
The next thing we need to do is tell our browser to load our
extension.
In Firefox go to the following page: "about:debugging".

Near the top right corner click on the button that says "Load
Temporary Add On..."
70 19 120

https://dev.to/yechielk/writing-your-first-browser-extension-part-1-d5e 7/16
06/08/2019 Writing Your First Browser Extension Tutorial - Part 1 - DEV Community 👩💻👨💻

Navigate
search to the folder we created for our extension and select 2

the manifst.json file.

You should see our first-extension extension show up
under "Temporary Extensions".

Our extension is now loaded and ready to roll. If we navigate to

dev.to our browser will execute the code in first-
extension.js . Of course we can't tell because there is no code
in first-extension.js so let's fix that.
Most people would put a console.log() and see if they can
see something in their console, but I think alert s are way
cooler so let's do that!
Open up first-extension.js and add the following:

alert("Hello DEV!")

If you refresh dev.to nothing will happen; our browser is still

running the old code we loaded. Every time we make changes to
our code we need to reload our extension.
70 19 120

https://dev.to/yechielk/writing-your-first-browser-extension-part-1-d5e 8/16
06/08/2019 Writing Your First Browser Extension Tutorial - Part 1 - DEV Community 👩💻👨💻

Go back
search to "about:debugging" and look at the temporary 2

extension we loaded. Near the bottom there should be a small

link that says "Reload". Click on it and then refresh dev.to. You
should see our alert pop up!

Congratulations! You now have a working browser extension!

Troubleshooting

If you have trouble getting the alert to pop up, or even getting the
extension to load double check that your manifest is valid JSON with
no syntax errors (missing commas, open brackets, etc.). Make sure
there are no typos in the "js" filename and that the name in the
manifest matches the actual name of the file.

One issue encountered by a few participants in the workshop was that

they forgot to remove the "icons" key from the manifest. If it's there
and the value is not a valid file path the browser will freak out trying
to load the icons.
70 19 120

https://dev.to/yechielk/writing-your-first-browser-extension-part-1-d5e 9/16
06/08/2019 Writing Your First Browser Extension Tutorial - Part 1 - DEV Community 👩💻👨💻

Get Off Twitter!

search
2

That was cool! But let's write an extension that actually does
something useful. How about an extension that will ping you
after being on Twitter for 10 minutes and remind you to take a
mental health break.
Let's head back to our manifest and change the value of our
"matches" key from the DEV website to Twitter:

"content_scripts": [
{
- "matches": ["*://*.dev.to/*"],
+ "matches": ["*://*.twitter.com/*"],
"js": ["first-extension.js"]
}
]

If we reload our extension in "about:debugging" and head to

Twitter.com we should see our alert pop up there. This is just to
make sure everything is still working.
Let's modify our first-extension.js to add the
functionality we want.
We can use JavaScript's built in setInterval function that
runs a callback function at set intervals.
The setInterval function takes two arguments. A function to
run, and an interval in which to run it, given in milliseconds.
Let's first set our interval to 10 minutes. We could do something
like:

70 19 120
const interval = 600000 // 600,000 milliseconds = 10 minutes
https://dev.to/yechielk/writing-your-first-browser-extension-part-1-d5e 10/16
06/08/2019 Writing Your First Browser Extension Tutorial - Part 1 - DEV Community 👩💻👨💻

2
search

But I find it more readable to break up the interval into its constituent
parts. This will make it easier to understand when you come back to
the code in a few weeks:

const interval = 1000 * 60 * 10 // 1000ms = 1 second * 60 = 1 minute * 1

Next let's write the function that will run every ten minutes. We
want a function that pops up an alert to tell us to get off Twitter.
It should look something like this:

function reminder() {
alert("Get off Twitter!")
}

Now we have all the parts we need. The only thing left is to put
it all together and call our setInterval function:

setInterval(reminder, interval)

We now have a browser extension that will do what we want.

The only problem is that in order to test it we will have to wait
10 minutes, and:

70 19 120

https://dev.to/yechielk/writing-your-first-browser-extension-part-1-d5e 11/16
06/08/2019 Writing Your First Browser Extension Tutorial - Part 1 - DEV Community 👩💻👨💻

2
search

so for now let's change our interval to 10 seconds instead of 10

minutes:

- const interval = 1000 * 60 * 10

+ const interval = 1000 * 10

Let's reload our extension in "about:debugging" and head over

to Twitter.com.
If we wait 10 seconds we should see our alert pop up!
If we dismiss the alert we should see it popping up again after
another 10 seconds etc.
We can go back to first-extension.js and switch the
interval back to 10 minutes:

- const interval = 1000 * 10

+ const interval = 1000 * 60* 10

Congratulations, we're done!

What's Next? 70 19 120

https://dev.to/yechielk/writing-your-first-browser-extension-part-1-d5e 12/16
06/08/2019 Writing Your First Browser Extension Tutorial - Part 1 - DEV Community 👩💻👨💻

So search
now we have an actual, useful browser extension, but chances are 2

that when you think of interesting browser extensions the ones that
come to mind are extensions that actually change things on web pages.

Browser extensions accomplish that by using DOM Manipulation (a

class of JavaScript functions that allow it to interact with, and
manipulate, web pages).

In part two of this series we will build a fun extension that does just
that while attempting to fix the broken hiring system in tech and, as a
bonus, includes cats!

Yechiel Kalmenson ✓ FOLLOWING

I'm a Software Engineer and a teacher. There's no feeling quite like the one you get when
you watch someone's eyes light up learning something they didn't know. What can I teach
you today?
@yechielk yechielk achasveachas yechiel.me

Add to the discussion

PREVIEW SUBMIT

Aug 5
Sandro Volery

This is honestly great, browser extensions are about the only thing i havent looked into yet to
work on for a side project, simply because i didn't have any ideas :D this article kind of got me
interested so now i got to find ideas.. does anyone have a cool idea?

2 REPLY
70 19 120
 
https://dev.to/yechielk/writing-your-first-browser-extension-part-1-d5e 13/16
06/08/2019 Writing Your First Browser Extension Tutorial - Part 1 - DEV Community 👩💻👨💻

25
search Aug
Yechiel Kalmenson

I'm glad I got you interested 🤗

Let me know what you end up making!

1 REPLY

Aug 5
KristijanFištrek

Exactly what I needed! 🖤

2 REPLY

 
Aug 5
Yechiel Kalmenson

Glad you found it useful!

2 REPLY

 
Aug 5
KristijanFištrek

Looking forward to Part 2!

2 REPLY

Aug 5
Muhammad

Great, I am going to follow that and think of something... Cheers Man.

2 REPLY

 
Aug 5
Yechiel Kalmenson

Awesome! Let us know what you make!

2 REPLY
70 19 120
 

https://dev.to/yechielk/writing-your-first-browser-extension-part-1-d5e 14/16
06/08/2019 Writing Your First Browser Extension Tutorial - Part 1 - DEV Community 👩💻👨💻

25
Aug
search
Eugen Cazacu

great article! thanks for clarifying the concept of browser extensions and how easy they are to
write

2 REPLY

 
Aug 5
Yechiel Kalmenson

Glad you liked it!

1 REPLY

code of conduct - report abuse

Classic DEV Post from Oct 16 '18

Who is hiring? (As of October 2018)

dev.to staff

Members of the dev.to community sharing open job opportunities at their

companies.
50 21

Another Post You Might Like

How to make Dynamic Text Overlays on Images

Sarthak Sharma

A cool experiment in canvas you should not miss out 😬

165 26

70 19 120
Another Post You Might Like
https://dev.to/yechielk/writing-your-first-browser-extension-part-1-d5e 15/16
06/08/2019 Writing Your First Browser Extension Tutorial - Part 1 - DEV Community 👩💻👨💻

2
search
A Developers Guide to Getting Fit
Eric Bishard

How I lost 30 lbs and kept if off while juggling a career as an engineer and
developer advocate.
371 47

Learning JavaScript Testing Quickly with Mocha, Chai, and Sinon

(and a Lot of Gaps)
Isa Levine - Aug 4

Get current time in 12 hours AM PM format in React Native Android

iOS
skptricks - Aug 4

Sideprojects Motivations and Goals

Alexandru Bucur - Aug 4

Is this normal? I am kinda freaked out!

Muhammad - Aug 4

Home About Privacy Policy Terms of Use Contact Code of Conduct

DEV Community copyright 2016 - 2019  🔥

70 19 120

https://dev.to/yechielk/writing-your-first-browser-extension-part-1-d5e 16/16