There are three practical ways to add JavaScript to a web page. You can use an inline <script> tag, you can use an external <script src="app.js"> tag, or you can use an inline event handler attribute on an element. These three choices are not equal. The external file is what you will use on every real project, and the defer and async attributes decide when that file runs.
The previous lesson in this module covered "What Is JavaScript and Where Does It Actually Run", and the next lesson in this module is about "Your First Script and console.log".
What are the three ways to add JavaScript to a page?
Any JavaScript in a page arrives through one of these doors, and all three of them end up doing the same thing. They give the browser a piece of source text to compile and to run.
| Approach | Written where | Use it when |
|---|---|---|
Inline <script> tag | Inside the HTML document | Small experiments, and a page that will never be reused |
External <script src> tag | A separate .js file | Almost always, for real sites, shared behaviour, and caching |
| Inline event handler | An attribute on an element | Never in new code, although you will meet it in old code |
There is a fourth and newer door, which is ES modules loaded with <script type="module">. Modules get their own scope, they run in strict mode, and they support import and export. They are also deferred by default. They have their own chapter later in this tutorial. For now the important thing is that the classic <script> tag still does the work for most pages.
What does an inline script tag look like?
Put the code directly between the <script> and </script> tags. There is no src attribute, so the browser uses whatever text sits between them.
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8" />
<title>Inline script</title>
</head>
<body>
<h1>Inline script</h1>
<button id="go">Count</button>
<p id="output">0</p>
<script>
let count = 0;
const output = document.getElementById("output");
document.getElementById("go").addEventListener("click", function () {
count += 1;
output.textContent = String(count);
});
</script>
</body>
</html>
That page works, but it has three problems that grow quickly. The code cannot be cached, so every visitor downloads it again. It cannot be reused on a second page. And it cannot be tested, version-controlled, or edited with syntax highlighting. Inline scripts are fine for a five-line experiment, and they are a liability in production.
Why an external file is the right default
Move the same JavaScript into its own file and point a tag at it. The rule of thumb is <script src="app.js" defer></script> in the <head>.
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8" />
<title>External script</title>
<link rel="stylesheet" href="styles.css" />
<script src="app.js" defer></script>
</head>
<body>
<h1>External script</h1>
<button id="go">Count</button>
<p id="output">0</p>
</body>
</html>
And app.js holds the behaviour.
let count = 0;
const output = document.getElementById("output");
document.getElementById("go").addEventListener("click", function () {
count += 1;
output.textContent = String(count);
});
The browser now downloads app.js once and reuses the cached copy on every later page view, so a change to the behaviour ships without sending the markup again. defer also means that the script waits for the HTML to be parsed before it runs, and that is exactly what the code above needs, because it looks up #output at the top level.
What do defer and async actually change?
Both attributes download your script in the background instead of blocking the HTML parser. They differ in one thing only, and that thing is when the code runs.
<!-- defer: download in parallel, run after parsing, keep document order -->
<script src="analytics.js" defer></script>
<script src="app.js" defer></script>
<!-- async: download in parallel, run the instant it arrives, any order -->
<script src="widget.js" async></script>
Without either attribute, a classic script blocks the parser. The browser stops reading HTML, it fetches the script, it runs the script to completion, and only then does it carry on. Two classic scripts therefore run strictly one after the other, in the order that they appear.
// Classic scripts run one at a time, in document order.
const order = [];
function runClassicScript(name) {
order.push(name + " ran");
}
runClassicScript("analytics.js");
runClassicScript("app.js");
console.log(order.join(" -> "));
Run that and the console prints analytics.js ran -> app.js ran. Swap the two call lines and the output swaps with them, because classic scripts never overlap.
With defer, all of the deferred scripts still run in document order among themselves, but they all wait for the page to finish parsing first. With async, each script runs the moment its download finishes, so the order depends on the network.
// Deferred scripts keep document order even if the network delivers them
// out of order. Async scripts would run in download order instead.
const documentOrder = ["analytics.js", "app.js"];
const downloadOrder = ["app.js", "analytics.js"];
console.log("download order: ", downloadOrder.join(" -> "));
console.log("defer runs as: ", documentOrder.join(" -> "));
console.log("async would run: ", downloadOrder.join(" -> "));
The two answers differ, and that difference is the whole point. If app.js depends on something that analytics.js defines, then defer keeps that guarantee and async breaks it.
Why does a script in the head fail to find my button?
This is the most common first-week error. You put a <script> in the <head>, you call document.getElementById("go"), and you get null back. The script ran perfectly. The problem is timing.
The browser parses HTML from top to bottom. When it reaches a <script> tag it pauses, runs the code, and then resumes parsing afterwards. A script in the <head> therefore runs before the <body> exists. There is no #go element yet, and getElementById correctly returns null.
There are three fixes, in order of preference. Add defer, or async when the order does not matter. Move the script to the end of the <body>. Or wait for the DOM to be ready. The third option exists, but it is rarely the best one, because it forces your whole script into a callback.
document.addEventListener("DOMContentLoaded", function () {
const output = document.getElementById("output");
document.getElementById("go").addEventListener("click", function () {
output.textContent = "clicked";
});
});
Compare that with the top-level version from the previous section. The behaviour is the same, there is one less layer of indentation, and there is no waiting at all, because defer already guarantees that the DOM exists. Reach for DOMContentLoaded only when you have to support a script that you do not control.
Do inline event handlers still work?
They do work, and they are also the weakest option of the three.
<button onclick="count += 1; output.textContent = count;">Count</button>
<p id="output">0</p>
The code lives inside an HTML attribute, so it is invisible to most editors, it cannot be tested, it cannot be reused, and it has to reach into variables that were declared somewhere else. The count and output above only exist if some script put them on the window. Inline handlers also break the moment you need to pass the clicked element, because this inside an inline handler is the element itself, and that is a trap that you will meet again when functions come up.
Treat inline handlers as something to read and to understand, and not as something to write. The moment you need more than one line, move to addEventListener.
Which approach should you reach for?
- Use
<script src="app.js" defer></script>in the<head>for application code. One file, cacheable, and safe with the order of your scripts. - Use an inline tag only for a throwaway experiment, or for a tiny snippet that has to run before anything else.
- Use
asyncfor independent extras such as analytics or ad tags, where the arrival order does not matter. - Use
DOMContentLoadedonly when you do not control when your script is loaded. - Never write new inline event handlers. Translate them to
addEventListenerwhen you touch the file.
Try it yourself: Create index.html and app.js side by side. First, put a plain <script src="app.js"></script> at the end of <body> and have app.js log "loaded". Then move the tag into the <head> without defer and confirm that it still logs, but that it now runs before the body exists. Finally, add defer and check the order again in the console. Three placements, three different execution points, and one file that you did not have to rewrite.