브라우저에서 작성하는 JavaScript 코드는 겉으로는 하나의 언어처럼 보입니다.

하지만 실제로는 JavaScript 언어와 브라우저가 제공하는 기능이 함께 동작합니다.

이 문서는 앞으로 브라우저 API를 배우기 전에 반드시 알아야 할 전체 지도를 설명합니다.

• JavaScript와 ECMAScript는 어떤 관계인지
• Web API는 어디에서 제공되는지
• document와 Promise는 무엇이 다른지
• 브라우저와 Node.js는 왜 사용할 수 있는 기능이 다른지
• 새로운 API를 사용할 때 무엇을 확인해야 하는지

먼저 코드부터 살펴보기

다음 코드는 버튼을 클릭하면 화면의 문구를 바꾸고 값을 브라우저에 저장합니다.

const button = document.querySelector("#saveButton");
const message = document.querySelector("#message");
 
button.addEventListener("click", () => {
  message.textContent = "저장되었습니다.";
  localStorage.setItem("status", "saved");
});

코드는 모두 JavaScript 문법으로 작성되어 있습니다.

하지만 코드 안의 모든 기능이 JavaScript 언어 자체에 포함된 것은 아닙니다.

ECMAScript는 코드의 구조와 실행 순서를 만듭니다.

Web API는 HTML 요소를 찾고, 클릭을 감지하고, 데이터를 저장하는 실제 브라우저 기능을 수행합니다.

JavaScript와 ECMAScript는 같은 말일까?

두 단어는 자주 같은 의미로 사용되지만 정확히는 구분할 필요가 있습니다.

document.querySelector("button");

ECMA와 ECMA-262

ECMA는 정보 통신 기술의 표준을 만드는 표준화 기구입니다. ECMAScript는 ECMA가 관리하는 스크립트 언어 표준이며, 공식 명세 번호는 ECMA-262입니다.

브라우저 JavaScript의 전체 구조

브라우저는 JavaScript 엔진만으로 이루어져 있지 않습니다.

HTML을 읽고, CSS를 계산하고, 화면을 그리고, 사용자 입력을 처리하고, 네트워크와 통신하는 여러 기능이 함께 동작합니다.

브라우저
├─ JavaScript 엔진
│  └─ ECMAScript 코드 실행
│
├─ DOM
│  └─ HTML 문서를 객체로 제공
│
├─ HTML 관련 API
│  ├─ window
│  ├─ history
│  ├─ localStorage
│  └─ setTimeout
│
├─ 네트워크 API
│  └─ fetch, Request, Response
│
└─ 기타 Web API
   ├─ Canvas
   ├─ Clipboard
   ├─ Geolocation
   ├─ Web Worker
   └─ Performance

JavaScript 엔진은 ECMAScript 코드를 해석하고 실행합니다.

브라우저는 그 위에 웹 페이지를 제어할 수 있는 객체와 함수를 추가합니다.

Web Platform과 Web API

Web Platform은 HTML, CSS, DOM, Fetch, URL 등 브라우저가 구현하는 웹 기술 전체를 가리키는 넓은 표현입니다.

Web API는 그중 JavaScript에서 호출할 수 있도록 객체와 메서드 형태로 제공되는 기능을 뜻합니다.

ECMAScript가 정의하는 것

ECMAScript는 JavaScript 언어의 문법과 기본 기능을 정의합니다.

문법

const userName = "Kim";
 
if (userName) {
  console.log(userName);
}

const, if, 중괄호, 문자열과 함수 호출 문법은 ECMAScript에서 정의합니다.

값과 타입

const count = 10;
const name = "Kim";
const enabled = true;
const empty = null;

숫자, 문자열, 불리언, null, undefined 같은 값도 ECMAScript가 정의합니다.

표준 내장 객체

const users = new Map();
const values = new Set();
const task = Promise.resolve("완료");

Map, Set, Promise는 ECMAScript가 정의하는 표준 내장 객체입니다.

