@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.

Styles

This project uses svelte-preprocess-cssmodules, which means you can add $style. in front of your classnames to scope them for your app. This prevents conflicts with the styles on the page your app is included on, and also allows for the uniqueID functionality where you can have multiple instances of your app running on the same page.

If you define any global css variables, consider their names as they might conflict with variables set on the page your component is used on.

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 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. There's two optional query parameteres you can use

Available query params

parameter	description
&ssrModernClientBundle=true	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.JS.
&uniqueID=my-unique-id	If you need to ESI in multiple instances of the same component on a page, you can send in a unique ID for each of them. This is needed to avoid targeting issues for the clientside scripts. This works by server side rendering all scripts and inserting the unique ID before classnames. Note that this forces all browsers to download the legacy clientside bundle, which is a fairly large increase in bundle size. Each component with a unique ID will be cached separately, so avoid too many different ones.

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 functions. 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 = renderComponent({ name: 'example' })

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

Options for package

parameter	type	description	sync	async
name	String	Name of the component you want to render	:heavy_check_mark:	:heavy_check_mark:
bundlePath	String	Path to the bundle, leave as default if import from package. Useful for local devlopment, as you can target localhost this way	:heavy_check_mark:	:heavy_check_mark:
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.	:x:	:heavy_check_mark:
uniqueMode	Boolean	Allows for multiple instances of the same svelte component on the same page. This works by server side rendering all scripts and inserting a unique hash before classnames. Note that this forces all browsers to download the clientside bundle component	:x:	:heavy_check_mark:

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