Server Functions Don't Exist (It Matters)

Server Functions: Syntactic Sugar or Standard API?

Key Concepts:

• Server Functions: Functions that appear to be invoked on the client-side but execute on the server.
• Syntactic Sugar: A feature that makes code easier to read and write without changing its underlying functionality.
• Bundler: A tool that combines JavaScript and other assets into optimized bundles for deployment.
• API Endpoint: A specific URL that a server exposes to allow clients to access its resources and functionality.
• TRPC: A TypeScript library for building end-to-end type-safe APIs.
• GraphQL: A query language for APIs and a runtime for fulfilling those queries with existing data.
• Isomorphic Frameworks: Frameworks where UI code can run on both the server and the client.

1. What are Server Functions?

• Server functions are a feature in modern full-stack frameworks (Next.js, Tanstack Start, Solid Start, Qwik) that allow developers to write functions that execute on the server while being invoked from the client-side code.
• Example: addNumbers function with use server directive in Next.js. Invoked on the client, but the actual addition happens on the server.
• Demonstration: A Next.js page with an input form. Submitting the form triggers the addNumbers server function, which returns the sum. The network panel shows a request to the server.
• Example of server-side only functionality: getFiles function retrieves files from the server's file system, which is impossible to do directly from the client-side browser environment.

2. How Server Functions are Implemented (Under the Hood)

• Server functions are not a native web platform feature. There is no built-in "server function" concept in browsers or web standards.
• They are a form of syntactic sugar provided by frameworks.
• The framework's bundler creates two bundles: one for the server and one for the client.
• UI code (in isomorphic frameworks) goes into both bundles for server-side rendering.
• API code and the body of server functions go into the server bundle.
• The bundler generates an API endpoint (e.g., a GET handler on a specific route) that executes the server function.
• The bundler also creates client-side code that makes a fetch request to that generated API endpoint.
• From the developer's perspective, they are simply calling a function (getFiles) without needing to worry about the underlying client-server communication.

3. Server Functions in Action: Tanstack Start Example

• Demonstration using Tanstack Start: An add function is invoked. The network panel shows a fetch request (a POST request by default) to a framework-controlled URL.
• Tanstack Start allows specifying the HTTP method (e.g., POST) when defining the server function. This is a distinguishing feature.
• The payload is typically JSON, containing the input data.
• Overriding fetch with a debugger statement reveals the call stack: onClick -> Tanstack Start middleware -> serverFunctionFetcher -> fetch -> generated API endpoint.
• The serverFunctionFetcher formats the request for the client.

4. Trade-offs of Server Functions

• Lack of Control over URL: The framework dictates the URL for the API endpoint.
• Lack of Control over HTTP Method: Some frameworks (like Next.js) only allow POST requests. Tanstack Start allows specifying the method.
• Lack of Control over Input/Output Format: The framework determines the data format (e.g., JSON, custom formats).
• Not a Standard: Server functions are framework-specific, unlike established API standards.

5. Comparison of Server Function Implementations (Next.js, Qwik, Solid Start)

• Next.js:
  • HTTP Method: POST only.
  • Payload: JSON array of arguments.
  • Response: Flight data (not JSON).
• Qwik:
  • HTTP Method: POST.
  • Payload: JSON (format unclear).
  • Response: application/quick+json (custom format).
• Solid Start:
  • HTTP Method: POST.
  • Payload: JSON (data fields).
  • Response: text/javascript (JSON).

6. Alternatives to Server Functions

• Custom API Endpoints: Developers have full control over the URL, HTTP method, input/output formats.
• TRPC: Allows defining a prefix for the URL (/trpc or /api/trpc), but the rest is managed by TRPC. Uses JSON RPC.
• GraphQL: Developers control the URL and can choose POST or GET (though POST is recommended). Input is GraphQL, output is JSON.

7. Decision Flowchart: When to Use Server Functions

1. Does your API have external clients? (e.g., mobile app, third-party integrations)
   • Yes: Use a standards-based API (GraphQL, TRPC, REST).
   • No: Server functions or custom APIs are acceptable.
2. Does the server function implementation support your requirements? (e.g., HTTP method control, desired input/output formats)
   • Yes: Server functions are a viable option.
   • No: Consider custom APIs or a different framework.

8. Synthesis/Conclusion

Server functions are a convenient form of syntactic sugar that simplifies client-server communication within a full-stack framework. However, they come with trade-offs, including a lack of control over URLs, HTTP methods, and data formats. The key decision point is whether the API needs to be exposed to external clients. If so, a standards-based API like GraphQL or TRPC is generally a better choice. If the API is only used within the framework's UI, server functions can be a suitable option, provided that the framework's implementation meets the application's specific requirements.