Preparing Reactjs app to be deployed to OpenComponents registry

Prepare opencomponents needed files

In order to use a React.js application as a opencomponent you have to create two files, the oc-server.js and template.html.

The oc-server.js

The oc-server.js will be processed by opencomponent 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 oc-server.js file should look as the next one:

1
2
3
4
5
6
7
module.exports.data = function (context, callback) {
  callback(null, {
    staticPath: context.staticPath,
    params: context.params,
    paramsStr: JSON.stringify(params)
  });
};

Also you can use plugins and add yout params defaults or any logic you need:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
module.exports.data = function (context, callback) {
  var defaultParameters = {
    disableSteps: false,
    disableResumeFirstPayment: false,
    disableResumeMonthly: false,
    disableEmails: false
  }

  context.plugins.getSettings('feeswidget_settings', context.params.apikey, function (err, settings) {
    // If there's an error we'll load the widget anyway to keep backwards compatibility
    if (err) {
      const params = Object.assign(defaultParameters, context.params)
      return callback(null, {
        staticPath: context.staticPath,
        params: params,
        paramsStr: JSON.stringify(params)
      })
    }

    const params = Object.assign(defaultParameters, settings, context.params)

    callback(null, {
      staticPath: context.staticPath,
      params: params,
      paramsStr: JSON.stringify(params)
    })
  })
}

Create yours in a specific folder in the project root. I.e ./oc

The template.html

The template.html is the file which will call the reactjs application. It is responsible to load the needed javascripts and stylesheets. Its functionality should be equivalent to the react’s included index.html. 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.

An example template instantiating a UMD build reactjs application should look as follows (using handlebars template engine):

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
<script>
  //Following is to guarantee this works if either this is client-side rendered
  // or server-side rendered - so if the oc namespace is available already or not
  window.oc = window.oc || {};
  oc.cmd = oc.cmd || [];

  // You have access here to built javascript uploaded by opencomponents to S3
  var mainScript = "{{ staticPath }}build/static/js/main.js";

  // Here you require the 2 files in the right order
  oc.cmd.push(function(){
    oc.require(mainScript, function(){

    {{#if params.selector }}
    // Instantiating widget, passing the selector where
    // you want to render it, and som parameters to configure it
        YourWidget.default.Signup.new({{{ paramsStr }}}).render();
    {{/if}}
    });

  });
</script>

{{#if params.googleMapsApikey }}
<script type="text/javascript" src="https://maps.googleapis.com/maps/api/js?language=es&key={{params.googleMapsApikey}}&libraries=places"></script>
{{/if}}

Note the staticPath definition to load the main.js file. This variable is provided by the server to be able to reach the deployed files of your component.

Create yours in the same folder of the oc-server.js . I.e ./oc

Setting up opencomponent settings in package.json

In order to tell to opencomponents where should go for this files you have to add some configurations in package.json.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
...
"oc": {
  "minify": false,
  "files": {
    "template": {
      "type": "handlebars",
      "src": "oc/template.html"
    },
    "static": [
      "build/static"
    ],
    "data": "oc/server.js"
  }
}
...

NOTE: For react.js already built application it’s important to disable opencomponents minify which can break your application.

NOTE: Due how opencomponents deployment works you should move all the dependencies to devDependencies. If not, oc will try to require all them again and it will fail to deploy your component.

All oc’s package.json possible configurations can be checked here.

Setting up Gitlab-ci to automatically deploy your component when a new tag (version) is created in git

You want to automatize the deployment process any time you publish new version of your react app. So let’s tell gitlab-ci to do the dirty work for us.
In resume the steps to deploy our component are:

  • Test: We should ensure our new version is stable enough to be deployed.
  • Build: When we know the application is stable enough we can proceed to build process which will generate the production js to be consumed by the component.
  • Deploy: Upload the application to our opencomponents registry

Your .gitlab-ci.yml should look as follows:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
stages:
- test
- deploy

test:
  stage: test
  image: node
  script:
  - yarn
  - yarn test

deploy:
  stage: deploy
  image: ciricihq/node:lts-oc
  only:
  - tags
  - triggers
  script:
  - yarn
  - yarn build
  - oc registry add https://your-registry-url.com
  - 'NODE_ENV=production oc publish . --username adminusername --password $REGISTRY_PASSWORD'

Note that publish ask for $REGISTRY_PASSWORD. You should ask your administrator the registry password and set up in your gitlab-ci.

Locally testing your component

  1. Move the component to a folder without any other component
  2. Enter the component folder and execute yarn, and then yarn build
  3. Go back to parent folder and execute NODE_ENV=production oc dev .

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
<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>
<html>

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