ECMAScript Monorepo Template

Description

An opinionated template for Monorepo and best practices for ECMAScript eco-system technologies and projects.

This repo contains several sub-packages each demonstrating best practices in different ECMAScript related technology / scenario.

Sub-packages

• NPM JavaScript Library
• NPM TypeScript Library
• VSCode Simple Extension
• Vue Frontend with RPC calls

Requirements

• Yarn 1
• A Long Term Support version of node.js

How to use this repository

This repository is meant to be used as a starting point when creating a new monorepo project. The consumption process is currently a manual step by step guide.

Common Modifications

1. Clone/Copy/Download this repo.

2. Choose which of the sub-packages templates are relevant to you, and delete the others.

   • Note that some sub-packages depend on other sub-packages.

3. Change the name fields of the remaining packages/*/package.json files to fit your new project.

4. Delete the contents of the README.md files in both the root and the sub-packages.

5. Reset the version field in the lerna.json to your project's initial version number.

   • Normally 0.1.0 or 0.0.1.

6. Adjust coverage thresholds in the nyc.config.js.

   • By default, these are set to 100%.

7. Adjust CONTRIBUTING.md code coverage section.

   • To align with the coverage thresholds defined in the nyc.config.js.
   • Modify the cla-assistant link in the CONTRIBUTING.md legal section.

8. Update the Legal Related files (copyrights/notices/disclaimer).

   • ./.reuse/dep5
   • ./LICENSES
   • ./LICENSE

Modifications dependent on selected sub-packages.

1. If you kept VSCode extension templates, also adjust the displayName and publisher fields in their package.json files to fit your new project.

2. If you have not kept any VSCode extensions in your monorepo, remove the root vscode webpack config.

3. Adjust the circle-ci config.yml. There are three possible sections that may need to be removed (and their references):

   • deploy-npm --> if your project should not deploy any npm library to npmjs.com.
   • prepare-vsix and deploy-gh-releases --> if your project does not include VSCode extensions.

4. Adjust the .eslintrc.js configuration.

   • Remove overrides sections for no longer relevant file types:
     • ["*.ts"] --> if your monorepo does not contain any TypeScript sources (including .d.ts files).
     • ["*.vue"] --> if your monorepo does not contain any vue frontend projects.
   • Remove dev-depedencies from the root package.json
     • @typescript-eslint/* --> if your monorepo does not contain any TypeScript projects.
     • eslint-plugin-vue --> if your monorepo does not contain any vue frontend projects.

5. Adjust root TypeScript configurations.

   • Remove sub-project references that no longer exist from root ./tsconfig.json.
   • If there are no references left in this file, and you do not plan on adding TypeScript projects to your monorepo:
     • Delete the root ./tsconfig.json.
     • Delete the root ./tsconfig.base.json.
     • Remove the compile and compile:watch scripts from the root package.json.

6. Adjust lint-staged configurations.

   • Look for the lint-staged field and its keys in the root package.json.
   • Remove file patterns that your repo no longer contains (or is expected to contain).
     • For example if your monorepo does not contain a Vue frontend sub-package, you may remove the vue suffixes.

Final steps and testing dev flows.

In your terminal, navigate to root of the monorepo and:

1. execute yarn to update the yarn.lock file.
2. execute yarn run ci to test the full build flow.

You may now commit/push your new mono-repo template project to your new git repo and start coding.

How to obtain support

Please open an issue on Github.

Contributing

Contributions are most welcome.

• Please see the Contributing Guide for docs about development flows.
• Before implementing a major contribution please open an issue to discuss your contribution first.
• Last but not least, please consider how your changes would affect both the:
  • Root level dev flows (e.g needed adjustment for linting/formatting).
  • Root level usage/consumption instructions.