배열과 객체의 동작

const prices = [1000, 2000, 3000];
 
const discountedPrices = prices.map((price) => {
  return price * 0.9;
});

배열, 객체, 함수, map() 같은 동작도 ECMAScript 영역에 속합니다.

참고: console은 매우 익숙하지만 ECMA-262가 정의하는 표준 내장 객체는 아닙니다.

브라우저와 Node.js 같은 실행 환경이 개발자가 로그를 확인할 수 있도록 제공하는 API입니다.

Web API가 정의하는 것

Web API는 브라우저가 가진 기능을 JavaScript에서 사용할 수 있게 해줍니다.

문서 제어

const title = document.querySelector("h1");
 
title.textContent = "변경된 제목";

document는 현재 HTML 문서를 나타냅니다.

querySelector()는 CSS 선택자와 일치하는 첫 번째 요소를 찾습니다.

textContent는 요소의 텍스트를 읽거나 변경합니다.

이벤트 처리

const button = document.querySelector("button");
 
button.addEventListener("click", () => {
  console.log("버튼 클릭");
});

addEventListener()는 클릭, 입력, 스크롤 같은 이벤트가 발생했을 때 실행할 함수를 등록합니다.

네트워크 요청

const response = await fetch("/api/posts");
const posts = await response.json();

fetch()는 네트워크에서 리소스를 가져오기 위한 Fetch API의 진입점입니다.

데이터 저장

localStorage.setItem("theme", "dark");
 
const theme = localStorage.getItem("theme");

localStorage는 현재 출처에 문자열 데이터를 저장합니다.

페이지를 닫았다가 다시 열어도 데이터가 유지될 수 있습니다.

표준 내장 객체와 환경 제공 객체

코드를 읽을 때 다음 두 종류를 구분하면 이해가 쉬워집니다.

과거에는 실행 환경이 제공하는 객체를 호스트 객체라고 부르기도 했습니다.

이 문서에서는 더 쉽게 이해할 수 있도록 “환경이 제공하는 객체”라고 표현합니다.

API, 인터페이스, 객체, 프로퍼티, 메서드

Web API 문서를 읽으면 비슷해 보이는 용어가 계속 등장합니다.

다음 코드를 기준으로 구분해 보겠습니다.

const title = document.querySelector("h1");
 
title.textContent = "새 제목";

인터페이스와 객체의 차이

Document는 문서 객체가 어떤 기능을 제공해야 하는지 설명하는 인터페이스 이름입니다.

document는 현재 페이지에서 실제로 사용하는 Document 객체입니다.

console.log(document);

Element는 HTML 요소 객체가 제공하는 기능을 설명하는 인터페이스입니다.

querySelector()로 찾은 요소는 일반적으로 Element 계열의 실제 객체입니다.

const button = document.querySelector("button");
 
console.log(button);

인터페이스는 설계도 또는 계약에 가깝고, 객체는 그 계약에 따라 실제로 만들어져 코드에서 사용하는 값에 가깝습니다.

Web IDL은 무엇일까?

웹 표준 문서를 보면 JavaScript와 비슷하지만 조금 다른 코드가 등장합니다.

interface Example {
  attribute DOMString value;
  undefined run();
};

이 문법은 JavaScript가 아니라 Web IDL입니다.

IDL은 Interface Definition Language의 약자입니다.

Web IDL은 브라우저가 구현할 인터페이스를 웹 표준 문서에서 표현하기 위한 언어입니다.

Web IDL에 적힌 인터페이스
        ↓
브라우저가 해당 기능을 구현
        ↓
JavaScript 객체와 메서드로 노출

개발자가 Web IDL을 직접 작성할 일은 많지 않습니다.

하지만 명세에서 다음 표현을 만났을 때 대략적인 의미를 알아볼 수 있어야 합니다.

여기서 기억할 점

Web IDL의 세부 문법을 외울 필요는 없습니다.

