tone down the directive post

Author: tannerlinsley

public/blog-assets/directives-and-the-platform-boundary/header.png

@@ -1,38 +1,36 @@
 ---
-title: Directives Are Becoming the New Framework Lock In
+title: Directives and the Platform Boundary
 published: 2025-10-24
 authors:
   - Tanner Linsley
+description: A constructive look at framework directives, portability, and keeping a clear boundary between platform and library spaces.
 ---
 
-![Directives Are Becoming the New Framework Lock In - A Quiet Problem in the JavaScript Ecosystem](/blog-assets/directives-the-new-framework-lock-in/header.png)
+![Header Image](/blog-assets/directives-and-the-platform-boundary/header.png)
 
-## A Quiet Problem in the JavaScript Ecosystem
+## A Quiet Trend in the JavaScript Ecosystem
 
 For years, JavaScript has had exactly one meaningful directive, `"use strict"`. It is standardized, enforced by runtimes, and behaves the same in every environment. It represents a clear contract between the language, the engines, and developers.
 
 But now we are watching a new trend emerge. Frameworks are inventing their own top level directives, `use client`, `use server`, `use cache`, `use workflow`, and more are appearing across the ecosystem. They look like language features. They sit where real language features sit. They affect how code is interpreted, bundled, and executed.
 
-There is just one problem.
+There is an important distinction: these are not standardized JavaScript features. Runtimes don't understand them, there is no governing specification, and each framework is free to define its own meaning, rules, and edge cases.
 
-**They are not JavaScript.**
-
-They are not standardized. Runtimes don't understand them. They have no governing specification. And each framework is free to define its own meaning, its own rules, and its own edge cases.
-
-This might feel harmless or ergonomic today, but it carries long term consequences for the ecosystem, consequences we have seen before.
+This can feel ergonomic today, but it also increases confusion, complicates debugging, and imposes costs on tooling and portability—patterns we’ve seen before.
 
 ---
 
-### When Directives Look Like the Platform, Developers Treat Them Like the Platform
+### When directives look like the platform, developers treat them like the platform
 
 A directive at the top of a file looks authoritative. It gives the impression of being a language level truth, not a framework hint. That creates a perception problem:
 
 - Developers assume directives are official
 - Ecosystems begin to treat them as a shared API surface
 - New learners struggle to distinguish JavaScript from framework magic
 - The boundary between platform and vendor blurs
+- Debuggability suffers and tooling must special‑case behaviors
 
-We are already seeing confusion in the wild. Many developers now believe `use client` and `use server` are just how modern JavaScript works, unaware that they only exist inside specific build pipelines and server component semantics. That misunderstanding is a signal of a deeper issue.
+We’ve already seen confusion. Many developers now believe `use client` and `use server` are just how modern JavaScript works, unaware that they only exist inside specific build pipelines and server component semantics. That misunderstanding signals a deeper issue.
 
 ---
 
@@ -42,9 +40,9 @@ Some directives exist because multiple tools needed a single, simple coordinatio
 
 That said, even these show the limits of directives once real-world needs appear. At scale, you often need parameters and policies that matter deeply to correctness and security: HTTP method, headers, middleware, auth context, tracing, caching behaviors, and more. Directives have no natural place to carry those options, which means they are frequently ignored, bolted on elsewhere, or re-encoded as new directive variants.
 
-### The real offenders: option-laden directives and directive-adjacent APIs
+### Where directives start to strain: options and directive-adjacent APIs
 
-When a directive immediately, or soon after creation, needs options or spawns siblings (e.g., `'use cache:remote'`) and helper calls like `cacheLife(...)`, that’s a strong signal the feature wants to be an API, not a string at the top of a file. If you know you need a function anyway, just use a function for all of it.
+When a directive immediately, or soon after creation, needs options or spawns siblings (e.g., `'use cache:remote'`) and helper calls like `cacheLife(...)`, that’s often a signal the feature wants to be an API, not a string at the top of a file. If you know you need a function anyway, just use a function for all of it.
 
 Examples:
 
