@aller/svelte-components

This repository contains svelte components that can be used in other projects. You should consider creating a svelte components if you need a component that requires a lot of clientside logic. If you want to create a component that can be ESI'd in without a lot of clientside logic, take a look at the esi-components project in wolverine-frontend

Run

1. yarn

2. yarn dev

3. localhost:3000/render/example

Making changes

This project serves content both through a NPM package and an express server. For your changes to be available everywhere, follow these steps

1. Make your changes or create your component (make sure to follow the required structure)
2. Bump the version in package.json
3. Make a PR and merge to master
4. Clear cache for your component, the cache channel will be svelte-components-yourComponentName. You can do this through the admin panel in janitr (https://github.com/dbmedialab/janitr)
5. Run yarn build locally, and run npm publish --access public to publish your changes to NPM. (Make sure you are logged in with npm login and that your NPM user is a part of the Aller org)
6. Update the @aller/svelte-components version in the repositories that uses it.

How to use

The simplest way of using these components is to ESI them in. <esi:include src="/app/svelte-components/render/example"></esi:include>. This will return server side rendered markup with script tags that fetches the clientside bundle. Add the query parameter ssrModernClientBundle if you want the modern client bundle's code to be inserted on the server instead of downloading it clientside. Note that this will force legacy browsers to download both the modern and legacy bundles.

NPM package

Some projects, like wolverine-frontend-xavier, can not use ESIs. In those cases, we can add the @aller/svelte-components package which exposes an async function that server side renders the svelte components. The package includes both the renderComponent and renderComponentAsync function. Note that renderComponentAsync will not work inside of a React component that is rendered on the server because it returns a promise.

Here is an example of how this can be used server side with express

import { renderComponentAsync } from '@aller/svelte-components'

const componentMarkup = await renderComponentAsync({ name: 'example', ssrModernClientBundle: true })

res.send(componentMarkup)

Server side with React

import renderComponent from '@aller/svelte-components'

const componentMarkup = renderComponentAsync({ name: 'example' })

return (
  <div
    dangerouslySetInnerHTML={{ __html: componentMarkup }}
  />
)

renderComponent() arguments

parameter	type	description
name	String	Name of the component you want to render
ssrModernClientBundle (Only with renderComponentAsync)	Boolean	Will insert the modern client bundle's code on the server instead of downloading it clientside. For modern browsers the component will be interactive almost immediately, but legacy browsers will now downlaod both the modern and legacy bundles. Consider the size of the client bundle before using this. Only works in node, will not work in Next.JS.
props	Object	Props sent to the Svelte component
bundlePath	String	Path to the bundle, do not change when importing from package

Structure

There is a specific structure and naming convention that needs to be follow for this to work properly right now. This can hopefully be refactored at some point to make it a bit easier. If you just want a starting point, copy /src/example.

Each svelte components needs to be placed within it's own folder in /src. The component's folder should only contain a .svelte and .js file with the same name as the component folder. The .js file's target also needs to inlude the name of the component target: document.getElementById("svelte-app-NAME_OF_COMPONENT"). All other files should be within subfolders, and there is no specific structure that is required here. For example:

src
|
└───myNewComponent
│   │   myNewComponent.js (with target id 'svelte-app-myNewComponent')
│   │   myNewComponent.svelte
│   │
│   └───components
│       │   Button.svelte
│       │   List.svelte
│       │   ...
│   └───store
│       │   store.js
│       │   ...

How it works

So far this works by making webpack create three different bundles. One for the server, one for modern browsers and one for legacy browsers.

• The server bundle is used to server side render the svelte component. The bundle is created by targeting the main .svelte file directly (src/yourComponent/yourComponent.svelte)

• The modern and legacy bundle are used clientside. These bundles are created by targeting each components main .js file (src/yourComponent/yourComponent.js). The legacy bundle is transpiled and polyfilled to support IE11

The server will respond with styled markup and a script tag that will download the bundle. Once the bundle is downloaded, the component will hydrate and become interactive

IE11 Support

We create two differende bundles for the client because we would like to avoid serving a heavily transpiled and polyfilled bundle to browser's that does not need it. We include the modern bundle with a script type="module" tag and the legacy bundle with a script nomodule tag. Modern browsers that support ES2015+ will download the modern bundle and ignore the legacy bundle. Legacy browsers that does not support type="module" will download and execute the legacy bundle. Some old browsers might download the modern bundle as well, but not execute it. More information about this approach