addingDependenciesTutorial.md

Tutorial adding npm dependencies

Foreman manage npm dependencies with a seperate project called @theforeman/vendor which responsible to deliver 3rd-party modules to foreman and its plugins. Foreman and its plugins consumes @theforeman/vendor project from npm in development and from rpm in production.

@theforeman/vendor lives inside a monorepo together with other foreman javascript tools in a project called foreman-js.

In this tutorial you will learn how to add a new dependency to be available for foreman and it's plugins.

You will learn how to:

• Use forklift to spin up a machine with centos7-luna-devel enviorment
• Install and consume foreman-js from source.

Step 1: Use forklift to spin up a machine with centos7-luna-devel enviorment

1. Follow the forklift quick start guide and setup your forklift enviorment. It is recommended to use the vagrant-hostmanager and sshfs so you can easily reach your machine ip and filesystem.

2. Provision and run the centos7-luna-devel, it might take a while:

vagrant up centos7-luna-devel

3. Connect to your centos7-luna-devel machine:

vagrant ssh centos7-luna-devel

4. Now you should land in centos7-luna-devel home folder, you will find there the foreman folder containing foreman source code and folder for each plugins and it's source code. Go to the foreman folder and install dependencies:

cd foreman
bundle install
npm install

Step 2: Fork and Install foreman-js

Fork, clone and install foreman-js to your homefolder (cd ~). See contributing project setup

Step 3: Add your dependency to the @theforeman/vendor-core

1. Go to foreman-js project and create a branch:

cd ~/foreman-js
git checkout -b feat/add-patternfly-react-icons

2. Go to @theforeman/vendor-core sub package in foreman-js and install your dependency:

cd ~/foreman-js/packages/vendor-core
npm install --save @patternfly/react-icons

3. Open the packages/vendor-core/lib/modules.js in your editor and add your dependencies there. This step will is required so webpack will produce a bundled javascript together with your new installed library exposed to foreman and foreman plugins:

--- a/packages/vendor-core/lib/modules.js
+++ b/packages/vendor-core/lib/modules.js
@@ -24,6 +24,7 @@ module.exports = [
   'react-loading-skeleton',
   'patternfly-react',
   'patternfly-react-extensions',
+  '@patternfly/react-icons',
   'react-redux',
   'redux',
   'redux-form',

4. Build foreman-js with your changes:

cd ~/foreman-js
npm run build

This script will create a ./dist folder with the newly created bundled javascripts. Read more about building @theforeman/vendor.

NOTICE: You will need to run npm run build after every code change to make them available

Step 4: Use foreman-js from source in foreman

Default, foreman-js installed from the npm registry, we will want to change it to consume the local foreman-js version so we will install foreman-js from source.

Link foreman-js to foreman, go to foreman folder and run:

npm run foreman-js:link

NOTICE: running npm install in foreman will replace the linked version of foreman-js with the npm version.

Step 5: Use your dependency in foreman

Happy Hacking 🎉: Start hacking and creating code changes.

You can use your dependency in foreman or in a foreman plugin now:

import React from 'react';
import { TimesIcon } from '@patternfly/react-icons';

const closeIcon = <TimesIcon />;

Step 6: Commiting your changes to foreman-js and creating a pull request

foreman-js uses commitizen to create commit messages so it can automatically create semantic releases.

1. Commit your changes to foreman-js

git add .
npm run commit
# answer the questions

2. Push your changes:

git push origin feat/add-patternfly-react-icons

3. Open the foreman-js on Github, then click “Compare & pull request”.

Step 7: Publish your changes to a temporary version in npm

We will want to consume [foreamn-js] from npm so users won't need to install [foreamn-js] locally in order to test your changes. It will also make your [foreamn-js] sub-packages available when running CI pipelines.

npm run lerna -- version prerelease --preid pficons