@ebanx/global-components

Global components for websites/webapps, built with Stencil.

@ebanx/global-components on npm

:space_invader: Maintainers

If you need anything, those people below can help you:

• Thiago Higuchi
• Fernando Ghiberti
• Viviane Veiga

:school_satchel: Requirements

In order to have the correct development experience, you need to install the following:

• node.js (version 12 or above)
• npm (npm is shipped with node; if you don't have it, try the link above)

Using the components

The components depends on Gilroy and Open Sans fonts to render correctly - those fonts must be inside their host application to avoid double requests.

EBANX has a CDN to load Gilroy fonts, and Open Sans is available with Google Fonts.

:gem: Stack

This project is built with Stencil, a toolchain for building web components and design systems using the Web Components API. The actual project was created using the component started, offered by stencil-cli.

Stencil play as a compiler for the web components; and those components uses Angular under the hood - we can also create them in a functional style too. Stencil offers a great tooling, and the components were generated using stencil generate helper.

The styles are component-scoped, and the stylesheets are written in plain CSS.

As the package manager, it uses npm; prettier, husky and lint-staged are used to ensure code's patterns.

The project also uses semantic-release with commitizen to ensure a correct package versioning.

For testing, it uses jest with Stencil's abstractions - components are generated with default unit and e2e test specs.

:computer: Developing

First things first: clone the repo.
After clonning the repo, use the following commands to start developing:

# install dependencies
npm install

# start development server at http://localhost:3333
npm run start

# commiting changes to remote
npm run commit
# it will trigger git-cz to start, a helper used to ensure the correct commit message
# that will be used by semantic-release within the deploy workflow, in order to
# create the correct package versioning using sem-ver

# create a production build
npm run build

The project was created using npm but you can use yarn as your package manager and script runner without big worries as well. If you use yarn, you may find some issues with the lock files.

:open_file_folder: Project structure

If you're not familiar with Stencil's folder structure, here's a brief explanation:

• /src: where the sources are;
  • /components: where our components live;
  • components.d.ts: Stencil generated file which contains information about our components;
  • index.ts: Stencil generated file which exports our components

For more information, take a look on Stencil's docs.

:name_badge: Naming Components

Components name's must be lower, dashed-case.

When creating new component tags, we recommend not using stencil in the component name (ex: <stencil-datepicker>). This is because the generated component has little to nothing to do with Stencil; it's just a web component!

Instead, use the prefix ebanx :rocket:

Like ebanx-cookie-disclaimer, ebanx-logo...

:microscope: Testing

Components are unit and e2e tested. To start the suite, run the following command:

npm run test

Test files can be found within components' folders.

:rocket: Build and Release

This project is release on npm with the help of semantic-release and GitHub Actions.

Every merged PR (pull request) into master branch will start the release workflow; if everything works fine, a new version will be automatically released within seconds.

The master branch is blocked. When working on this project create new, dedicated branches to your changes and always merge it into master.

Obs. To perform release correctly enter npm and git, we need to insert the fix: or feat: before the name of the commit.

:wrench: Using the components

There are two ways to use those components:

CDN

The easiest way to use those components in your web app is using a package CDN link in your HTML template - it can be used with CMSs (WordPress), page builders (HubSpot, Webflow) and any JS framework (React, Vue...).

To do so, put those tags in your template:

<!-- preferably before </body> -->
<script
  type="module"
  src="https://unpkg.com/@ebanx/global-components/dist/global-components/global-components.esm.js"
></script>
<script
  nomodule
  src="https://unpkg.com/@ebanx/global-components/dist/global-components/global-components.js"
></script>

All the components' styles are scoped within itself, so don't worry about colisions nor overridings.

And then you're able to use the components:

<ebanx-logo></ebanx-logo>

<ebanx-cookies-disclaimer></ebanx-cookies-disclaimer>

The above example shows the import using unpkg CDN. unpkg has a slightly better approach to use the package's latest version; jsDelivr CDN cache is a bit harder, even using the @latest flag on the version - so you can face some issues while using it.

Installing the package

You can also install this package as your project's dependency:

npm i @ebanx/global-components

After installing, you can import the components into your app's main file and use them. It's worthy to check Stencil's framework integrations!