Svelte Injector
Go Svelte one component at a time
Features
- Use Svelte components in any framework: React, Angular, Vue, jQuery, Vanilla JS.
- Easily migrate to Svelte while keeping older code running.
- Built in React and AngularJS components for ease of use.
- Write agnostic Svelte components. No workarounds needed.
- Uses Portals to render components where you want them.
- The Svelte App is in your control. Use contexts/store/head/window.
- Support for dynamic imports and lazy loading.
Table of contents
Installing
npm install --save-dev svelte-injector svelte
Then configure your bundler of choice to accept Svelte files.
Usage
Setup
Create your Svelte App: --> reference
src/svelte/main
import App from "./App.svelte";
const svelteEntrypoint = document.createElement("div");
svelteEntrypoint.id = "svelte-entrypoint";
document.body.prepend(svelteEntrypoint);
// Create Svelte App
new App({
target: svelteEntrypoint,
});
Note: Svelte needs to share the DOM with your existing app. It's recommended you don't use document.body
as the App target while you are migrating.
App.svelte
<script>
import { InjectedComponents } from "svelte-injector";
</script>
<InjectedComponents/>
Use svelte-loader
or rollup-plugin-svelte
in your bundler. Make sure you are not excluding /svelte-injector/
as it lives in your /node-modules/
Injecting Components
Creating
Imported components
Import the component class into your framework controller, then use create()
.
import Hello from "./Hello.svelte";
SvelteInjector.create(target, Hello, props);
Linked components
Link component class with a string to use it anywhere.
Import your components somewhere in your bundle (es: create an index.module
file)
import Hello from "./Hello.svelte";
SvelteInjector.link("hello", Hello);
// OR for lazy loading
SvelteInjector.link("hello", async () => {
return (await import("./Hello.svelte")).default
})
then use this string as the second argument of create()
SvelteInjector.create(target, "hello", props);
Hydrating
Place HTML placeholders and then hydrate
them
Use this notation in the template:
<div data-component-name="hello">
<template class="props"">
<!--JSON formatted-->
{"name": "hello"}
</template>
</div>
Then call hydrate()
to update the components tree in Svelte.
SvelteInjector.hydrate(target);
You can use data-to-render
attribute as an {if}
block in Svelte
<div data-component-name="hello" data-to-render"true">
<template class="props"">
<!--JSON formatted-->
{"name": "hello"}
</template>
</div>
Hydrating source HTML
On multi page applications you can create components directly from the source HTML.
If any page of your source contains component markup, just hydrate
the body to render them.
SvelteInjector.hydrate(document.body);
NOTE: make sure to hydrate the body only after linking your components.
Framework integration
This project was created to easily migrate apps from AngularJs to Svelte, but it is not framework specific.
Svelte components should NOT be aware of the fact that they were used by another framework.
AngularJs
Use the built-in AngularJS component.
Link your Svelte component
// /svelte/index.module.ts
import SvelteInjector from "svelte-injector";
import Component from "src/Component.svelte";
SvelteInjector.link("component-name", Component);
// /angularjs/index.module.ts
import { svelteComponent } from "svelte-injector/angularjs";
angular.component("svelteComponent", svelteComponent);
Now in any AngularJS component you can use:
<svelte-component component="component-name" props="$ctrl.svelteProps"/>
Bindings:
const bindings = {
component: "@", // Link name
props: "?<", // Props object
toRender: "?<", // Ng-if
options: "?<", // HydrateOptions
encode: "?<", // encode props?
onMount: "?&", // Function called with "element" param on mount
}
React
Use the built-in React component.
import { SvelteComponent } from "svelte-injector/react"
// Using the class
import Component from "src/Component.svelte";
function YourComponent(props){
return <SvelteComponent component={Component} props={{name: "world"}}/>
}
// Using the link name
function YourComponent(props){
return <SvelteComponent component={"hello"} props={{name: "world"}}/>
}
// Conditional rendering
function YourComponent(props){
return <SvelteComponent component={"hello"} props={{name: "world"}} to-render={props.render}/>
}
Props:
export type SvelteComponentProps = {
component: string | typeof SvelteComponentClass;
props?: any;
toRender?: boolean;
options?: CreateOptions;
onMount?: (element: SvelteElement) => void;
};
Angular
Docs in progress
JS API
Elements
Interface SvelteElement
updateProps(props)
object
props The new props object. All previous props will be dropped.
setToRender(toRender)
boolean
toRender Set if the component should render of not. Useful for conditional rendering.
destroy()
Destroys the component.
Injector
create(target, Component, props[,toRender], [options])
HTMLElement
target The element in which the component will be rendered
SvelteComponent | string
Component The Svelte component Class or the link name
object
props An object with props compatible with the Svelte Component
boolean
(default = true)
toRender Boolean that indicates if the component should render immediately.
CreateOptions
(defaults)
options Object with options
Promise<SvelteElement>
RETURN A promise that resolves the SvelteElement
when the component is mounted or created (when toRender = false)
link(linkName, svelteComponent)
string
linkName The name of the link
SvelteComponent | function
svelteComponent The Svelte Component class or an async functions that returns one (useful for dynamic imports and lazy loading).
hydrate(target[,options])
HTMLElement
target The element in which the components will be looked for.
HydrateOptions
(defaults)
options Object with options
Promise<SvelteElement[]>
RETURN A promise array for each created component that resolves the SvelteElement
when the component is mounted or created (when data-to-render = false)
findComponentByName(name)
string
name name of the component as previously linked with link()
typeof SvelteComponent
RETURN The Class of the linked component, if any
findLinkNameByClass(Class)
typeof SvelteComponent
Class Class of the component as previously linked with link()
string
RETURN The name of the linked component, if any
generatePropsBlock(props)
Returns an HTML string representing the props template HTML element, as expected from hydrate
.
serializeProps(props)
Returns stringified (and encoded?) string from a props object, as expected from the parser.
Options
Options object are the opional last argument of create
and hydrate
methods.
CreateOptions:
####observeParents Create a MutationObserver on the element parent and destroy the component if no longer in the DOM
HydrateOptions:
####observeParents (default: true) Create a MutationObserver on the element parent and destroy the component if no longer in the DOM
####observe (default: true) Create a MutationObserver on the props element and update the component on props updates.
Migrating from v1
Methods:
The main methods have been renamed
createElement --> create
createElementFromTemplate, syncTemplate --> hydrate
Template
Use of data-props
attribute is no longer supported. Props should be expressed in the new template format:
<div data-component-name="hello" data-to-render"true">
<template class="props"">
<!--JSON formatted-->
{"name": "hello"}
</template>
</div>
Credits
- Svelte
- Portals implementation was inspired by @romkor's work on svelte-portal.