swtl

> Check out the swtl-starter app

A Service Worker Templating Language (swtl) for component-like templating in service workers. Streams templates to the browser as they're being parsed, and handles rendering iterables/Responses in templates by default. Also supports SSR/SWSRing custom elements, with a pluggable custom element renderer system.

Runs in Service Workers, but can also be used in Node, or other server-side JS environments.

``bash
npm i swtl
`

Example

`js
import { html, Router, CacheFirst } from 'swtl';
import { BreadCrumbs } from './BreadCrumbs.js'

function HtmlPage({children, title}) {
return html${children};
}

function Footer() {
return html

;
}

const router = new Router({
routes: [
{
path: '/',
response: ({url, params, query, request}) => html
<${HtmlPage} title="Home">

Home

${fetch('./some-partial.html')}
${caches.match('./another-partial.html')}

${['foo', 'bar', 'baz'].map(i => html
• ${i}
)}

<${CacheFirst} file="./some-file.html"/>
<${Footer}/>


},
]
});

self.addEventListener('fetch', (event) => {
if (event.request.mode === 'navigate') {
event.respondWith(router.handleRequest(event.request));
}
});
`

Router

Uses URLPattern internally for matching the paths. The response callback gets passed the native Request object, as well as any route params or query params.

`js
import { html, Router } from 'swtl';

const router = new Router({
routes: [
{
path: '/',
response: () => html

Home


},
{
path: '/:foo',
response: ({params}) => html

${params.foo}


},
{
path: '/:foo/:bar',
response: ({params}) => html

${params.foo}/${params.bar}


},
{
path: '/:foo/:bar',
response: ({url, params, query, request}) => html

${params.foo}/${params.bar}

},
]
});

self.addEventListener('fetch', (event) => {
if (event.request.mode === 'navigate') {
event.respondWith(router.handleRequest(event.request));
}
});
`

$3

You can also specify a baseHref, for example if your app is served under a specific base route, like https://my-app.com/foo/bar/:

`js
const router = new Router({
baseHref: '/foo/bar/',
routes: [
{
// The url will be: https://my-app.com/foo/bar/
path: '',
response: () => html<${Home}/>
},
{
// The url will be: https://my-app.com/foo/bar/users/1
path: 'users/:id',
response: ({params}) => html<${User} id=${params.id}/>
}
]
});
`

Note that you also have the set the base tag in your HTML:
`html

`

$3

You can also provide a fallback in case no routes are matched. If you don't provide a fallback, the request will not be handled by the service worker, and go through to the network.

`js
const router = new Router({
routes: [
{
path: '/',
response: () => html<${Home}/>
}
],
fallback: ({query, request}) => html<${NotFound}/>
});
`

$3

You can also provide plugins. You can add global plugins that will run for every route, or add plugins for specific routes only. If you return a Response from a plugin, the router will return that response to the browser instead of your response function.

`js
import { Router, html, HtmlResponse } from 'swtl';

const logger = {
name: 'logger-plugin',
beforeResponse({request}) {
console.log(Request made to ${request.url});
}
}

const router = new Router({
/**
* These plugins run for all routes
*/
plugins: [logger],
routes: [
{
path: '/',
response: () => html<${Home}/>,
/**
* These plugins run for this route only
*/
plugins: [
{
name: 'my-plugin',
async beforeResponse({url, query, params, request}) {
console.log('Running [my-plugin]!');

/**
* Based on conditions we can return a different response
*/
if (query.foo === 'bar') {
return new Response('bar');
}

if (query.bar === 'foo') {
/**
* Returns a Response with a stream of the html template as body for convenience
*/
return new HtmlResponse(html<${Bar}/>);
}

/**
* We can also use plugins for redirects
*/
if (params.user === 'frank') {
return Response.redirect('/foo');
}
}
}
]
}
]
});
`

$3

You can also provide options, the options will be passed to the Response that handleRequest returns:

`js
const router = new Router({
routes: [
{
path: '/foo',
response: () => htmlfoo,
options: {
headers: {
'content-type': 'text/xml'
}
}
}
],
});
`

Html

$3

`js
/**
* Children
*/
function Heading({children}) {
return html

${children}

;
}

html<${Heading}>Hello world