이 코드는 JavaScript 실행 예제가 아니라 브라우저가 구현해야 할 API 계약을 표현한다는 점만 먼저 이해하면 충분합니다.

브라우저의 전역 환경

일반적인 웹 페이지에서는 window가 전역 객체 역할을 합니다.

window는 현재 브라우징 컨텍스트를 나타내며 현재 문서는 window.document로 접근할 수 있습니다.

console.log(window.document === document);
// true

브라우저가 전역에 제공한 기능은 대부분 window.를 생략하고 사용할 수 있습니다.

window.setTimeout(() => {
  console.log("실행");
}, 1000);

setTimeout(() => {
  console.log("실행");
}, 1000);

두 코드는 일반적인 브라우저 페이지에서 같은 방식으로 동작합니다.

모든 환경에 window가 있는 것은 아니다

• 브라우저의 일반 페이지에는 window가 있습니다.
• Web Worker에는 window가 없습니다.
• Node.js에는 브라우저의 window가 없습니다.

환경과 관계없이 현재 전역 값을 가리키는 표준 방법으로 globalThis를 사용할 수 있습니다.

console.log(globalThis);

정리하면

• window는 브라우저가 제공하는 객체입니다.
• globalThis는 여러 환경에서 전역 값에 접근할 수 있도록 ECMAScript가 정의한 표준 프로퍼티입니다.

window와 전역 환경은 뒤의 문서에서 더 자세히 다룹니다.

DOM, CSSOM, BOM은 무엇일까?

브라우저 관련 문서에서 세 용어가 자주 함께 등장합니다.

document.querySelector("h1");

const style = getComputedStyle(document.body);
 
console.log(style.color);

window;
location;
history;
navigator;

브라우저에서는 되고 Node.js에서는 안 되는 이유

다음 코드는 브라우저에서 실행됩니다.

const title = document.querySelector("h1");

하지만 일반적인 Node.js 환경에서는 오류가 발생합니다.

ReferenceError: document is not defined

Node.js에는 기본적으로 현재 웹 페이지와 HTML 문서가 없습니다.

따라서 브라우저가 제공하는 document 객체도 존재하지 않습니다.

반면 다음 코드는 브라우저와 Node.js에서 모두 실행할 수 있습니다.

const numbers = [1, 2, 3];
 
const doubled = numbers.map((number) => {
  return number * 2;
});

배열, 함수, map()은 ECMAScript가 정의한 기능이기 때문입니다.

Node.js에도 fetch()와 setTimeout()이 있는데?

최근의 JavaScript 실행 환경은 서로 비슷한 API를 제공하기도 합니다.

fetch()

fetch()는 Fetch Standard에서 정의하는 Web API입니다.

브라우저뿐 아니라 다른 JavaScript 실행 환경에서도 이 웹 표준과 호환되는 fetch()를 제공할 수 있습니다.

const response = await fetch("https://example.com");

Node.js에서 실행된다고 해서 fetch()가 ECMAScript 기능으로 바뀌는 것은 아닙니다.

setTimeout()

브라우저의 setTimeout()은 HTML Standard에서 정의합니다.

Node.js도 같은 이름과 비슷한 사용법을 가진 타이머 API를 제공합니다.

setTimeout(() => {
  console.log("1초 후 실행");
}, 1000);

이 시리즈에서는 브라우저에서의 동작과 웹 표준을 중심으로 설명합니다.

기능의 출처를 구분하는 기준

처음 보는 기능이 ECMAScript인지 Web API인지 헷갈린다면 다음 순서로 확인합니다.

const
let
function
class
Array
Object
Map
Set
Promise
globalThis

document
fetch
localStorage
location
history
navigator
requestAnimationFrame

명세와 MDN은 어떤 차이가 있을까?

웹 개발 문서를 찾으면 여러 단체와 사이트 이름이 등장합니다.

명세와 MDN의 역할

