서문 & 소개 — 이 글이 존재하는 이유

이 글은 반박이 아닙니다. Tanner Linsley의 훌륭한 "Directives and the Platform Boundary" 글에서 영감을 받은 성찰입니다. 그 글을 정말 재밌게 읽었고 많은 부분에 동의합니다 — 특히 소유권, 출처, 명시적 API의 가치에 관한 부분들이요. 제가 추가하고 싶은 것은 약간 다른 관점입니다: 지시어 기반 도구를 만들면서 얻은 경험과, JavaScript에 'use client'나 'use server'가 있기 훨씬 전의 프로그래밍 역사에서 매우 유사한 시대를 겪었던 경험에서 나온 관점입니다.

React Server Components와 Next.js 같은 프레임워크의 진화를 따라오지 못한 사람을 위해 설명하자면: 현대의 React 앱은 이제 'use client'와 'use server' 같은 파일 수준의 지시어를 사용해서 코드가 어디서 실행될지를 제어합니다. 파일 맨 위의 단순한 문자열 리터럴처럼 보이지만, 컴포넌트가 서버에서 실행될지 클라이언트에서 실행될지를 결정하고 — 번들링, 렌더링, 데이터 흐름을 형성합니다. 혼동이 시작되는 지점이 바로 여기입니다.

개인적인 회상

지시어가 언어 기능처럼 느껴지는 이유

'use client';

export function Button() {
  return <button>Click</button>;
}

"JavaScript의 일부입니다."

"파일 맨 위의 지시어는 권위 있어 보입니다. 프레임워크 힌트가 아닌 언어 수준의 기능같은 인상을 줍니다."

숨겨진 메커니즘이 더 악화시킵니다

import { client } from 'somewhere';

빌드 도구를 추가하면... 환상이 굳어집니다

"번들러가 필요하다면, 언어의 일부가 아니라 생태계 플랫폼의 일부 아닌가요?"

돌아보기: C/C++ 매크로와 전처리기

C 전처리기는 언어가 아니었습니다 — 하지만 그렇게 느껴졌습니다

#define PI 3.14

'use server';

pragma: 원조 프레임워크 지시어

#pragma once

Include Guards: 첫 번째 "보이지 않는 빌드타임 동작"

#ifndef MY_HEADER_H
#define MY_HEADER_H

// header contents

#endif

C/C++는 개발자들에게 "파일에 쓴 코드"와 "언어 자체"가 같은 것이 아니라는 것을 배우도록 강제했습니다.

다단계 컴파일: 익숙한 파이프라인

전처리기 → 컴파일러 → 링커 → 실행 파일

지시어 스캐너 / 로더 → AST 변환 → 번들러 → 출력 청크

전처리기 시대의 시각을 통한 현대 지시어

지시어는 실행되지 않습니다 — 도구에 명령합니다

이들은 그 자체로는 아무것도 하지 않습니다 — 이들은 다른 무언가가 어떻게 동작할지만 바꿉니다.

파일 읽기 → 지시어 확인 → 환경 / 경계 결정 →
변환 실행 → 클라이언트/서버 번들 생성 → 출력

파일 읽기 → 전처리기가 매크로 확장 + 프래그마 처리 →
컴파일 → 링크 → 출력

언어 기능의 환상이 지속되는 이유

하지만 현대 지시어는 C pragma보다 더 나아갑니다

무언가가 런타임 실행과 코드 배치에 영향을 준다면, 우리는 이를 "파일 맨 위의 단순한 문자열"로 취급해서는 안 됩니다.

빌드 도구가 지시어의 실제 해석자입니다

'use streaming-server';

📦 인라인 서버 함수가 지시어의 필요성을 드러낼 때 저는 한 번 지시어가 왜 필요한지를 완벽하게 드러내는 경우를 마주쳤습니다. 서버 컴포넌트 내부에 정의된 인라인 서버 함수를 생각해 봅시다, 로컬 스코프에서 변수를 캡처하는: 얼핏 보기에, 이것은 일반적인 함수 호출처럼 느껴집니다. 하지만 이것이 작동하려면, 번들러는 미묘하고 필수적인 무언가를 해야 합니다: 런타임 헬퍼는 이를 해결할 수 없습니다. 코드가 실행될 때쯤이면, 클로저는 사라지고 의도는 이미 손실됩니다. 함수는 프로그램이 존재하기 전에 변환되어야 하므로, 클라이언트가 이를 직접 함수로 호출할 수 있습니다, 너무 늦게 함께 꿰맨 프록시가 아니라. 이것이 지시어가 이 공간에 잘 맞는 이유입니다: 이들은 정의 시점에 빌드 도구에 이 함수가 정말 무엇인지를 알려주고, 이에 따라 형성할 시간을 줍니다. 어떤 결정은 코드가 여전히 짜여지고 있을 때 일어나야 합니다 — 이미 살아있은 후가 아니라.

