@viamedici-spc/configurator-framer-host
Version:
Provides a Web Component for host applications to embed a Framer based Viamedici SPC configurator.
108 lines (74 loc) • 5.59 kB
Markdown
<div >
<strong>Viamedici SPC</strong>
</div>
# Host Component for Framer Configurators
[](https://www.npmjs.com/package/@viamedici-spc/configurator-framer-host)
[](https://github.com/viamedici-spc/configurator-framer-host/blob/main/LICENSE)
[](https://github.com/viamedici-spc/configurator-framer-host/actions/workflows/main.yml?query=branch%3Amain)
## Introduction
This package provides a Web Component that allows host applications to embed a Framer-based Viamedici SPC configurator.
It is designed to be used in any modern web environment (e.g. plain HTML, React, Vue, etc.) and enables seamless integration to provide the best user experience.
## Modes
### Native Mode
In native mode, the configurator is embedded directly into the host application DOM without an iframe. This allows for tight visual and layout integration, resulting in a more seamless user experience. However, since the configurator shares the same document context as the host, styling or DOM
conflicts can arise. Use this mode only when full control over the host environment is ensured.
### Isolated Mode
The isolated mode, enabled via `isolated="true"`, embeds the configurator within a sandboxed iframe. This ensures that both host and configurator remain fully decoupled, preventing style or JavaScript interference. To provide a native-feeling height behavior, the iframe automatically resizes based
on its content. This behavior can be disabled using the attribute: `no-auto-height`
## Installation
You can install the package via npm:
```bash
npm install -spc/configurator-framer-host
```
Or use it directly via a CDN (e.g. jsDelivr):
```html
<script type="module" src="https://cdn.jsdelivr.net/npm/@viamedici-spc/configurator-framer-host@1.1.0"></script>
```
## Getting Started
Below is a minimal example of how to embed a Framer configurator using the `<spc-embedded-configurator>` Web Component:
### index.html
```html
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8"/>
<script type="module" src="https://cdn.jsdelivr.net/npm/@viamedici-spc/configurator-framer-host@1.0.0"></script>
</head>
<body>
<spc-embedded-configurator src="https://example.framer.app" isolated="true"/>
</body>
</html>
```
## Attributes
Attributes for `<spc-embedded-configurator>`
| Attribute | Type | Description | Example |
|------------------|-----------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------|
| `src` | `string` | URL of the Framer-based configurator to embed.
| `isolated` | `boolean` | If `true`, the configurator runs in sandboxed iframe mode.<br/>Default: `false` | `true`, `false` or `undefined` |
| `no-auto-height` | `boolean` | if true, it disables automatic resizing of the iframe to match the configurator's content height. Only applicable when `isolated` mode is enabled.<br/>Default: `false` | `true`, `false` or `undefined` |
| `data-*` | `string` | Custom parameters forwarded to the configurator app (see below). | `data-region="eu"` |
## Custom Parameters
Any attribute prefixed with `data-` is forwarded to the embedded configurator as a custom parameter. This lets the host
pass runtime context — for example a configuration model id, a region, or whether the configurator runs inside a webshop.
The `data-` prefix is stripped to form the parameter key, so `data-region="eu"` arrives as the parameter `region` with the
value `"eu"`. Browsers lowercase attribute names, so keys are always lowercase.
```html
<spc-embedded-configurator
src="https://example.framer.app"
data-configuration-model-id="123"
data-region="eu"
data-webshop="true"/>
```
Parameters work identically in native and isolated (iframe) mode and **hot-reload**: changing an attribute at runtime
propagates to the configurator without reloading the page. The configurator reads them via the `useHostParameter` /
`useHostParameters` hooks from `-spc/configurator-framer`.
> Note: every `data-*` attribute is treated as a parameter, including generic ones such as `data-testid`.
## Releasing
After publishing a new version to npm, jsDelivr may continue to serve the previous version for floating URLs (e.g. `@1`, ``) for up to 12 hours per edge node, because each CDN edge caches the resolved file independently.
To make the new version available immediately on all edges and CDN providers, trigger a global purge once npm has accepted the publish:
```bash
curl -fsS "https://purge.jsdelivr.net/npm/@viamedici-spc/configurator-framer-host@1"
curl -fsS "https://purge.jsdelivr.net/npm/@viamedici-spc/configurator-framer-host@latest"
```
## License
This project is licensed under the MIT License - see the LICENSE file for details.