[Feature] include a serverHandle export

[paul-vd]

Proposal: Introducing export const serverHandle in Remix

Background

In Remix, exporting a handle allows developers to create application conventions that can be utilized with the useMatches hook, providing a flexible way to attach metadata or methods to routes. However, this capability currently does not differentiate between server-side and client-side code, potentially leading to unintended exposure of server-only logic in the client bundle. This poses a problem, especially when handles are used for server-side logic such as accessing databases or APIs that should not be part of the client-side codebase.

A notable example can be found in Kent C. Dodds's epic-stack, where export const handle is used for generating sitemap entries. This server-side logic, ideally, should not be included in the client bundle to prevent unnecessary code exposure and potential errors.

To address this limitation, this proposal suggests introducing a new export const serverHandle that follows the same removal principle as other server-only exports like loader and action, ensuring that any server-side logic defined within serverHandle is stripped from the client bundle.

Use Case

The primary use case for export const serverHandle is to allow developers to define server-side logic associated with routes without worrying about this logic leaking into the client-side bundle. This is particularly useful for:

• Generating sitemap entries
• Defining server-side data fetching methods
• Implementing server-side authorization checks
• Custom server-side handling or route-specific logic

By ensuring that serverHandle is removed from the client bundle, we can maintain a clear separation of concerns between client and server, optimize bundle size, and enhance application security.

Proposal Details

Introduction of serverHandle

// Example of using serverHandle for server-side logic
export const serverHandle = {
  getSitemapEntries: async request => {
    const entries = await someServerSideOperation(request);
    return entries.map(entry => ({
      route: `/some-route/${entry.id}`,
      priority: entry.priority,
    }));
  },
};

For implementation details on how the handle is used in this particular case please see @balavishnuvj/remix-seo

This serverHandle would be automatically stripped from the client bundle, similar to how export const loader and export const action are currently handled. This ensures that server-side code is not exposed or shipped to the client, aligning with best practices for security and performance.

Integration with SERVER_ONLY_ROUTE_EXPORTS

To implement this feature, serverHandle would be added to the list of SERVER_ONLY_ROUTE_EXPORTS within Remix's build process. This would automatically exclude serverHandle from the client bundle during the build phase, ensuring that server-side logic remains server-side.

Conclusion

The introduction of export const serverHandle in Remix offers a robust solution for defining server-side logic associated with routes, enhancing code organization, security, and performance by ensuring server-side code is not included in the client bundle. This proposal aims to address the current limitations and provide a more flexible and secure way of handling server-side logic in Remix applications.

[kiliman]

Now that Remix has moved to Vite, you can do a similar thing with serverOnly$ from vite-env-only. In the client bundle, the expression would evaluate to undefined

import { serverOnly$ } form 'vite-env-only'

export const handle = {
  getSiteMapEntries: serverOnly$(async () => {})
}

[paul-vd]

Yea that would have been good, but as a library distributor it will not work, for example, if I try to create a helper function which is server from my package @acme/remix-seo

import { serverOnly$ } from "vite-env-only";
import type { SEOHandle } from "./types";

interface Handle extends SEOHandle {
  [key: string]: any;
}

export const createSeoHandle = (options: Handle) => {
  if (options.getSitemapEntries) {
    return {
      ...options,
      getSitemapEntries: serverOnly$(options.getSitemapEntries),
    };
  }

  return options;
};

and then use it within a app via the distributed package, for example:

import { createSeoHandle } from "@acme/remix-seo"

export const handle = createSeoHandle({
  getSitemapEntries: async request => {
    const entries = await someServerSideOperation(request);
    return entries.map(entry => ({
      route: `/some-route/${entry.id}`,
      priority: entry.priority,
    }));
  },
});

it does not correctly remove it.

[paul-vd]

Although the code is removed from the client side, it seems like the imports used within the function are not removed, in my example the someServerSideOperation, here is an example of the result of vite-env-only transformation

// Before transformation
export const createSeoHandle = (options) => {
  if (options.getSitemapEntries) {
    const getSitemapEntries = serverOnly$(options.getSitemapEntries);
    if (getSitemapEntries) {
      return {
        ...options,
        getSitemapEntries
      };
    }
  }
  return options;
};

// After transformation
export const createSeoHandle = options => {
  if (options.getSitemapEntries) {
    const getSitemapEntries = undefined;
    if (getSitemapEntries) {
      return {
        ...options,
        getSitemapEntries
      };
    }
  }
  return options;
};