Nimble Package Maestros

    rotom

    0.12.0 • Public • Published

    Rotom

    Write intuitive, deterministic, and extendable web components.


    Version License Circle CI status (master) bundle size dependency status

    See Rotom in action!

    🧾 Explore

    Getting Started

    So you're ready to take the dive? Awesome! Check out the wiki articles below on getting started. If you run into any problems or simply have ideas and suggestions, don't be shy about submitting an issue or pull request!

    Install

    $ npm i rotom

    CDN

    Use the CDN to skip packaging and use the library from the cloud.

    You can use Rotom with string or jsx renderers. Make sure to use the right version of Rotom for your renderer as shown below.

    Omdomdom:

    <!-- Development build -->
    <script
      type="text/javascript"
      src="https://cdn.jsdelivr.net/npm/omdomdom@0.3.0/dist/omdomdom.js"
      integrity="sha256-BpjOyF5QNlVmvIoAucFkb4hr+8+5r0qctp12U3J9cmM="
      crossorigin="anonymous"
    ></script>
    
    <!-- OR production build-->
    <script
      type="text/javascript"
      src="https://cdn.jsdelivr.net/npm/omdomdom@0.3.0/dist/omdomdomm.min.js"
      integrity="sha256-BpjOyF5QNlVmvIoAucFkb4hr+8+5r0qctp12U3J9cmM="
      crossorigin="anonymous"
    ></script>
    <!-- Development build -->
    <script
      type="text/javascript"
      src="https://cdn.jsdelivr.net/npm/rotom@0.12.0/dist/rotom.template.js"
      integrity="sha256-IbXDe8TmN1por6MG4Zu906uX9I6yfjT/HcOiJtbda3g="
      crossorigin="anonymous"
    ></script>
    
    <!-- OR production build -->
    <script
      type="text/javascript"
      src="https://cdn.jsdelivr.net/npm/rotom@0.12.0/dist/rotom.template.min.js"
      integrity="sha256-/r/3pprCOy3t+5DkvH7KnBZHRT/aNm2Om5dJMgusWi8="
      crossorigin="anonymous"
    ></script>

    Snabbdom:

    <!-- Development build -->
    <script
      type="text/javascript"
      src="https://cdn.jsdelivr.net/npm/rotom@0.12.0/dist/snabbdom.js"
      integrity="sha256-0xccUJ0Wrf3QnJXGrV4onKUkgI92mpyy+48H4jIN4Ho="
      crossorigin="anonymous"
    ></script>
    
    <!-- OR production build-->
    <script
      type="text/javascript"
      src="https://cdn.jsdelivr.net/npm/rotom@0.12.0/dist/snabbdom.min.js"
      integrity="sha256-2ocqbM/5Lp2mPUeOc5EYrFGf8tFXkpRM3hg0PIU5m8k="
      crossorigin="anonymous"
    ></script>

    Note that Snabbdom doesn't build its own browser bundle so Rotom provides it.

    <!-- Development build -->
    <script
      type="text/javascript"
      src="https://cdn.jsdelivr.net/npm/rotom@0.12.0/dist/rotom.jsx.js"
      integrity="sha256-szJd11RmdmUtdeLk+ZljpYNsWc+TQoPPPz5LUXJNbHM="
      crossorigin="anonymous"
    ></script>
    
    <!-- OR production build -->
    <script
      type="text/javascript"
      src="https://cdn.jsdelivr.net/npm/rotom@0.12.0/dist/rotom.jsx.min.js"
      integrity="sha256-8/CwMQH6wP3K9EjYSBTN9A1v9L9+8aCykewew4ygrb8="
      crossorigin="anonymous"
    ></script>

    Write with Template Strings

    This is the default configuration and easiest way to use Rotom. It enables you to write HTML in your components as string templates.

    Write your component with HTML strings:

    import { RotomElement, register } from "rotom"
    
    class FirstComponent extends RotomElement {
      constructor() {
        super()
        this.handleMouseEnter = this.handleMouseEnter.bind(this)
      }
    
      onMount() {
        this.target = this.shadowRoot.querySelector("#foo")
        this.target.addEventListener("mouseenter", this.handleMouseEnter)
      }
    
      onUnmount() {
        this.target.removeEventListener("mouseenter", this.handleMouseEnter)
      }
    
      handleMouseEnter(e) {
        console.log(e.target.innerText)
      }
    
      render() {
        return "<p class='bar'>What a cool component!</p>"
      }
    }
    
    register("first-component", FirstComponent)

    Learn more about Omdomdom.

    Write with JSX

    JSX is an industry standard for writing views, and it's fully supported in Rotom. Snabbdom, a popular and performant JSX library, is used.

    When importing from rotom, ensure you specify rotom/jsx as the import path and import the jsx pragma from snabbdom directly (you might need to whitelist jsx as an unused variable in linters):

    import { RotomElement, register } from "rotom/jsx"
    import { jsx } from "snabbdom"
    
    class FirstComponent extends RotomElement {
      render() {
        return (
          <p className="bar" on-mouseenter={(e) => console.log(e.target.innerText)}>
            What a cool component!
          </p>
        )
      }
    }
    
    register("first-component", FirstComponent)

    Next, you're going to need some way of transforming the JSX at build time. The easiest way is transpiling your code with Babel using @babel/plugin-transform-react-jsx with Snabbdom's pragma.

    Add the plugin to your babel.config.json. Example:

    {
      "plugins": [["@babel/plugin-transform-react-jsx", { "pragma": "jsx" }]]
    }

    Learn more about Snabbdom's JSX API in the modules section of their documentation.

    Default and Custom Renderer Versions

    If you want to use a specific version of Omdomdom or Snabbdom, you can do so by explicitly installing it alongside Rotom. See Rotom's optionalDependencies field in its package.json file for the default version you will get.

    Type Checking and Debugging

    The development (unminified) build of Rotom will include component property type checking. This feature is omitted in the production build.

    Browser Support

    The npm and browser bundles will work in all major browsers, except IE11. The package contains no explicit polyfills.

    Use the below polyfills to achieve IE11 support. Include them once in your app (or page) before importing Rotom.

    You will also need to run the bundle through ES5 transpilation for things like arrow functions.

    Performance

    Both the string and JSX libraries use performant reconciliation algorithms to change content on a page.

    However, as good as the performance is, it isn't perfect, so changes are always welcome!

    Contribute

    If you like the project or find issues, feel free to contribute!

    See this StackOverflow answer on prerelease versioning.

    Install

    npm i rotom

    DownloadsWeekly Downloads

    1

    Version

    0.12.0

    License

    MIT

    Unpacked Size

    843 kB

    Total Files

    65

    Last publish

    Collaborators

    • geotrev