Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/Gomah/bulmil
:lipstick: A agnostic UI components library based on Web Components, made with Bulma & Stencil.
https://github.com/Gomah/bulmil
bulma bulmil stencil-components stencil-js stenciljs stenciljs-components ui-components ui-framework webcom
Last synced: 5 days ago
JSON representation
:lipstick: A agnostic UI components library based on Web Components, made with Bulma & Stencil.
- Host: GitHub
- URL: https://github.com/Gomah/bulmil
- Owner: Gomah
- License: mit
- Created: 2019-07-01T11:54:47.000Z (over 5 years ago)
- Default Branch: main
- Last Pushed: 2024-04-19T09:45:06.000Z (7 months ago)
- Last Synced: 2024-10-29T17:30:26.359Z (10 days ago)
- Topics: bulma, bulmil, stencil-components, stencil-js, stenciljs, stenciljs-components, ui-components, ui-framework, webcom
- Language: TypeScript
- Homepage: https://bulmil.vercel.app
- Size: 16 MB
- Stars: 155
- Watchers: 8
- Forks: 12
- Open Issues: 4
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
- awesome-stenciljs - Bulmil
README
Bulmil is an agnostic UI library based on Web Components, made with [Bulma.io](https://bulma.io/) & [Stencil.js](https://stenciljs.com/).
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.
:warning: Currently in Alpha, beta will be available once [this issue](https://github.com/Gomah/bulmil/issues/26) 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
```bash
# 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:
```html
Button
```
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.
```html
import {
applyPolyfills,
defineCustomElements,
} from 'https://unpkg.com/@bulmil/core@latest/dist/loader/index.es2017.js';
applyPolyfills().then(() => {
defineCustomElements(window);
});
Button
```
[Try this example on Codesandbox](https://codesandbox.io/s/bulmil-es-module-i8ce8)
---
### 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/](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:
- [React](#react)
- [Vue / Nuxt](#vue)
- [Svelte](#svelte)
- [Angular](#angular)
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](https://custom-elements-everywhere.com/) if your framework has complete support for web components.
There are also [examples](./examples) for loading and using Bulmil with:
- [HTML](./examples/html)
- [React](./examples/react)
- [Next](./examples/next)
- [Vue](./examples/vue)
- [Nuxt](./examples/nuxt)
- [Angular](./examples/angular)
- [Svelte](./examples/svelte)
---
### React
Unfortunately React has poor [web components support](https://custom-elements-everywhere.com/#react) ... 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:
```tsx
// 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:
```bash
# Using npm
npm i @bulmil/react
# Using yarn
yarn add @bulmil/react
```
And ... we're all done :tada:
### Vue
You have two options with Vue due to it having perfect [web components support](https://custom-elements-everywhere.com/#vue). You can either follow the instructions [here](https://stenciljs.com/docs/vue) 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:
```tsx
// 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:
```bash
# Using npm
npm i @bulmil/vue
# Using yarn
yarn add @bulmil/vue
```
And ... we're all done :tada:
### Using Nuxt
Create a plugin, (e.g plugins/bulmil.ts):
```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);
});
```
```ts
// nuxt.config.ts
{
plugins: [
{ src: '~/plugins/bulmil.ts', mode: 'client' },
],
}
```
The components should then be available in any of the Vue components
```tsx
render() {
return (
Button
)
}
```
### Angular
You have two options with Angular due to it having perfect [web components support](https://custom-elements-everywhere.com/#angular). 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:
```tsx
// 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:
```bash
# Using npm
npm i @bulmil/angular
# Using yarn
yarn add @bulmil/angular
```
And ... we're all done :tada:
### Svelte
You have two options with Svelte due to it having perfect [web components support](https://custom-elements-everywhere.com/#svelte). 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 `` element of your HTML file:
```tsx
// 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:
```bash
# Using npm
npm i @bulmil/svelte
# Using yarn
yarn add @bulmil/svelte
```
And ... we're all done :tada:
### 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
```bash
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](https://github.com/alexlafroscia/ember-cli-stencil).
---
## 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](./LICENSE)