명세는 브라우저 구현자가 따라야 할 정확한 규칙을 정의합니다. MDN은 개발자가 API를 사용할 수 있도록 문법, 예제, 반환값, 주의점, 호환성을 정리합니다.

일반적인 학습과 개발에서는 MDN을 먼저 읽고, 더 정확한 동작이 필요할 때 명세를 확인하면 됩니다.

MDN 문서는 어떤 순서로 읽을까?

처음부터 문서 전체를 읽을 필요는 없습니다.

querySelector() 같은 메서드를 찾았다면 다음 순서로 확인하면 됩니다.

document.querySelector(selectors);

브라우저 지원과 Baseline

JavaScript 문법 지원과 Web API 지원은 같은 문제가 아닙니다.

다음 코드는 ECMAScript 문법 지원과 관련됩니다.

const city = user?.address?.city;

다음 코드는 Web API 지원과 관련됩니다.

const observer = new IntersectionObserver(() => {});

브라우저가 최신 JavaScript 문법을 지원한다고 해서 모든 Web API를 지원하는 것은 아닙니다.

Baseline이 의미하는 것

Baseline은 주요 브라우저에서 기능을 사용할 수 있는 상태를 쉽게 판단할 수 있도록 만든 표시입니다.

하지만 Baseline만으로 다음 조건까지 모두 보장되지는 않습니다.

• 사용자의 권한 허용
• HTTPS 같은 보안 조건
• 특정 기기에서의 동작
• WebView 지원
• 오래된 브라우저 지원
• 성능과 접근성

기능 감지

브라우저 이름을 보고 API 사용 가능 여부를 추측하는 것보다 기능이 실제로 존재하는지 확인하는 편이 안전합니다.

if ("geolocation" in navigator) {
  console.log("Geolocation API를 사용할 수 있습니다.");
} else {
  console.log("위치를 직접 입력하는 기능이 필요합니다.");
}

fetch()를 확인하려면 다음처럼 작성할 수 있습니다.

if (typeof globalThis.fetch === "function") {
  console.log("fetch()를 사용할 수 있습니다.");
}

이 방식을 기능 감지라고 합니다.

실행 가능한 전체 예제

다음 예제는 DOM, 이벤트, 타이머를 함께 사용합니다.

<!doctype html>
<html lang="ko">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>브라우저 JavaScript 실습</title>
  </head>
 
  <body>
    <h1 id="title">브라우저 JavaScript</h1>
    <button id="changeButton" type="button">제목 변경</button>
    <p id="status">버튼을 눌러보세요.</p>
 
    <script>
      const title = document.querySelector("#title");
      const button = document.querySelector("#changeButton");
      const status = document.querySelector("#status");
 
      if (!title || !button || !status) {
        throw new Error("필요한 HTML 요소를 찾지 못했습니다.");
      }
 
      button.addEventListener("click", () => {
        title.textContent = "제목이 변경되었습니다.";
        status.textContent = "잠시 기다려주세요.";
 
        setTimeout(() => {
          status.textContent = "작업이 완료되었습니다.";
        }, 1000);
      });
    </script>
  </body>
</html>

코드는 다음 순서로 동작합니다.

이 예제에서 영역 구분하기

실무에서 이 구분이 필요한 이유

ECMAScript와 Web API를 구분하는 것은 단순한 용어 공부가 아닙니다.

오류 원인을 빠르게 찾을 수 있다

ReferenceError: document is not defined

이 오류를 보면 JavaScript 문법 문제가 아니라 현재 실행 환경에 document가 없다는 점을 먼저 의심할 수 있습니다.

검색할 문서를 판단할 수 있다

• Array.map() 문제 → JavaScript Reference
• document.querySelector() 문제 → Web API 문서
• fetch() 문제 → Fetch API와 HTTP 문서
• localStorage 문제 → Web Storage 문서

브라우저 호환성을 따로 확인할 수 있다

새로운 문법을 지원하는 브라우저라도 특정 Web API는 지원하지 않을 수 있습니다.

실행 환경에 맞는 코드를 작성할 수 있다

