summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorGravatar natemoo-re <natemoo-re@users.noreply.github.com> 2021-06-05 00:42:26 +0000
committerGravatar GitHub Actions <actions@github.com> 2021-06-05 00:42:26 +0000
commit9d3533993045a85c83330173c38149c7e1aac1b2 (patch)
tree9a558239332e304e80e8573a52973c4c0badba39
parent316b4a165256cd5eb07d5c37800464f919d797d4 (diff)
downloadastro-9d3533993045a85c83330173c38149c7e1aac1b2.tar.gz
astro-9d3533993045a85c83330173c38149c7e1aac1b2.tar.zst
astro-9d3533993045a85c83330173c38149c7e1aac1b2.zip
[ci] yarn format
Diffstat (limited to '')
-rw-r--r--docs/renderers.md47
1 files changed, 19 insertions, 28 deletions
diff --git a/docs/renderers.md b/docs/renderers.md
index 678721678..532d4b445 100644
--- a/docs/renderers.md
+++ b/docs/renderers.md
@@ -29,6 +29,7 @@ To enable a new renderer, add the dependency to your project and update the `ren
## Building a new renderer
A simple renderer only needs a few files.
+
```
/renderer-xxx/
├── package.json
@@ -38,6 +39,7 @@ A simple renderer only needs a few files.
```
Two quick notes before we dive into these files individually.
+
1. We'd love for you to contribute any renderer you build directly to the Astro repo. This will allow us to publish it under `@astrojs/renderer-xxx`! Feel free to open a pull request.
2. Your renderer doesn't need to be written in ESM, but it's pretty straightforward! Add `"type": "module"` to your `package.json` file and be sure to [define a valid `export` map](https://nodejs.org/api/packages.html#packages_package_entry_points).
@@ -47,15 +49,13 @@ The main entrypoint of a renderer is a simple JS file which exports a manifest f
Additionally, this entrypoint can optionally define a [Snowpack plugin](https://www.snowpack.dev/guides/plugins) that should be used to load non-JavaScript files.
-
```js
export default {
- name: '@astrojs/renderer-xxx', // the renderer name
- client: './client.js', // relative path to the client entrypoint
- server: './server.js', // relative path to the server entrypoint
- snowpackPlugin: '@snowpack/plugin-xxx', // optional, the name of a snowpack plugin to inject
- snowpackPluginOptions: { example: true }, // optional, any options to be forwarded to the snowpack plugin
-
+ name: '@astrojs/renderer-xxx', // the renderer name
+ client: './client.js', // relative path to the client entrypoint
+ server: './server.js', // relative path to the server entrypoint
+ snowpackPlugin: '@snowpack/plugin-xxx', // optional, the name of a snowpack plugin to inject
+ snowpackPluginOptions: { example: true }, // optional, any options to be forwarded to the snowpack plugin
};
```
@@ -65,16 +65,16 @@ The server entrypoint of a renderer is responsible for checking if a component s
```js
export default {
- // should Component use this renderer?
+ // should Component use this renderer?
check(Component, props, childHTML) {},
// Component => string of static HTML
- renderToStaticMarkup(Component, props, childHTML) {}
-}
+ renderToStaticMarkup(Component, props, childHTML) {},
+};
```
### `check`
-`check` is a function that determines whether a Component should be "claimed" by this renderer.
+`check` is a function that determines whether a Component should be "claimed" by this renderer.
In it's simplest form, it can check for the existence of a flag on Object-based components.
@@ -84,7 +84,7 @@ function check(Component) {
}
```
-In more complex scenarios, like when a Component is a `Function` without any flags, you may need to use `try/catch` to attempt a full render. This result is cached so that it only runs once per-component.
+In more complex scenarios, like when a Component is a `Function` without any flags, you may need to use `try/catch` to attempt a full render. This result is cached so that it only runs once per-component.
```js
function check(Component, props, childHTML) {
@@ -98,7 +98,7 @@ function check(Component, props, childHTML) {
### `renderToStaticMarkup`
-`renderToStaticMarkup` is a function that renders a Component to a static string of HTML. You don't need to worry about hydration
+`renderToStaticMarkup` is a function that renders a Component to a static string of HTML. You don't need to worry about hydration
```js
import { renderToString } from 'xxx';
@@ -117,11 +117,7 @@ import { h, renderToString } from 'xxx';
const Wrapper = ({ value }) => h('astro-fragment', { dangerouslySetInnerHTML: { __html: value } });
function renderToStaticMarkup(Component, props, childHTML) {
- const html = renderToString(
- h(Component, props,
- h(Wrapper, { value: childHTML })
- )
- );
+ const html = renderToString(h(Component, props, h(Wrapper, { value: childHTML })));
return { html };
}
```
@@ -138,8 +134,8 @@ import { hydrate } from 'xxx';
export default (element) => {
return (Component, props, childHTML) => {
hydrate(h(Component, { ...props, innerHTML: childHTML }));
- }
-}
+ };
+};
```
Note that `childHTML` is an HTML string representing this component's children. If your framework does not support rendering HTML directly, you should use the same wrapper component you used for the server entrypoint.
@@ -150,14 +146,9 @@ import SharedWrapper from './SharedWrapper.js';
export default (element) => {
return (Component, props, childHTML) => {
- hydrate(
- h(Component, props,
- h(SharedWrapper, { value: childHTML })
- )
- );
- }
-}
+ hydrate(h(Component, props, h(SharedWrapper, { value: childHTML })));
+ };
+};
```
-
[astro-config]: ./config.md