Skip to content

Latest commit

 

History

History
334 lines (233 loc) · 12.8 KB

README.md

File metadata and controls

334 lines (233 loc) · 12.8 KB
Raw

bulmil

Built with Stencil Code Style npm version License MIT
dependencies Circle CI npm downloads Package Phobia Bundle Phobia

Bulmil is an agnostic UI library based on Web Components, made with Bulma.io & Stencil.js.

Bulmil was created as a proof of concept to introduce an easy way to consume common reusable web components for use with various modern application frameworks (Angular, Vue, React, Ember) or simply with pure Javascript.

⚠️ Currently in Alpha, beta will be available once this issue is resolved.

Why Stencil?

Stencil is a compiler for building fast web apps using Web Components.

Stencil combines the best concepts of the most popular frontend frameworks into a compile-time rather than run-time tool. Stencil takes TypeScript, JSX, a tiny virtual DOM layer, efficient one-way data binding, an asynchronous rendering pipeline (similar to React Fiber), and lazy-loading out of the box, and generates 100% standards-based Web Components that run in any browser supporting the Custom Elements v1 spec.

Stencil components are just Web Components, so they work in any major framework or with no framework at all.

Getting Started

# Using npm
npm i @bulmil/core

# Using yarn
yarn add @bulmil/core

Usage

Without a javascript framework

Integrating a component built with Stencil to a project without a JavaScript framework is straight forward. If you're using a simple HTML page, you can add your component via a script tag. For example, if we published a component to npm, we could load the component through a CDN like this:

<!DOCTYPE html>
<html lang="en">
  <head>
    <link rel="stylesheet" href="https://unpkg.com/@bulmil/core@latest/dist/css/bulmil.min.css" />
    <script src="https://unpkg.com/@bulmil/core@latest/dist/bulmil/bulmil.js"></script>
  </head>
  <body>
    <bm-button>Button</bm-button>
  </body>
</html>

Alternatively, if you wanted to take advantage of ES Modules, you could include the components using an import statement. Note that in this scenario applyPolyfills is needed if you are targeting Edge or IE11.

<!DOCTYPE html>
<html lang="en">
  <head>
    <link rel="stylesheet" href="https://unpkg.com/@bulmil/core@latest/dist/css/bulmil.min.css" />
    <script type="module">
      import {
        applyPolyfills,
        defineCustomElements,
      } from 'https://unpkg.com/@bulmil/core@latest/dist/loader/index.es2017.js';
      applyPolyfills().then(() => {
        defineCustomElements(window);
      });
    </script>
  </head>
  <body>
    <bm-button>Button</bm-button>
  </body>
</html>

Try this example on Codesandbox

Frameworks

Unfortunately the experience of integrating web components into existing applications can be tricky at times. More about this can be read at https://custom-elements-everywhere.com/. In order to accommodate the various issues the Stencil team has created new output target plugins to make the process simpler.

The plugins add additional output targets for each framework binding that is included. This output target will emit a native angular/react/vue library, just like if your components were originally written using any of these frameworks.

There are framework specific bindings for:

Keep in mind, that at its core Bulmil is still simply web components. Even if your framework is not mentioned in the list above, it most likely still supports Bulmil natively. You can check here if your framework has complete support for web components.

There are also examples for loading and using Bulmil with:

React

Unfortunately React has poor web components support ... but we have you covered with our @bulmil/react package, which wraps all the Bulmil web components inside React components so it feels natural to interact with, and it removes all the limitations of working with web components inside React.

Let's first load the CSS for the application, the css file includes:

  • Bulma base
  • Bulma helpers
  • Other components & elements not fitting in any components or not implemented yet.

Add the following to the root of your application:

// Global CSS (includes base & helpers). ~50KB
// We recommend to use purgecss to remove the unused css styles from your application.
import '@bulmil/core/dist/css/bulmil.min.css';

Now let's install the @bulmil/react package by running the following in your terminal:

# Using npm
npm i @bulmil/react

# Using yarn
yarn add @bulmil/react

And ... we're all done 🎉

Vue

