Motivation

Make Micro-Services Consistent

With the growing amount of toolings and ci services we need to use to create a production-grade codebase, the difficulty of managing configs across multiple repos is increasing. Tools like lerna is easy to result in a heavy monorepo and doesn't help to manage apps in different teams, plus a lot of Github integrations are optmised on a repo level. ncm is created to manage packages (components or apps) in separate repos, keeping the repos light-weight for swift development experience, enjoying the benefits of micro-services while not sacarificing build layer consistency.

Best-Practices In Code

ncm is built to look after the whole lifecycle of a package (component or app) systematically from creation to development, maintainance and deprecation. We want to make it very easy to create and maintain a production-grade packages. It is built and released following @opbi/principles.

How to Use

Install

yarn add @opbi/ncm -D

Before We Start

It assumes that you've git installed and setup with SSH keys to clone public and private repo in your scope.

Also to setup Github repo it requires you to provide a Github Access Token. You can create it on Github Settings page, and it requires repo:private access if you want to create private repo. When you have got the access token, you can store it in MacOS Keychain, and export it to NCM_GITHUB_ACCESS_TOKEN in your shell profile.

Setup New Component

ncm init  # you will be asked a list of questions like `npm init` or `yarn init`
# check .ncmrc.yml, add more details if necessary
ncm setup # it will create dotfiles based on preset and custom config as well as create GitHub repo
make install
# all set, start development 🎉

Currently it needs manual clicks to setup project in CI and code quality reports, this can be automated by running a worker triggered by GitHub hook.

Use Custom Template Repo

By default, ncm uses ncm-preset-[component.type] as the config file template, which is a repo that is constantly being updated and tested to maintain fresh high-quality build config standards. In case you prefer use your own preset, you just need to add your Github repo to .ncmrc.yml under component.template.

---
component:
  type: package # [package, service, app, job]
  template: opbi/ncm-preset-package  # default to this repo for [package]

Update Config Files

ncm config # it will replace the dotfiles with latest ones from the template

Fetch Dotenv Secrets

ncm .env -s <path-of-secrets-in-vault> # it will write secrets in vault to .env file

Upgrade Node Version [TODO]

ncm upgrade node # this will upgrade node version via nvm, update .ncmrc.yml, .nvmrc, babel.config.js, package.json, .circleci/config.yml

Develop A Component [TODO]

As ncm is created to manage the whole lifecycle of a component in microservice system, workflow automation is included in the scope. Workflow logics over lifecycles of different types of components defined in @opbi/practices would be materialised as automation in ncm. For example, when the following command in a package component, it would move the Trello card to development stage, create a new branch with preset naming convention, open a PR, link the PR to the Trello Card.

ncm start #TrelloCard

Repo Specific Config [TODO]

Add repo specific configuration to .ncmrc.yml to overwrite certain rules in the common dotfiles from the template. ncm will pick up the settings and inject them into the config files based on dotfiles from template.

For example, if you want to use a specific babel-plugin that is not included in the template, then you can add the devDependency, and set .ncmrc.yml like the following, ncm will then pick up the config.babel and merge it into babel.config.js, the structure of config.babel would be exactly the same as .babelrc, except that it more yamlful.

---
component:
  type: package
config:
  babel:
    plugins:
      - @babel/plugin-of-your-choice
  gitbook:
    disabled: true

Rename A Component [TODO]

ncm rename # this would rename the dir, GitHub Repo, package.json, deployment service, etc.

Archive A Component [TODO]

ncm archive # this will archive the repo, teardown all services, deprecate component/service/app

Glossary

Component

We use component to refer to a complete codebase unit that serves a specific function in a micro-service system, which could be in the type of [app, service, job, package, etc.]. For more details, please refer to @opbi/glossary.

Inspiration

• helm
• mrm
• kyt
• yarn

License

MIT