stnd.build

Illegal server Flag on Action Extension Hook

Error: [ERR_HOOK_SERVER_ON_ACTION] Setting server: true on an action extension hook is a build-time fatal error. Action extensions have no SSR/client split.


The Problem

A module manifest (index.module.js or index.module.ts) configures server: true on an action extension hook (e.g. launcher:action, selection:action, or any hook ending with :action).

// Inside index.module.ts
export default defineModule({
  id: "quick-notes",
  hooks: {
    "launcher:action": {
      handler: "./actions/create.js",
      server: true // Fatal Error: Action extensions cannot be server-only
    }
  }
});

The Why

In the Standard Unified Hooks System:

  1. Action extensions run in the client launcher: Action hooks (like launcher commands or quick palette actions) are dispatched dynamically in the user interface inside the browser.
  2. No SSR/client split for actions: Unlike logic fanout hooks or UI slots that can participate in server-side prerendering, action extensions are purely dynamic client handlers. Declaring server: true causes the bundler to isolate them into the server build where the browser client cannot invoke them.

The Solution

Remove the server: true flag from the action extension registration:

// Compliant
export default defineModule({
  id: "quick-notes",
  hooks: {
    "launcher:action": {
      handler: "./actions/create.js"
    }
  }
});