OpenComponents Workshop

opencomponents-logo
By genar fullstack developer at alvarium.io

Introdution

OpenComponents is an open-source framework that allows fast-moving teams to easily build and deploy front-end components. It abstracts away complicated infrastructure and leaves developers with very simple, but powerful building blocks that handle scale transparently.

Why opencomponents?

We’re in the era of microservices rise. The unix philosofy of doing one thing but do it well seems to be a good aproach to separate domin of each mobile part of your system and make it an expert on its domain. This approach has been grew in backend software side successfully but not so much in frontend world.

Developing your frontend logic in opencomponets will help you to:

  • Your components are reusable so you’re enforcing to make the components customizable for any customer needs.
  • Have only one source of true. You will only have to maintain one component in a centralized place.
  • Version history. The OC registry will keep all the deployed versions so that way any old customers using old version of your component can still using the same version in time.
  • Automated updates. If a customer is using a component without specifying the version will use always the last version in its web.
  • Easy scallable. OpenComponents registry saves your components in Amazon’s S3, so you can deploy so much registries as you wish with the same components. Avoiding the one point of failure.
  • You will be able to build sites quicker and using only plain HTML or static site generator.

How does it work?

First, you create your component. It can contain logic to get some data (using node.js) and then the view, including css and js. It can be what you want, including React or Angular components or whatever you like.

Then, you publish it to the OpenComponents registry and you wait a couple of seconds while the registry prepares your stuff to be production-ready.

Now, every web app in your private or public network can consume the component via its own HTTP endpoint during server-side rendering or just in the browser.

Quickstart

Install oc cli

1
npm install -g oc

Create your first component

1
2
3
mkdir ~/components
cd ~/components
oc init my-first-component

Run development server

1
oc dev . 3030

Development

The template

The template is the file which will call your javascript application. It is responsible to load the needed javascripts and stylesheets. This file is a template which will be rendered by any template engine supported by the opencomponents registry. You have access to all parameters provided by the oc-server.js file.

1
2
3
<img src="{{staticPath}}img/logo.png" />

<div>Hello {{name}}</div>

The server.js

The server.js will be processed by opencomponents registry. You have access to all plugins registered in the registry and code executed here is not exposed to public domain.

The server file has access to all parameters passed to your component from the application who is including it.

The server.js file should look as the next one:

1
2
3
4
5
6
7
8
9
export const data = (context, callback) => {
  const { name } = context.params;
  const { staticPath } = context;

  callback(null, {
    name,
    staticPath
  });
};

Deployment

OpenComponents makes use of semver philosofy for the deployment process. Each time you want to publish a new version of a components you need to increase the version of your component running npm version patch|minor|major. When your component will be published it will be accessible in the registry url (i.e http://your-registry.com/my-component/1.2) also the latest version can be accessed if you don’t specify a version in the URL.

The package.json configuration

The basic working version of package.json should loooks like as follows:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
{
  "name": "hello-world",
  "description": "description of my hello-world component",
  "version": "1.0.0",
  "oc": {
    "files": {
      "data": "server.js",
      "template": {
        "src": "template.hbs",
        "type": "oc-template-handlebars"
      }
    }
  },
  "devDependencies": {
    "oc-template-handlebars-compiler": "6.0.8"
  }
}

You can check the complete list of oc options here.

Manual deployment

1
2
oc registry add http://my-registry.on.herokuapp.com/
oc publish my-first-component --username=YOURVALUEHERE --password=YOURVALUEHERE

Gitlab-ci deployment

1
2
3
4
5
6
7
8
9
10
11
12
13
14
stages:
- deploy

deploy:
  stage: deploy
  image: ciricihq/node:lts-oc
  only:
  - tags
  - triggers
  script:
  - yarn
  - yarn build
  - oc registry add https://components.registry.com
  - NODE_ENV=production oc publish --username=nobody --password=1234 .

Include your new opencomponent into a website

You can render opencomponent in frontend or backend. The easier way is using frontend. To do so just add the <oc-component> tag and the oc-client script in your page.

The minimal working example should look like this:

1
2
3
4
5
6
7
8
9
10
11
<html>
  <head></head>
  <body>
    <oc-component
      href="//my-components-registry.mydomain.com/hello-world/1.X.X"
    ></oc-component>
    <script
      src="//my-components-registry.mydomain.com/oc-client/client.js"
    ></script>
  </body>
</html>

NOTE: You can provide component parameters using URL querystring in the component href.
NOTE: The previous example won’t work if you open directly the file in your browser. You should serve the html using a webserver. I.e serve.

Comments

⬆︎TOP