Skip to content

Latest commit

 

History

History
304 lines (225 loc) · 12.2 KB

README.md

File metadata and controls

304 lines (225 loc) · 12.2 KB
Raw

Prerender Macro

Bun plugin to prerender JSX components using a kind of macro.

Work in every JSX Framework.

At a glance

prerender-macro plugin allows Partial Prerendering (PPR) to make hybrid pages between dynamic and static components, avoiding the rendering in runtime of the static ones, this rendering is done in build-time thanks to Bun's macros.

import StaticComponent from "@/static-component" with { type: "prerender" };
import DynamicComponent from "@/dynamic-component";

// ...
return (
  <>
    <StaticComponent foo="bar" />
    <DynamicComponent />
  </>
);

In this way:

  • The bundle is smaller because instead of carrying all the JS it only carries the prerendered HTML.
  • The runtime speed of rendering is faster, it only has to render the dynamic components.
React example

How does it work?

This plugin transforms the previous code into this code:

import { prerender } from "prerender-macro/prerender" with { "type": "macro" };
import DynamicComponent from "@/dynamic-component";

// ...
return (
  <>
    {prerender({
      componentPath: "@/static-component",
      componentModuleName: "default",
      componentProps: { foo: "bar" },
    })}
    <DynamicComponent />
  </>
);

And pass it back through the Bun transpiler to run the macro. Bun macro together with the prerender helper takes care of converting the component to html string in build-time. This way it will only be necessary in runtime to make the rendering of those dynamic.

Important

Macros can accept component properties, but only in limited cases. The value must be statically known. For more info take a look at the Bun Macros Arguments documentation.

Quick start

Install

bun install prerender-macro

Use it in Bun.build

To use it you have to set the prerenderConfigPath (mandatory), which is the path where you have the configuration export, if it is in the same file you can use import.meta.url.

import prerenderMacroPlugin from "prerender-macro";

// The configuration should be adapted to the framework that you are using:
export const prerenderConfig = {
  render: (Component, props) => /* mandatory */,
  postRender: () => /* optional */
};

Bun.build({
  plugins: [prerenderMacroPlugin({ prerenderConfigPath: import.meta.url })],
  entrypoints,
  outdir,
  root,
});

Configuration

The prerender-macro plugin needs this mandatory configuration to work:

Parameter Description Mandatory
prerenderConfigPath String path of the file with the prerenderConfig named export true

The configuration can be in another file, but it must have the named export prerenderConfig.

It is necessary to do it this way because this configuration will be executed when doing the prerender inside a Bun macro, and at this point we cannot pass it from the plugin because it would need to be serialized, so it is better that you directly access it.

The prerenderConfig named export needs this mandatory configuration to work:

Parameter Description Mandatory Can be async
render Function to render the component on your framework (AOT) true yes
postRender Function to make a post rendering in runtime (JIT) false no

Note

It is not necessary to indicate the jsx-runtime, it will work with the one you have and it can connect with any JSX framework.

Configuration examples in different frameworks

Framework Render ahead of time Inject ahead of time Preserves the HTML structure Demo
✅ ✅ ✅ 🔗
✅ ❌ ❌ 🔗
✅ ✅ ❌ 🔗
✅ ✅ ✅ 🔗

Tip

👉 Add your framework

Brisa (experimental)

Configuration example:

import prerenderMacroPlugin, { type PrerenderConfig } from "prerender-macro";
import { dangerHTML } from "brisa";
import { renderToString } from "brisa/server";

export const prerenderConfig = {
  render: async (Component, props) =>
    dangerHTML(await renderToString(<Component {...props} />)),
} satisfies PrerenderConfig;

export const plugin = prerenderMacroPlugin({
  prerenderConfigPath: import.meta.url,
});

Note

Brisa elements can be seamlessly coerced with Bun's AST and everything can be done AOT without having to use a postRender.

Note

Brisa does not add extra nodes in the HTML, so it is a prerender of the real component, without modifying its structure.

Warning

Brisa is an experimental framework that we are building.

Brisa is not yet public but it will be in the next months. If you want to be updated, subscribe to my blog newsletter.

React

For React components, since React does not have a built-in function for injecting HTML strings directly into JSX, you need to use dangerouslySetInnerHTML. This allows you to bypass React's default behavior and inject raw HTML into the DOM.

Configuration example:

import prerenderMacroPlugin, { type PrerenderConfig } from "prerender-macro";
import { renderToString } from "react-dom/server";

export const prerenderConfig = {
  render: async (Component, props) => {
    return renderToString(<Component {...props} />);
  },
  postRender: (htmlString) => (
    <div dangerouslySetInnerHTML={{ __html: htmlString }} />
  ),
} satisfies PrerenderConfig;

export const plugin = prerenderMacroPlugin({
  prerenderConfigPath: import.meta.url,
});

Important

React elements have the $$typeof symbol and therefore cannot coerce to Bun's AST. This is why it is necessary to do the postRender in JIT.

Caution

Additional <div> Nodes: Using dangerouslySetInnerHTML to inject HTML strings into JSX components results in the creation of an additional <div> node for each injection, which may affect the structure of your rendered output. Unlike Brisa, where this issue is avoided, the extra <div> nodes can lead to unexpected layout changes or styling issues.

Preact

For Preact components, since Preact does not have a built-in function for injecting HTML strings directly into JSX, you need to use dangerouslySetInnerHTML. This allows you to bypass Preact's default behavior and inject raw HTML into the DOM.

Configuration example:

import prerenderMacroPlugin, { type PrerenderConfig } from "prerender-macro";
import { render } from "preact-render-to-string";

export const prerenderConfig = {
  render: async (Component, props) => {
    return (
      <div
        dangerouslySetInnerHTML={{ __html: render(<Component {...props} />) }}
      />
    );
  },
} satisfies PrerenderConfig;

export const plugin = prerenderMacroPlugin({
  prerenderConfigPath: import.meta.url,
});

Note

Preact elements can be seamlessly coerced with Bun's AST and everything can be done AOT without having to use a postRender.

Caution

Additional <div> Nodes: Using dangerouslySetInnerHTML attribute to inject HTML strings into JSX components results in the creation of an additional <div> node for each injection, which may affect the structure of your rendered output. Unlike Brisa, where this issue is avoided, the extra <div> nodes can lead to unexpected layout changes or styling issues.

Kitajs/html

Configuration example:

import { createElement } from "@kitajs/html";
import prerenderMacroPlugin, { type PrerenderConfig } from "prerender-macro";

export const prerenderConfig = {
  render: createElement,
} satisfies PrerenderConfig;

export const plugin = prerenderMacroPlugin({
  prerenderConfigPath: import.meta.url,
});

Note

Kitajs/html elements can be seamlessly coerced with Bun's AST and everything can be done AOT without having to use a postRender.

Note

Kitajs/html does not add extra nodes in the HTML, so it is a prerender of the real component, without modifying its structure.

Add your framework example

This project is open-source and totally open for you to contribute by adding the JSX framework you use, I'm sure it can help a lot of people.

To add your framework you have to:

  • Fork & clone
  • Create a folder inside tests with your framework that is a copy of some other framework. The same for examples.
  • Make the changes and adapt the example and tests to your framework
  • Update the package.json scripts to add your framework
  • Update the README.md adding the documentation of your framework.
  • Open a PR with the changes.

Contributing

See Contributing Guide and please follow our Code of Conduct.

License

MIT