@@ -67,20 +65,23 @@ And for server behavior where details matter:
 ```js
 import { server } from '@acme/runtime'
 
-export const action = server(async (req) => {
-  return new Response('ok')
-}, {
-  method: 'POST',
-  headers: { 'x-foo': 'bar' },
-  middleware: [requireAuth()],
-})
+export const action = server(
+  async (req) => {
+    return new Response('ok')
+  },
+  {
+    method: 'POST',
+    headers: { 'x-foo': 'bar' },
+    middleware: [requireAuth()],
+  }
+)
 ```
 
-APIs carry provenance (imports), versioning (packages), composition (functions), and testability. Directives don’t — and trying to smuggle options into them quickly becomes a design smell.
+APIs carry provenance (imports), versioning (packages), composition (functions), and testability. Directives typically don’t — and trying to encode options into them can quickly become a design smell.
 
 ---
 
-### A Shared Syntax Without a Shared Spec Is a Fragile Foundation
+### Shared syntax without a shared spec can be a fragile foundation
 
 Once multiple frameworks start adopting directives, we end up in the worst possible state:
 
@@ -97,9 +98,7 @@ A shared surface area without a shared definition creates:
 - Tooling burden, bundlers, linters, and IDEs must guess or chase behavior
 - Platform friction, standards bodies get boxed in by ecosystem expectations
 
-We already lived through this with decorators. TypeScript normalized a non standard semantics, the community built on top of it, then TC39 went in a different direction. Years of pain followed.
-
-Why are we walking into the same trap again?
+An example of where we've seen these struggles before is with decorators. TypeScript normalized a non standard semantics, the community built on top of it, then TC39 went in a different direction. This was and continues to be a painful migration for many.
 
 ---
 
@@ -110,7 +109,7 @@ Functionally, yes — both directives and custom transforms can change behavior
 - Directives look like the platform. No import, no owner, no explicit source. They signal “this is JavaScript.”
 - APIs/macros point to an owner. Imports provide provenance, versioning, and discoverability.
 
-At best, a directive is equivalent to calling a global, importless function like `window.useCache()` at the top of your file. That’s exactly why it’s risky: it hides the provider and smuggles framework semantics into what looks like language.
+At best, a directive is equivalent to calling a global, importless function like `window.useCache()` at the top of your file. That’s exactly why it’s risky: it hides the provider and moves framework semantics into what looks like language.
 
 Examples:
 
@@ -167,15 +166,15 @@ If the goal is provenance, imports already solve that cleanly and work with toda
 
 ---
 
-### Directives Create an Ecosystem Arms Race
+### Directives can drive competitive dynamics
 
 Once directives become a competitive surface, the incentives shift:
 
 1. One vendor ships a new directive
-2. It becomes a marketing feature
+2. It becomes a visible feature
 3. Developers expect it everywhere
-4. Other frameworks feel forced to copy it
-5. The pseudo standard spreads without a spec
+4. Other frameworks feel pressure to adopt it
+5. The syntax spreads without a spec
 
 This is how you get:
 