/**
* Self-closing
*/
function Heading() {
return html

Hello world

;
}

html<${Heading}/>

/**
* Properties and spread
*/
function MyComponent({foo, title, baz, qux, bool}) {
return html

${title}

;
}

const object = {
baz: 'hello',
qux: 'world',
}

html<${MyComponent} title="hello" foo=${1} ...${object} bool/>;

/**
* Note that quotes are optional when using expressions, the following is also fine:
* foo="${1}"
* ...bar="${object}"
*/
`

$3

In addition to children, SWTL also supports slots, for when you need a little more flexibility for composition. You can use slots like so:

`js
import { Slot } from 'swtl';

function Parent({slots}) {
return html

${slots.default}

${slots.bar}

${slots.baz}

;
}

html<${Parent}>
<${Slot}>Foo
<${Slot} name="bar">Bar
<${Slot} name="baz">Baz

// Output:
//

Foo

//

Bar

//

Baz

`

$3

You can also use iterables or Responses in your templates directly

`js
const stream = new ReadableStream({
start(controller) {
['a', 'b', 'c'].forEach(s => controller.enqueue(s));
controller.close();
}
});

function* gen() {
yield '

1

';
yield '

2

';
yield '

3

';
}

const template = html

${fetch('/some.html')}
${caches.match('/some.html')}
${new Response('hello')}
${stream}

${gen()}

;
`

Strategies

We also ship some built-in components to declaratively let you request files.

`js
import { NetworkFirst, NetworkOnly, CacheFirst, CacheOnly, html } from 'swtl';

const template = html

Hello world

<${NetworkFirst} file="./some-file.html"/>
<${NetworkOnly} file="./some-file.html"/>
<${CacheFirst} file="./some-file.html"/>
<${CacheOnly} file="./some-file.html"/>

;
`

You can also provide a fallback:

`js
const template = html
<${NetworkFirst} file="./some-file.html">

<${NetworkOnly} file="./some-file.html">

<${CacheFirst} file="./some-file.html">

<${CacheOnly} file="./some-file.html">

;
`

If you're using SWTL in a more SPA-like PWA app, you can also use the following strategies:

`js
import { networkFirst, networkOnly, cacheFirst, cacheOnly, staleWhileRevalidate } from 'swtl';

import { Router } from 'swtl';

const router = new Router({
routes: [
{
path: '/images/*.svg',
response: cacheFirst
},
]
});

self.addEventListener('fetch', (event) => {
event.respondWith(router.handleRequest(event.request));
});
`

Out of order streaming

For out of order streaming you can use the built-in Await component and provide a promise property:

`js
import { Await, when } from 'swtl';

html
<${Await} promise=${() => fetch('/api/foo').then(r => r.json())}>
${(status, data, error) => html


Fetching data


${when(status.pending, () => html

Loading...

)}
${when(status.error, () => html

Failed to fetch data

)}
${when(status.success, () => html

${data.map(i => html
• ${i}
)}

)}
}


`

Render

The Router streams responses to the browser via the render function internally in handleRequest:

`js
import { render } from 'swtl';

for await (const chunk of render(html

${1}

)) {
console.log(chunk);
}
`

But we also export a renderToString:

`js
import { renderToString } from 'swtl';

const result = await renderToString(html

${1}

);
`

SSR/SWSR

Swtl also supports SSR (Server Side Rendering) or SWSR (Service Worker Side Rendering) of custom elements via a pluggable custom element renderer system. Here's an example:

`js
import { litRenderer } from '@swtl/lit';

const router = new Router({
customElementRenderers = [litRenderer]
// etc
})
`

> Note that customElementRenderers are order-sensitive; customElementRenderers will do a match check to see if the current renderer should or should not render the given custom element. If this match check returns false, it will defer to the next renderer (if any) or to the default renderer, which just outputs the custom element as-is, and essentially _doesn't_ SSR/SWSR it. You don't have to provide the default renderer manually; it gets added for you.

You can then use (in this case) LitElements in your SWTL template, e.g.:

`js
html
`

And the LitElement will get rendered via @lit-labs/ssr with Declarative Shadow Dom. If you want to hydrate your component, you'll have to explicitly load the client-side code for your component:

`js
html