교육적 격차 — 그리고 역사에서 배울 수 있는 것

문제는 더 이상 기술적이지 않습니다 — 교육적입니다.

우리는 기능이 아니라 레이어링을 가르쳐야 합니다

C/C++ 커뮤니티가 결국 배운 것

지시어는 나쁘지 않습니다 — 이해되면 강력합니다

내일부터 가르칠 수 있는 단순한 멘탈 모델

"지시어는 당신의 빌드 도구를 위해 남기는 메모입니다 — JavaScript를 위한 것이 아닙니다."

"#pragma once가 C++ 문법이 아니었다면, 'use client'도 오늘날 JavaScript 문법이 아닙니다."

명확성을 향한 실질적인 단계: 지시어를 위한 TypeScript 플러그인

TypeScript 플러그인이 지시어를 "강제"할 수 있다는 일반적인 가정이 있습니다 — 플러그인이 이들을 알면, 시스템이 기본적으로 안전해진다는 것입니다. 하지만 TS 플러그인은 Language Service에 있습니다. 이것은 인식, 경고, 지침을 제공할 수 있습니다 — 그런데도 코드가 실제로 변환되는 곳에서 실행되지 않습니다. 컴파일이나 번들링에 참여하지 않습니다. 플러그인은 지시어 사용을 식별하는 데 도움이 될 수 있지만, 이들의 의미론을 강제할 수 없습니다. 그를 위해, 컴파일러는 의도의 신호가 필요합니다 — 타입 시스템이 이해할 수 있는 무언가. 이를 가능하게 하기 위해, 저는 플러그인에서 전역 Directive 타입을 노출합니다. 저자들은 satisfies를 사용할 수 있습니다 — 편집기에 알리기 위해서가 아니라, TypeScript 컴파일러에 알리기 위해 주어진 문자열이 지시어로 의도되었다는 것을: 'use server' satisfies Directive; 이것은 동작이나 변환을 트리거하지 않습니다. 그것이 하는 것은 훨씬 더 기본적이고 근본적입니다: 타입 시스템에 알립니다: "이것을 지시어로 취급하세요 — 그리고 그렇게 검증하세요." 이것은 의도를 런타임이 아닌 컴파일러와 정렬하고, IDE뿐만 아니라. 인라인 서버 함수를 컴포넌트 밖으로 끌어올리고, 캡처된 스코프를 분석하고, 직접 호출 가능한 경계를 생성하는 실제 분리 — 이것은 여전히 전적으로 빌드에 속합니다. 타입 시스템은 의도를 인정할 수 있지만, 번들러가 이에 작용해야 합니다. 한 가지 실질적인 주의: 오늘날, Next.js를 포함한 일부 도구는 지시어가 벌거벗은 문자열 리터럴로 나타나기를 기대합니다. 'use server' satisfies Directive로 쓰여질 때, 지시어는 더 이상 감지되지 않을 수 있습니다, 리터럴이 더 이상 프레임워크가 스캔하는 정확한 형태가 아니기 때문입니다. 이것이 변할 때까지, 이 패턴은 Next.js에 의해 선택되지 않을 것입니다. 한 가지 더 미묘한 점이 있습니다. 이 타입 수준의 의도는 타입 체커가 실제로 실행되는 경우에만 중요합니다. 많은 현대 도구 체인 — esbuild, SWC, Oxc, Bun, 심지어 대부분의 Deno와 Vite 설정 — 전혀 타입 체크하지 않습니다. 이들은 단순히 타입을 제거하고 계속합니다. 그 환경에서, Directive + satisfies 표현은 듣기 위해 기회를 가지지 못한 컴파일러에 대한 조용한 메모가 됩니다.

마무리 성찰