@@ -189,25 +188,23 @@ This is how you get:
 'use edge'
 ```
 
-Even durable tasks, caching strategies, and execution locations are now being encoded as directives. These are runtime semantics, not syntax semantics. Encoding them as directives is a form of platform creep, an attempt to define how developers think about capability boundaries using what looks like language grammar.
-
-That is not harmless. That is direction setting outside the standards process.
+Even durable tasks, caching strategies, and execution locations are now being encoded as directives. These are runtime semantics, not syntax semantics. Encoding them as directives sets direction outside the standards process and merits caution.
 
 ---
 
-### The Lock In Is Subtle, but Real
+### Subtle forms of lock‑in can emerge
 
 Even when there is no bad intent, directives create lock in by design:
 
 - Mental lock in, developers form muscle memory around a vendor's directive semantics
 - Tooling lock in, IDEs, bundlers, and compilers must target a specific runtime
 - Code lock in, directives sit at the syntax level, making them costly to remove or migrate
 
-Directives do not look proprietary, but they behave more proprietary than an API ever could, because they reshape the grammar of the ecosystem.
+Directives may not look proprietary, but they can behave more like proprietary features than an API would, because they reshape the grammar of the ecosystem.
 
 ---
 
-### If We Want Shared Primitives, We Should Collaborate, Not Fork the Language
+### If we want shared primitives, we should collaborate on specs and APIs
 
 There absolutely are real problems to solve:
 
@@ -219,26 +216,26 @@ There absolutely are real problems to solve:
 
 But those are problems for **APIs, capabilities, and future standards**, not for ungoverned pseudo syntax pushed through bundlers.
 
-If multiple frameworks truly want shared primitives, the responsible path is:
+If multiple frameworks truly want shared primitives, a responsible path is:
 
 - Collaborate on a cross framework spec
 - Propose primitives to TC39 when appropriate
 - Keep non standard features clearly scoped to API space, not language space
 
-Directives should be rare, stable, and standardized, not multiplied by every vendor with a new idea.
+Directives should be rare, stable, and standardized—used judiciously rather than proliferating across vendors.
 
 ---
 
-### This is not the JSX/virtual DOM moment
+### Why this differs from the JSX/virtual DOM moment
 
-It’s tempting to compare criticism of directives to the early skepticism around React’s JSX or the virtual DOM. I get the sentiment, but the failure modes are different. JSX and the VDOM did not masquerade as language features; they came with explicit imports, provenance, and tooling boundaries. Directives, by contrast, live at the top-level of files and look like the platform, which creates ecosystem expectations and tooling burdens without a shared spec.
+It’s tempting to compare criticism of directives to the early skepticism around React’s JSX or the virtual DOM. The failure modes are different. JSX and the VDOM did not masquerade as language features; they came with explicit imports, provenance, and tooling boundaries. Directives, by contrast, live at the top-level of files and look like the platform, which creates ecosystem expectations and tooling burdens without a shared spec.
 
 ---
 
-### The Bottom Line
+### The bottom line
 
-Framework directives might feel like DX magic today, but the current trend points toward a fractured future, JavaScript dialects defined not by standards, but by vendors.
+Framework directives might feel like DX magic today, but the current trend risks a more fragmented future—dialects defined not by standards, but by tools.
 
-We can do better.
+We can aim for clearer boundaries.
 
-If frameworks want to innovate, they should, but they should also clearly distinguish **framework behavior** from **platform semantics**, instead of blurring that line for short term adoption. The health of the ecosystem depends on it.
+If frameworks want to innovate, they should, but they should also clearly distinguish **framework behavior** from **platform semantics**, instead of blurring that line for short term adoption. Clearer boundaries help the ecosystem.

public/blog-assets/directives-the-new-framework-lock-in/header.png

@@ -1,4 +1,9 @@
-import { Link, notFound, createFileRoute } from '@tanstack/react-router'
+import {
+  Link,
+  notFound,
+  createFileRoute,
+  redirect,
+} from '@tanstack/react-router'
 import { seo } from '~/utils/seo'
 import { Doc } from '~/components/Doc'
 import { PostNotFound } from './blog'
@@ -11,13 +16,23 @@ import { DocContainer } from '~/components/DocContainer'
 import { setResponseHeaders } from '@tanstack/react-start/server'
 import { allPosts } from 'content-collections'
 
+function handleRedirects(docsPath: string) {
+  if (docsPath.includes('directives-the-new-framework-lock-in')) {
+    throw redirect({
+      href: '/blog/directives-and-the-platform-boundary',
+    })
+  }
+}
+
 const fetchBlogPost = createServerFn({ method: 'GET' })
   .inputValidator(z.string().optional())
   .handler(async ({ data: docsPath }) => {
     if (!docsPath) {
       throw new Error('Invalid docs path')
     }
 
+    handleRedirects(docsPath)
+
     const filePath = `src/blog/${docsPath}.md`
 
     const post = allPosts.find((post) => post.slug === docsPath)
@@ -26,11 +41,13 @@ const fetchBlogPost = createServerFn({ method: 'GET' })
       throw notFound()
     }
 
-    setResponseHeaders({
-      'cache-control': 'public, max-age=0, must-revalidate',
-      'cdn-cache-control': 'max-age=300, stale-while-revalidate=300, durable',
-      'Netlify-Vary': 'query=payload',
-    })
+    setResponseHeaders(
+      new Headers({
+        'cache-control': 'public, max-age=0, must-revalidate',
+        'cdn-cache-control': 'max-age=300, stale-while-revalidate=300, durable',
+        'Netlify-Vary': 'query=payload',
+      })
+    )
 
     return {
       title: post.title,