Guides
Svelte, React and Vue
Mount a component as a widget with the SDK adapters.
EdgeStation has no framework-specific API: it calls the widget module's mount(el, api) and runs the cleanup it returns. The SDK's adapters turn a component into such a module. Each one mounts the component in el with the api as its only prop, and unmounts it with the widget.
| Framework | Adapter | Plugin to add next to widget() |
|---|---|---|
| Svelte 5 | svelteWidget from @edgestation/sdk/svelte |
svelte({ emitCss: false }) |
| React 19 | reactWidget from @edgestation/sdk/react |
react() |
| Vue 3 | vueWidget from @edgestation/sdk/vue |
vue() |
The component's props are typed WidgetProps: { api: WidgetApi }. Installing the SDK lists the packages each one needs.
Svelte 5
npm install -D @edgestation/sdk vite svelte @sveltejs/vite-plugin-svelteimport { widget } from '@edgestation/sdk/vite';
import { svelte } from '@sveltejs/vite-plugin-svelte';
import { defineConfig } from 'vite';
export default defineConfig({ plugins: [svelte({ emitCss: false }), widget()] });import { svelteWidget } from '@edgestation/sdk/svelte';
import Cpu from './Cpu.svelte';
export default svelteWidget(Cpu);<script lang="ts">
import type { WidgetProps } from '@edgestation/sdk';
let props: WidgetProps = $props();
// svelte-ignore state_referenced_locally
const { api } = props;
let load = $state(0);
api.every(1000, async () => (load = (await api.system()).cpu.load));
</script>
<p>{Math.round(load)} %</p>
<style>
p {
color: var(--primary);
}
</style>- Styles.
emitCss: falsekeeps each component's<style>block in its JavaScript, and Svelte adds it to the widget's shadow root when the component mounts. There is no CSS file, so leavestylesout of the manifest. - Reading
api. Readapifrom the props once, at the top of the script. Svelte warns that this only captures the prop's first value (state_referenced_locally): that is what you want, since a setting change remounts the widget rather than changing the prop. Takingapiout ofpropsin one statement, as above, keeps the warning to that line, which thesvelte-ignorecomment silences. Destructured straight from$props(),apiwould raise it at every use. - Errors. Svelte redraws after the callback that changed its state has returned, so errors thrown while drawing don't show the error card. Errors in callbacks wrapped with
api.guard,api.everyorapi.afterdo. - Scrollbars. An attachment gives an element the app's scrollbars and removes them with it:
<ul {@attach (ul) => api.scrollbars(ul)}>.
React 19
npm install -D @edgestation/sdk vite react react-dom @vitejs/plugin-reactimport { widget } from '@edgestation/sdk/vite';
import react from '@vitejs/plugin-react';
import { defineConfig } from 'vite';
export default defineConfig({ plugins: [react(), widget()] });import { reactWidget } from '@edgestation/sdk/react';
import type { WidgetProps } from '@edgestation/sdk';
import { useEffect, useState } from 'react';
import './styles.css';
function Cpu({ api }: WidgetProps) {
const [load, setLoad] = useState(0);
useEffect(() => api.every(1000, async () => setLoad((await api.system()).cpu.load)), []);
return <p>{Math.round(load)} %</p>;
}
export default reactWidget(Cpu);- Effects.
api.every,api.after,api.webviewandapi.scrollbarsreturn their cleanup, so an effect can return their result directly, as above. - Styles. CSS you import goes to
dist/main.css. Add"styles": "dist/main.css"to the manifest. - Errors. An error thrown while rendering, that no error boundary of yours catches, shows the widget's error card.
Vue 3
npm install -D @edgestation/sdk vite vue @vitejs/plugin-vueimport { widget } from '@edgestation/sdk/vite';
import vue from '@vitejs/plugin-vue';
import { defineConfig } from 'vite';
export default defineConfig({ plugins: [vue(), widget()] });import { vueWidget } from '@edgestation/sdk/vue';
import Cpu from './Cpu.vue';
export default vueWidget(Cpu);<script setup lang="ts">
import { ref } from 'vue';
import type { WidgetProps } from '@edgestation/sdk';
const { api } = defineProps<WidgetProps>();
const load = ref(0);
api.every(1000, async () => (load.value = (await api.system()).cpu.load));
</script>
<template>
<p>{{ Math.round(load) }} %</p>
</template>
<style>
p {
color: var(--primary);
}
</style>- Styles.
<style>blocks go todist/main.css. Add"styles": "dist/main.css"to the manifest. They don't needscoped: the widget's shadow root already keeps them in. - Errors. Errors Vue catches (in rendering, lifecycle hooks, watchers and template event handlers) show the widget's error card.
- TypeScript. For
tscto understand.vuefiles, check them withvue-tsc.
Another framework
Any framework that can render into an element works without an adapter: write the module yourself. mount renders into el and returns what unmounts it, and errors you catch can go to the error card through api.guard:
import { defineWidget } from '@edgestation/sdk';
export default defineWidget({
mount(el, api) {
const app = renderMyApp(el, { api }); // your framework's mount
return () => app.destroy(); // and its unmount
}
});