You have two options with Vue due to it having perfect web components support. You can either follow the instructions here for loading the web components in their natural form, or you can use the Vue bindings from the @bulmil/vue package, which wraps all the web components inside Vue components so you can feel right at home. Some other advantages for using @bulmil/vue include typed + documented components, and additional helpers for extending Bulmil with custom components.

Let's first load the CSS for the application, the css file includes:

  • Bulma base
  • Bulma helpers
  • Other components & elements not fitting in any components or not implemented yet.

Add the following to the root of your application:

// Global CSS (includes base & helpers). ~50KB
// We recommend to use purgecss to remove the unused css styles from your application.
import '@bulmil/core/dist/css/bulmil.min.css';

Now let's install the @bulmil/vue package by running the following in your terminal:

# Using npm
npm i @bulmil/vue

# Using yarn
yarn add @bulmil/vue

And ... we're all done 🎉

Using Nuxt

Create a plugin, (e.g plugins/bulmil.ts):

import Vue from 'vue';

import { applyPolyfills, defineCustomElements } from '@bulmil/core/dist/loader';

Vue.config.productionTip = false;
Vue.config.ignoredElements = [/bm-\w*/];

// Bind the custom elements to the window object
applyPolyfills().then(() => {
  defineCustomElements(window);
});
// nuxt.config.ts
{
  plugins: [
    { src: '~/plugins/bulmil.ts', mode: 'client' },
  ],
}

The components should then be available in any of the Vue components

render() {
  return (
    <div>
      <bm-button>Button</bm-button>
    </div>
  )
}

Angular

You have two options with Angular due to it having perfect web components support. You can either follow the instructions here for loading the web components in their natural form, or you can use the Angular bindings from the @bulmil/angular package, which wraps all the web components inside Angular components so you can feel right at home. Some other advantages for using @bulmil/angular include typed + documented components, and additional helpers for extending Bulmil with custom components.

Let's first load the CSS for the application, the css file includes:

  • Bulma base
  • Bulma helpers
  • Other components & elements not fitting in any components or not implemented yet.

Add the following to the root of your application styles:

// Global CSS (includes base & helpers). ~50KB
// We recommend to use purgecss to remove the unused css styles from your application.
import '@bulmil/core/dist/css/bulmil.min.css';

Now let's install the @bulmil/angular package by running the following in your terminal:

# Using npm
npm i @bulmil/angular

# Using yarn
yarn add @bulmil/angular

And ... we're all done 🎉

Svelte

You have two options with Svelte due to it having perfect web components support. You can either follow the instructions for loading it from the CDN and use the Bulmil web components in their natural form, or you can use the Svelte bindings from the @bulmil/svelte package, which wraps all the web components inside Svelte components so you can feel right at home. Some other advantages for using @bulmil/svelte include typed + documented components, and additional helpers for extending Bulmil with custom components.

Let's first load the CSS for the application, the css file includes:

  • Bulma base
  • Bulma helpers
  • Other components & elements not fitting in any components or not implemented yet.

Add the following to the <head> element of your HTML file:

// Global CSS (includes base & helpers). ~50KB
// We recommend to use purgecss to remove the unused css styles from your application.
import '@bulmil/core/dist/css/bulmil.min.css';

Now let's install the @bulmil/svelte package by running the following in your terminal:

# Using npm
npm i @bulmil/svelte

# Using yarn
yarn add @bulmil/svelte

And ... we're all done 🎉

Ember

Working with Stencil components in Ember is really easy thanks to the ember-cli-stencil addon. It handles:

  • Importing the required files into your vendor.js
  • Copying the component definitions into your assets directory
  • Optionally generating a wrapper component for improved compatibility with older Ember versions

Start off by installing the Ember addon

ember install ember-cli-stencil

Now, when you build your application, Stencil collections in your dependencies will automatically be discovered and pulled into your application. You can just start using the custom elements in your hbs files with no further work needed. For more information, check out the ember-cli-stencil documentation.

Development

  1. Clone this repository
  2. Install dependencies using yarn install or npm install
  3. Start development server using yarn storybook or npm run storybook

📑 License

MIT License