Worker에서 window를 사용하거나 Node.js에서 document를 사용하는 실수를 줄일 수 있습니다.

프레임워크를 더 쉽게 이해할 수 있다

React, Vue, Next.js 같은 도구도 브라우저 환경과 Web API 위에서 동작합니다.

기본 경계를 이해하면 프레임워크 코드와 브라우저 기능을 분리해서 생각할 수 있습니다.

흔한 실수

document를 JavaScript 기본 기능이라고 생각한다

잘못된 설명:

JavaScript에는 document 객체가 있다.

더 정확한 설명:

브라우저는 현재 HTML 문서를 나타내는
document 객체를 JavaScript에 제공한다.

querySelector()의 결과가 항상 있다고 생각한다

querySelector()는 요소를 찾지 못하면 null을 반환합니다.

const button = document.querySelector("#saveButton");
 
if (button) {
  button.addEventListener("click", () => {
    console.log("저장");
  });
}

window가 모든 환경에 있다고 생각한다

if (window.fetch) {
  console.log("fetch 사용 가능");
}

이 코드는 window가 없는 환경에서 바로 오류가 발생할 수 있습니다.

환경에 독립적으로 확인하려면 globalThis를 사용할 수 있습니다.

if (typeof globalThis.fetch === "function") {
  console.log("fetch 사용 가능");
}

Node.js에서 실행되면 ECMAScript라고 생각한다

Node.js가 fetch()를 제공해도 fetch()의 표준 출처는 Fetch Standard입니다.

환경이 API를 구현했다고 해서 언어 표준의 일부가 되는 것은 아닙니다.

브라우저 이름으로 기능을 추측한다

if (navigator.userAgent.includes("Chrome")) {
  // 특정 기능이 있다고 가정
}

브라우저 이름만으로 기능의 존재를 정확히 판단하기 어렵습니다.

가능하면 기능 감지를 사용합니다.

if ("IntersectionObserver" in globalThis) {
  // 기능 사용
}

알아두면 좋은 약어

이 시리즈에서 다루는 범위

이 시리즈는 ECMAScript 언어 자체보다 브라우저가 제공하는 환경과 Web API를 다룹니다.

핵심 정리

• Array, Map, Promise, globalThis는 ECMAScript 영역입니다.
• window, document, localStorage, location은 브라우저가 제공합니다.
• 브라우저 JavaScript는 ECMAScript 문법으로 Web API를 호출합니다.
• 같은 이름의 API가 여러 환경에 있어도 정의된 표준과 구현은 다를 수 있습니다.
• 기능의 출처는 MDN의 Specifications와 관련 명세에서 확인합니다.
• Web API는 JavaScript 문법 지원과 별도로 브라우저 호환성을 확인해야 합니다.
• API 존재 여부뿐 아니라 권한, 보안 환경, 사용자 동작 조건도 확인해야 합니다.

확인 문제

문제 1

다음 기능을 ECMAScript와 Web API로 나누어 보세요.

Array
document
Promise
localStorage
globalThis
fetch

문제 2

다음 코드가 Node.js에서 실패하는 이유는 무엇인가요?

const title = document.querySelector("h1");

문제 3

Node.js에서 fetch()를 사용할 수 있으면 fetch()는 ECMAScript 기능인가요?

문제 4

Document와 document의 차이는 무엇인가요?

문제 5

새로운 Web API를 사용하기 전에 무엇을 확인해야 하나요?

참고 자료

• MDN: JavaScript technologies overview 
• MDN: Web APIs 
• MDN: Window 
• MDN: globalThis 
• MDN: Document.querySelector 
• MDN: EventTarget.addEventListener 
• MDN: Fetch API 
• MDN: Window.localStorage 
• ECMAScript Language Specification 
• WHATWG HTML Standard 
• WHATWG DOM Standard 
• WHATWG Fetch Standard 
• WHATWG Web IDL Standard 
• WHATWG Console Standard