Neighbourhood Party Manager

    svelte-injector
    TypeScript icon, indicating that this package has built-in type declarations

    2.0.8 • Public • Published

    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)

    props object

    The new props object. All previous props will be dropped.

    setToRender(toRender)

    toRender boolean

    Set if the component should render of not. Useful for conditional rendering.

    destroy()

    Destroys the component.

    Injector

    create(target, Component, props[,toRender], [options])

    target HTMLElement

    The element in which the component will be rendered

    Component SvelteComponent | string

    The Svelte component Class or the link name

    props object

    An object with props compatible with the Svelte Component

    toRender boolean (default = true)

    Boolean that indicates if the component should render immediately.

    options CreateOptions (defaults)

    Object with options

    RETURN Promise<SvelteElement>

    A promise that resolves the SvelteElement when the component is mounted or created (when toRender = false)

    link(linkName, svelteComponent)

    linkName string

    The name of the link

    svelteComponent SvelteComponent | function

    The Svelte Component class or an async functions that returns one (useful for dynamic imports and lazy loading).

    hydrate(target[,options])

    target HTMLElement

    The element in which the components will be looked for.

    options HydrateOptions (defaults)

    Object with options

    RETURN Promise<SvelteElement[]>

    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)

    name string

    name of the component as previously linked with link()

    RETURN typeof SvelteComponent

    The Class of the linked component, if any

    findLinkNameByClass(Class)

    Class typeof SvelteComponent

    Class of the component as previously linked with link()

    RETURN string

    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

    License

    MIT

    Install

    npm i svelte-injector

    DownloadsWeekly Downloads

    12

    Version

    2.0.8

    License

    MIT

    Unpacked Size

    57.4 kB

    Total Files

    20

    Last publish

    Collaborators

    • kornfactory