In this blog, we'll look into how we build, release, and maintain these packagesto support our product development cycles. Let's take a look at some of thesekey packages.

neeto-cist

neeto-cist contains essential pureutility functions and forms the backbone of our development framework.

neeto-ui

neeto-ui is the foundational designstructure for our Neeto products. It contains basic-level components likeButtons, Input fields, etc.

neeto-molecules

Built on top of neeto-ui, the neeto-molecules package houses reusable UIelements like a login page, settings page, sidebars etc. It simplifies thecreation of consistent user experiences across Neeto products.

neeto-commons

neeto-commons store crucial elements such as initializers, constants, hooksand configurations shared across our entire product range. We wrote in greatdetail about thechallenges we faced while building neeto-commons.

Let's look at how we build, release, and maintain these packages.

Build

In general we use Babel to transpile andRollup to bundle with some exceptions.

Let's look at our standard build configuration.

import peerDepsExternal from "rollup-plugin-peer-deps-external";import svgr from "@svgr/rollup";import babel from "@rollup/plugin-babel";import resolve from "@rollup/plugin-node-resolve";import alias from "@rollup/plugin-alias";import json from "@rollup/plugin-json";import commonjs from "@rollup/plugin-commonjs";import styles from "rollup-plugin-styles";import aliases from "./aliases";export default {  input: {    Component1: "src/components/Component1",    Component2: "src/components/Component2",    //... rest of the entry points  },  output: ["esm", "cjs"].map(format => ({    format,    sourcemap: true,    //... other options  })),  plugins: [    // To automatically externalize peerDependencies in a Rollup bundle.    peerDepsExternal(),    // Inline any svg files    svgr(),    // To integrate Rollup and Babel.    babel({      exclude: "node_modules/**",      babelHelpers: "runtime",    }),    // To use third party modules from node_modules    resolve({ extensions: [".js", ".jsx", ".svg"] }),    // To define aliases while bundling package.    alias({ entries: aliases }),    // To convert .json files to ES6 modules.    json(),    // To convert CommonJS modules to ES6.    commonjs(),    // Handle styles    styles({      minimize: true,      extensions: [".css", ".scss", ".min.css"],    }),  ],};

When dealing with multiple entry points, passing an array of input is a commonmistake people make. The problem with an input array is that it will beduplicated if there is shared code. So, the best approach here is to pass akey-value object. This way, Rollup will create separate files for shared codeand reuse them everywhere.

Looking at the output, notice that we built it for CommonJS and ECMAScript.Even though we don't have any Node.js projects (we are mainly a Rails company),we still need the CommonJS format to run Jest tests and some scripts for buildand automation purposes.

When using Babel to transpile and Rollup to bundle, we ran into someconfiguration pain points.@rollup/plugin-babelplugin made the configuration far easier.@svgr/rollup converts normal svgfiles to react components.rollup-plugin-peer-deps-externalautomatically externalizes peer dependencies, keeping the bundle lean. Eventhough we don't have any CommonJS modules, it's better to add@rollup/plugin-commonjsso that if there is any deep in dependency rabbit hole.

Above is a simplified version of the Rollup configuration we use onneeto-cist, neeto-ui and neeto-molecules. We took a much simpler approachwhen building neeto-commons. The reason for abandoning bundling forneeto-commons is that within this package, we have a variety of commonly usedelements, such as components, hooks, initializers, constants, utils, etc., eachwith varying sizes and dependency requirements. If the host project only wantsto use a few simple util functions, we don't want them to be served with theentire bundle and need to install lots of dependencies.

Instead of serving everything from the root index.js, we useexports field in thepackage.json to specify which files can be imported by the host project. Belowis a sample of our exports.

"exports": {  "./react-utils": {    "import": "./react-utils/index.js",    "require": "./cjs/react-utils/index.js",    "types": "./react-utils.d.ts"  },  "./react-utils/*": {    "import": "./react-utils/*",    "require": "./cjs/react-utils/*",    "types": "./react-utils.d.ts"  },  "./utils": {    "import": "./utils/index.js",    "require": "./cjs/utils/index.js",    "types": "./utils.d.ts"  },  "./utils/*": {    "import": "./utils/*",    "require": "./cjs/utils/*",    "types": "./utils.d.ts"  },  "./initializers": {    "import": "./initializers/index.js",    "require": "./cjs/initializers/index.js",    "types": "./initializers.d.ts"  },  "./constants": {    "import": "./constants/index.js",    "require": "./cjs/constants/index.js",    "types": "./constants.d.ts"  }}

We export, for example, ./react-utils and ./react-utils/* because we want tosupport both import styles below.

import { useLocalStorage } from "neetocommons/react-utils";

import useLocalStorage from "neetocommons/react-utils/useLocalStorage";

We initially employed the first import style, but as we expanded, we recognizedthe necessity of supporting a more concise approach in smaller projects. Thissecond method involves importing solely the target file without additionaldependencies, significantly improving tree-shaking capabilities.

We also ensure we build for esm and cjs. Below is our simplified Babelconfig.

const defaultConfigurations = require("./defaultConfigurations");const alias = {  assets: "./src/assets",  neetocist: "@bigbinary/neeto-cist",  // others};module.exports = function (api) {  const config = defaultConfigurations(api);  config.sourceMaps = true;  config.plugins.push(    ["module-resolver", { root: ["./src"], alias }],    "inline-react-svg"  );  if (process.env.BABEL_MODE === "commonjs") {    config.overrides = [      {        presets: [["@babel/preset-env", { modules: "commonjs" }]],      },    ];  }  return config;};

When transpiling, we ensure aliases are correctly resolved, and if there are anySVG files, we inline them using theinline-react-svgplugin to make life easy for the host application. Below is our build script.

"scripts": {  "build:pre": "del-cli dist",  "build:es": "babel  --extensions \".js,.jsx\" src --out-dir=dist",  "build:cjs": "BABEL_MODE=commonjs babel  --extensions \".js,.jsx\" src --out-dir=dist/cjs",  "build:post": "node ./.scripts/post-build.mjs",  "build": "yarn build:pre && yarn build:es && yarn build:cjs && yarn build:post",}

Release

We did not want to create a release every time we merged a PR, and we alsodidn't want to manually release packages every time. Instead, we rely on GitHubLabels while running Github Actions to do the release.

We created three labels specifically for this purpose: patch, minor andmajor. As the names suggest, these labels help us create patch, minor andmajor versions. When we create a PR and want to do a release when merging,attach any of these labels, and GitHub Action will create releases accordingly.

name: "Create and publish releases"on:  pull_request:    branches:      - main    types: [closed]jobs:  release:    name: "Create Release"    runs-on: ubuntu-latest    if: >-      ${{ github.event.pull_request.merged == true && (      contains(github.event.pull_request.labels.*.name, 'patch') ||      contains(github.event.pull_request.labels.*.name, 'minor') ||      contains(github.event.pull_request.labels.*.name, 'major') ) }}

As evident from the code above, we trigger the Create and publish releasesGitHub Action only if any of the three aforementioned labels are present. Oncethat condition is met, we proceed to useyarn version toupdate the version.

- name: Bump the patch version and create a git tag on release  if: ${{ contains(github.event.pull_request.labels.*.name, 'patch') }}  run: yarn version --patch --no-git-tag-version- name: Bump the minor version and create a git tag on release  if: ${{ contains(github.event.pull_request.labels.*.name, 'minor') }}  run: yarn version --minor --no-git-tag-version- name: Bump the major version and create a git tag on release  if: ${{ contains(github.event.pull_request.labels.*.name, 'major') }}  run: yarn version --major --no-git-tag-version

Then, we extract changelogs from PR's title and description.

- name: Extract changelog  id: CHANGELOG  run: |    content=$(echo '${{ steps.PR.outputs.pr_body }}' | python3 -c 'import json; import sys; print(json.dumps(sys.stdin.read().partition("**Description**")[2].partition("**Checklist**")[0].strip()))')    echo "CHANGELOG=${content}" >> $GITHUB_ENV  shell: bash- name: Update Changelog  continue-on-error: true  uses: stefanzweifel/changelog-updater-action@v1  with:    latest-version: ${{ steps.package-version.outputs.version }}    release-notes: ${{ fromJson(env.CHANGELOG) }}

Finally, we publish the package to NPM.

- name: Publish the package on NPM  uses: JS-DevTools/npm-publish  with:    access: "public"    token: ${{ secrets.NPM_TOKEN }}

Maintenance

Now that the release is done, we need to propagate changes to our products. Forexample, we may have extracted an existing functionality from one of thepackages. Here is an example ofhow we standardized keyboard shortcuts in neetoand extracted out into a package. Now, the product team needs to remove thatfunctionality and use it from the package. Reaching out to each team and askingthem to replace it can be tedious, especially considering their priorities. Sowe came up with a plan to use customESLint rules to enforcethem, and we built eslint-plugin-neeto.

Let's look at a few examples of how we use eslint-plugin-neeto to enforcechanges on the product team.

There are some third-party packages we decided not to use when we found betteralternatives, and they even included our own. For example, bootstrap,moment.js, @bigbinary/neeto-utils, etc. To enforce this, we create ESLintrules called no-blacklisted-imports. This rule throws a lint error ifdevelopers attempt to commit changes that include these blacklisted imports.

Another example is that we moved higher-level constants, commonly utilizedacross various products, to neeto-commons. To enforce this, we created anESLint rule called use-common-constants. This rule detects any local importsand recommends importing from neeto-commons instead.

Here is another great blog post in which we explained the challenges we facedwhileadding translations and enforcing them using ESLint and Babel plugins.

These are just a few of the many ESLint and Babel plugins we created.

dependencies

The packages that are really needed for a project to function should be listedunder dependencies. These packages are always installed within that project.If the project is also a package, then these dependencies will also getinstalled in the host project that uses this package. Below are some commonexamples of what might go under dependencies.

 "dependencies": {   "dayjs": "1.11.1",   "immer": "^10.0.2",   "ramda": "^0.29.0",   "react": "^18.2.0" }

It's important to understand that the above packages do not always have to beunder dependencies. For example, if dayjs is needed only for development,deployment or testing purposes, It should not be listed under dependencies butrather in the devDependencies section, because dependencies will be bundledwith the main code, whereas devDependencies will not. So adding dependenciesthat are only used in development purposes under dependencies is unnecessaryand will increase the bundle size, affecting the performance of the application.

To add a package to dependencies section, simply run:

yarn add package-name

If we are shipping a package, all our dependencies are installed in the root ofhost projects node_modules. However, an exception occurs if the host projectalready has the same dependency but with a different version. In this scenario,that specific conflicting dependency will be installed within the node_modulesof our package to avoid version conflicts.

To explain it bit more lets say we have dayjs@1.0.0 as one of our dependencybut the host project uses 2.0.0. Then both versions will be installed, 2.0.0would be the in root node_modules and 1.0.0 in our package's node_modules.This way, our package can continue to use 1.0.0 while the host uses 2.0.0. Thefolder structure of that host will look something like below.

host-project-app src    index.js node_modules    react    dayjs    my-awesome-lib      node_modules        dayjs package.json README.md

devDependencies

Packages listed in devDependencies are used specifically for developmentpurposes. Any dependencies that do not go into our actual code are listed hereand not under dependencies. These dependencies won't be installed in aproduction environment or in a host project if our project acts as a package.Here are a few examples of what might belong in devDependencies.

 "devDependencies": {    "@babel/core": "^7.16.5",    "eslint": "^8.41.0",    "husky": "^7.0.4",    "jest": "27.5.1",    "prettier": "^2.8.8" }

Just like in dependencies, these packages may not always be indevDependencies. For example, if we are building a package that enhances Jesttests capabilities, then we should place jest under dependencies. Otherwiseour host project will break, because jest will not be installed in the hostproject.

To add a package to devDependencies section, simply run:

yarn add -D package-name

peerDependencies

peerDependencies are needed only if we are building a package. It allows hostto install any desired version unless we specify otherwise.

If we are using yarn as the package manager then peerDependencies are notinstalled automatically. We have to install manually, even in our own package.But there is a slight difference if you are using npm. Up to version 6 npmdoes not install peerDependencies automatically. However, this changes fromversion 7 onwards, as it will install peerDependencies automatically. So if weare using yarn or npm<=v6 and we have for example Storybook or Jest tests inour package project, then we have to install peerDependencies asdevDependencies(not as dependencies which defeats the purpose) as well.

 "devDependencies": {    "@babel/core": "^7.16.5",    "eslint": "^8.41.0",    "husky": "^7.0.4",    "jest": "27.5.1",    "prettier": "^2.8.8",    "dayjs": "1.11.1", } "peerDependencies": {    "dayjs": "latest" }

You might wonder about its purpose if manual installation is required. It servesas a means for our package project to specify essential dependencies requiredfor the package to function properly. Simultaneously, it grants control to thehost project to choose which versions to install.

To add a package to peerDependencies section, simply run:

yarn add --peer package-name

Now the tricky part is determining whether a particular dependency should gounder dependencies or peerDependencies. Unfortunately, there is no clearanswer here. But there are some questions we can ask ourselves to narrow it down.

1. If the specific version of the dependency is important for our package, thatis if using a different version breaks our package, then definitely we wantto place that package under dependencies.

   It is possible to place such dependencies under peerDependencies andspecify supported versions like below, but it is not a good practice.

 "peerDependencies": {    "dayjs": "1.2.0 || 1.5.1", }

2. If the dependency is a widely used package like react, better place itunder peerDependencyand ensure that our package works with differentversion of that dependency. This way, the dependency installed in the hostproject can be reused by our package without installing a separate version.
3. If we want to make changes to a dependency in a manner that impacts its usagewithin the host project, then place it under peerDependencies. Good exampleof this is, at neeto we have a package calledneeto-commons-frontend which extracts numerous common functionalitiesutilized across various products. One such functionality is our errorhandling system, for which we use anAxios interceptor. To ensure thefunctionality of this interceptor, it's crucial to apply this interceptor tothe same instance of Axios. To elaborate further, if we add Axios underdependencies in neeto-commons-frontend, but the host project uses adifferent Axios version, we will be making changes to the Axios instancethat's in node_modules of neeto-commons-frontend and not of the hostproject, means the functionality will not work on the host project.

Another rationale behind utilizing peerDependencies is its substantial impacton reducing the bundle size, particularly when bundling our package. Now if weare using Rollup, placing certain packages under peerDependencies doesn'tautomatically exclude them from the bundle. We need to explicitly specify thisin the Rollup configuration. This is achieved through the Rollup externalconfiguration option, where we provide a list of peerDependencies to beexcluded from the bundle. To simplify this process,rollup-plugin-peer-deps-external automates the inclusion of peerDependencieswithin the external configuration.

import peerDepsExternal from "rollup-plugin-peer-deps-external";export default {  plugins: [    // Preferably set as first plugin.    peerDepsExternal(),  ],};