Vionic package

Vionic is a NPM package to load the Ionic framework with just vanilla JavaScript. It is licensed as open-source under the MIT license.

Vionic allows developers to employ the Ionic framework in pure offline apps. Unlike common examples, it is neither required to link to an online CDN nor to utilize a web framework like React, Vue or Angular.

Take a look at the Vionic example app or read the installation and usage sections below, if you want to know how to use Vionic in your project.

Installation

Just install Vionic like any other NPM package:

npm install vionic

The vionic package includes the Ionic core and Ionicons packages as dependencies.

Versioning

Vionic uses semantic versioning with some little tweaks:

• Major: Same as the major version of the underlying Ionic core package.
• Minor: Updated when a new feature or icon has been added.
• Patch: Updated when a bugfix or minor improvement occurred.

Breaking changes will only happen when the major version changes.

Usage

First, add the following line to the main CCS file of the project to load the Ionic CSS:

@import "vionic/styles.css";

To load all Ionic components and icons at once, the following lines need to be added to the main JavaScript module of the app:

export * from "vionic/components/";
export * from "vionic/icons/";

However, the loading process can take quite some time, so it is recommended to load components and icons individually.

Components

If you want to use an Ionic component, you have to load it before you can use it. Assuming you want to create a new web-component with an ion-button, the code could look like follows:

export * from "vionic/components/ion-button";

const html = "<p><ion-button>Add something</ion-button></p>";

window.customElements.define("button-example", class extends HTMLElement {
    connectedCallback() {
      this.innerHTML = html;
    }
  }
);

Icons

Similar to a component, a named icon also has to be loaded explicitly before use. Assuming you would replace the button-text in the example above with an icon, the following code could be used:

export * from "vionic/components/ion-button";
export * from "vionic/components/ion-icon";
export * from 'vionic/icons/add.js';

const html = "<p><ion-button><ion-icon name="add"></ion-icon></ion-button></p>";

window.customElements.define("button-example", class extends HTMLElement {
    connectedCallback() {
      this.innerHTML = html;
    }
  }
);

Building

The JavaScript files in the components and icons directories have been generated from the JavaScript files in the template directory.

Run the following NPM commands to update the component and icon loader scripts:

npm run update-components
npm run update-icons

Acknowledgements

While developing this packages supertorpe's ionic-vanilla-js repository helped me a lot to understand the underlying logic of the Ionic loading process.

Copyright (c) 2024 Torben Haase <https://letorbi.com>