@enhance/ssr

v4.0.3

Published

5 months ago

Server-side rendering for custom elements with template and slots support

Downloads

600

0High
0Medium
0Low

Enhance SSR

Server side render for Custom Elements.

Enhance enables a web standards based workflow that embraces the platform by supporting Custom Elements and slot syntax.

Install

npm i @enhance/ssr

Usage

import HelloWorld from './path/to/elements/hello-world.mjs'
import enhance from '@enhance/ssr'
const html = enhance({
  elements: {
    'hello-world': HelloWorld
  }
})
console.log(html`<hello-world greeting="Well hi!"></hello-world>`)

An example custom element template for use in Server Side Rendering

Elements are pure functions that are passed an object containing an html function used to expand custom elements and a state object comprised of attrs which are the attributes set on the custom element and a store object that contains application state.

export default function HelloWorld({ html, state }) {
  const { attrs } = state
  const { greeting='Hello World' } = attrs
  return html`
    <style scope="global">
      h1 {
        color: red;
      }
    </style>

    <h1>${greeting}</h1>
  `
}

The rendered output

<head>
  <style scope="global">
    h1 {
      color: red;
    }
  </style>
</head>

<body>
<hello-world>
  <h1>Hello World</h1>
</hello-world>
</body>

Render function

You can also use an object that exposes a render function as your template. The render function will be passed the same arguments { html:function, state:object }.

{
  attrs: [ 'label' ],
  init(el) {
    el.addEventListener('click', el.click)
  },
  render({ html, state }) {
    const { attrs={} } = state
    const { label='Nope' } = attrs
    return html`
    <pre>
      ${JSON.stringify(state)}
    </pre>
    <button>${ label }</button>
    `
  },
  click(e) {
    console.log('CLICKED')
  },
  adopted() {
    console.log('ADOPTED')
  },
  connected() {
    console.log('CONNECTED')
  },
  disconnected() {
    console.log('DISCONNECTED')
  }
}

Use these options objects with the enhance custom element factory

Store

Supply initital state to enhance and it will be passed along in a store object nested inside the state object.

Node

import MyStoreData from './path/to/elements/my-store-data.mjs'
import enhance from '@enhance/ssr'
const html = enhance({
  elements: {
    'my-store-data': MyStoreData
  },
  initialState: { apps: [ { users: [ { name: 'tim', id: 001 }, { name: 'kim', id: 002 } ] } ] }
})
console.log(html`<my-store-data app-index="0" user-index="1"></my-store-data>`)

Element template

export default function MyStoreData({ html, state }) {
  const { attrs, store } = state
  const appIndex = attrs['app-index']
  const userIndex = attrs['user-index']
  const { id='', name='' } = store?.apps?.[appIndex]?.users?.[userIndex] || {}
  return `
<div>
  <h1>${name}</h1>
  <h1>${id}</h1>
</div>
  `
}

The store is used to pass state to all components in the tree.

Slots

Enhance supports the use of slots in your custom element templates.

export default function MyParagraph({ html }) {
  return html`
<p>
  <slot name="my-text">
    My default text
  </slot>
</p>
  `
}

You can override the default text by adding a slot attribute with a value that matches the slot name you want to replace.

<my-paragraph>
  <span slot="my-text">Let's have some different text!</span>
</my-paragraph>

Unnamed slots

Enhance supports unnamed slots for when you want to create a container element for all non-slotted child nodes.

export default function MyButton({ html }) {
  return html`
<button>
  <slot>Submit</slot>
</button>
  `
}

<my-button></my-button>

<my-button>Save</my-button>

Transforms

Enhance supports the inclusion of script and style transform functions. You add a function to the array of scriptTransforms and/or styleTransforms and are able to transform the contents however you wish, just return your desired output.

import enhance from '@enhance/ssr'

const html = enhance({
  elements: {
    'my-transform-script': MyTransformScript
  },
  scriptTransforms: [
    function({ attrs, raw }) {
      // raw is the raw text from inside the script tag
      // attrs are the attributes from the script tag
      return raw + ' yolo'
    }
  ],
  styleTransforms: [
    function({ attrs, raw }) {
      // raw is the raw text from inside the style tag
      // attrs are the attributes from the style tag
      const { scope } = attrs
      return `
      /* Scope: ${ scope } */
      ${ raw }
      `
    }
  ]
})

function MyTransformScript({ html }) {
  return html`
<style scope="component">
  :host {
    display: block;
  }
</style>
<h1>My Transform Script</h1>
<script type=module>
  class MyTransformScript extends HTMLElement {
    constructor() {
      super()
    }
  }
  customElements.define('my-transform-script', MyTransformScript)
</script>
  `
}

console.log(html`<my-transform-script></my-transform-script>`)

`context`

There are times you will need to pass state to nested child custom elements. To avoid the tedium of passing attributes through multiple levels of nested elements Enhance SSR supplies a context object to add state to.

Parent sets context

export default function MyContextParent({ html, state }) {
  const { attrs, context } = state
  const { message } = attrs
  context.message = message

  return html`
    <slot></slot>
  `
}

Child retrieves state from parent supplied context

export default function MyContextChild({ html, state }) {
  const { context } = state
  const { message } = context
  return html`
    <span>${ message }</span>
  `
}

Authoring

<my-context-parent message="hmmm">
  <div>
    <span>
      <my-context-child></my-context-child>
    </span>
  </div>
</my-context-parent>

`instanceID`

When rendering custom elements from a single template there are times where you may need to target a specific instance. The instanceID is passed in the state object.

export default function MyInstanceID({ html, state }) {
  const { instanceID='' } = state

  return html`
<p>${instanceID}</p>
  `
}

`bodyContent`

Enhance SSR outputs an entire valid HTML page but you can pass bodyContent: true to get just the content of the <body> element. This can be useful for when you want to isolate the HTML output to just the Custom Element(s) you are authoring.

const html = enhance({
  bodyContent: true,
  elements: {
    'my-paragraph': MyParagraph,
  }
})
const output = html`
<my-paragraph></my-paragraph>
  `

Integration with `<html>`, `<head>`, and `<body>` elements

Enhance SSR will intelligently merge its rendered <html>, <head>, and <body> elements with any that you provide to it (unless you choose to use the bodyContent: true option).

For example:

const html = enhance({
  elements: {
    'my-content': MyContent,
  }
})

html`
<!DOCTYPE html>
<html lang="en">
  <head>
    <title>My Website</title>
  </head>
  <body class="foo bar">
    <my-content></my-content>
  </body>
</html>
`

P.S. Enhance works really well with Begin.

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme