|
| 1 | +# Next.js Server Functions Visualizer |
| 2 | + |
| 3 | +> A VS Code extension that visualizes the “definitions” and “call sites” of Server Functions (`'use server'`) to help you understand them quickly in the editor. |
| 4 | +
|
| 5 | +<img src="./assets/screenshot.png" alt="Screenshot" width="800" /> |
| 6 | + |
| 7 | +## Motivation |
| 8 | +Server Functions are transformed into framework‑managed endpoints (POST), which makes the network boundary implicit and hard to see in code. By visualizing these definitions and call sites directly in the editor, this extension aims to improve readability and reduce review friction. |
| 9 | + |
| 10 | +## Features |
| 11 | +- Highlight definitions (blue‑purple line background) |
| 12 | + - Highlights the entire line range of the server function body |
| 13 | + - Shows 🌐 inline at the end of the line that starts the block “{” |
| 14 | +- Highlight call sites (expression range) |
| 15 | + - Blue‑purple background + solid underline on the same range + 🚪 inline at the end |
| 16 | + - Patterns: direct calls (`id(...)`/`obj.id(...)`), `<form action={...}>`/`formAction`, `startTransition(() => id(...))`, `useActionState(id, ...)` |
| 17 | +- Auto filtering to reduce false positives |
| 18 | + - Only identifiers that are callables from imports or declared in the same file are considered |
| 19 | + - Uses the TypeScript Language Service to resolve definitions and decorates only when they match a Server Function |
| 20 | + |
| 21 | +## Usage |
| 22 | +1. Install this extension and open a Next.js (React Server Components) project |
| 23 | +2. Open any `.ts/.tsx` file and visualization activates automatically (JS/JSX are not supported) |
| 24 | +3. Server Function definitions are highlighted with a blue‑purple line background; call sites are highlighted by expression range |
| 25 | + |
| 26 | +Tips |
| 27 | +- Definitions target functions that satisfy both `'use server'` and `async` |
| 28 | +- Also supports builder patterns (e.g., `createServerAction(async () => {...})`) and JSX inline `action={async () => {'use server'}}` |
| 29 | + |
| 30 | +## Settings |
| 31 | +You can tweak the background intensity and theme colors. |
| 32 | + |
| 33 | +```jsonc |
| 34 | +// Example (settings.json) |
| 35 | +{ |
| 36 | + "nextjs-server-functions-visualizer.highlight.definition.tintLight": "rgba(138, 99, 255, 0.14)", |
| 37 | + "nextjs-server-functions-visualizer.highlight.definition.tintDark": "rgba(138, 99, 255, 0.18)", |
| 38 | + "nextjs-server-functions-visualizer.highlight.definition.tintHighContrast": "rgba(138, 99, 255, 0.22)", |
| 39 | + "nextjs-server-functions-visualizer.highlight.call.tintLight": "rgba(118, 129, 255, 0.14)", |
| 40 | + "nextjs-server-functions-visualizer.highlight.call.tintDark": "rgba(118, 129, 255, 0.18)", |
| 41 | + "nextjs-server-functions-visualizer.highlight.call.tintHighContrast": "rgba(118, 129, 255, 0.22)", |
| 42 | + "nextjs-server-functions-visualizer.highlight.call.underlineColorLight": "rgba(118, 129, 255, 0.85)", |
| 43 | + "nextjs-server-functions-visualizer.highlight.call.underlineColorDark": "rgba(118, 129, 255, 0.85)", |
| 44 | + "nextjs-server-functions-visualizer.highlight.call.underlineColorHighContrast": "rgba(118, 129, 255, 0.9)" |
| 45 | +} |
| 46 | +``` |
| 47 | + |
| 48 | +## Supported Detections |
| 49 | +- Definitions (`'use server'` + async) |
| 50 | + - `export async function foo() {}` / `export default async function ...` |
| 51 | + - `export const x = async () => {}` / `async function() {}` |
| 52 | + - Async function literals inside initializers of builder patterns |
| 53 | + - JSX inline: `action={async () => {'use server'}}` |
| 54 | +- Call sites |
| 55 | + - Direct: `id(...)`, `obj.id(...)` |
| 56 | + - JSX: `<form action={...}>`, `formAction={...}` |
| 57 | + - `startTransition(() => id(...))` |
| 58 | + - `useActionState(id, ...)` |
| 59 | + |
| 60 | +## Known Limitations |
| 61 | +- Namespace imports: single-level calls like `ns.action()` are supported; multi-level chains like `ns.group.action()` are not. |
| 62 | + - Element access (`obj['action']()`) is not supported. |
| 63 | +- Does not track indirect calls (via props/HOF) or `bind/apply` |
| 64 | +- Async functions that don’t satisfy `'use server'` are not treated as definitions |
| 65 | + |
| 66 | +## Troubleshooting |
| 67 | +- Expected locations aren’t highlighted |
| 68 | + - Ensure the function meets `'use server'` + `async` |
| 69 | + - Ensure it’s declared as an imported or same‑file function |
| 70 | + - Use “Go to Definition” (F12) to check if it resolves to the intended Server Function |
| 71 | +- If decorations conflict with other extensions, adjust background/underline intensity in settings |
| 72 | + |
| 73 | +## How It Works (High level) |
| 74 | +- Extracts definition and call candidates via AST (TypeScript Compiler API) |
| 75 | +- Pre‑filters imports/local declarations to exclude global APIs (e.g., `alert`/`console`) |
| 76 | +- Uses VS Code’s TypeScript Language Service to resolve definitions and decorate only when they match a Server Function (identifier/body range) |
| 77 | + |
| 78 | +## License / Contributions |
| 79 | +- Issues/PRs welcome. Proposals for UI/colors and unsupported patterns (e.g., namespace import/element access) are appreciated. |
| 80 | + |
| 81 | +## Related |
| 82 | +- Next.js Component Boundary Visualizer: https://github.com/makotot/vscode-nextjs-component-boundary-visualizer — A VS Code extension that visualizes component execution environments (client/server) via the 'use client' directive. |
0 commit comments