@rainforestpay/frontend-standards

Rainforest Frontend Standards

Introduction

We want to apply a consistent set of standards across all frontend projects. In general, the stack in use consists of:

• Vue
• TypeScript
• JavaScript

Ideally, we don't want to duplicate these settings across repositories, but would instead prefer to maintain them in a central location. This frontend-standards repo aims to be that central location.

Caveats

As of this writing, we're only sharing the ESLint and Prettier configuration files.

Ultimately, it'd be good to share the scripts and the dependencies, but that was more involved than we wanted to get with this initial implementation.

Publishing and Access

As of this writing, all @rainforestpay packages live at npmjs.org.

All packages (thus far) have been public. There is nothing sensitive in them, so it's fine for them to be publicly-accessible.

Because they're publicly accessible, we can minimize setup steps for other engineers, GitLab CI/CD pipelines, etc.

To publish a new version

• First, create an npmjs.org access token of type Publish
• Take note of the token value
• Configure your access token on your local machine:

  npm config set _authToken=[your access token value here]
  

• To publish a new version of the package, run:

  yarn publish --access public
  

NOTE: Alternatively, you can create a token from the command line.

Note that you will see console output similar to:

$ yarn publish --access public                                      
yarn publish v1.22.19
[1/4] Bumping version...
info Current version: 1.0.3
question New version: 1.0.4
[2/4] Logging in...
[3/4] Publishing...
info Two factor authentication enabled.
question npm one-time password: [REDACTED]
success Published.
[4/4] Revoking token...
info Not revoking login token, specified via config file.
✨  Done in 9.27s.

How to use

To use our shared frontend standards in another repository, run:

yarn add -D @rainforestpay/frontend-standards

Once installed, you can simply use and extend the eslint-config and prettier-config files as needed.

For example, your project's .eslintrc.js would look like:

const sharedEslintConfig = require('@rainforestpay/frontend-standards/eslint-config');

module.exports = {
    ...sharedEslintConfig,
    // Add custom settings here.
};

Similarly, your Prettier config at .prettierrc.js would look like:

const sharedPrettierConfig = require('@rainforestpay/frontend-standards/prettier-config');

module.exports = {
    ...sharedPrettierConfig,
    // Add custom settings here.
};

By using the spread operator, you can extend and change settings as needed within your specific project.

Dependencies

Note the peerDependencies section of package.json in this repository. In general, it reflects the dependencies needed to use these shared configurations.

You will need to install these dependencies in your project. For example:

yarn add -D \
    @rushstack/eslint-patch \
    @trivago/prettier-plugin-sort-imports \
    @typescript-eslint/parser \
    @vue/eslint-config-typescript \
    eslint \
    eslint-config-prettier \
    eslint-plugin-prettier-vue \
    eslint-plugin-vue \
    prettier

Take note of any warnings from your output, such as:

warning " > @rainforestpay/frontend-standards@1.0.0" has incorrect peer dependency "@typescript-eslint/parser@^5.36.2".
warning " > @rainforestpay/frontend-standards@1.0.0" has incorrect peer dependency "@vue/eslint-config-typescript@^11.0.1".

In cases like these, you'll want to make sure you've installed the expected version of the package. You can do this like so:

yarn upgrade @typescript-eslint/parser
yarn upgrade @vue/eslint-config-typescript

Common scripts to setup

The following scripts can be added to your project's package.json. Of course, feel free to adjust them as needed.

"lint": "eslint \"src/**/*.{js,ts,vue}\"",
"lint-fix": "yarn lint-fix-prettier && yarn lint-fix-eslint",
"lint-fix-eslint": "eslint --fix \"src/**/*.{js,ts,vue}\"",
"lint-fix-prettier": "prettier -w \"src/**/*.{js,ts,vue}\""

yarn lint runs the linter, while yarn lint-fix automatically fixes the matching files with both ESLint and Prettier.

Making changes to frontend-standards

The process for updating frontend-standards is as follows:

1. Make the necessary changes to files in your clone of the repository
2. Increase the version value in package.json as neededs
   • Please follow semantic versioning when adjusting the version.
   • Is it only a minor, non-breaking change? If so, just increment the 1.0.x value.
   • Is it a new piece of functionality or requirement for projects that use this? Consider incrementing the minor version number, or 1.x.0.
   • Is there a big new addition or requirement? Consider incrementing the major version number, or x.0.0.
3. Commit and push the changes; open an MR if needed
4. Once approved, you need to publish an updated package to GitLab's Package Registry
   • You can follow the GitLab Package Registry instructions
   • Assuming you have performed Setting up authentication above, you can just run npm publish
   • You will see output similar to:

      ✗ npm publish
      npm notice 
      npm notice 📦  @rainforestpay/frontend-standards@1.0.1
      npm notice === Tarball Contents === 
      npm notice 5.7kB README.md         
      npm notice 3.1kB eslint-config.js  
      npm notice 871B  package.json      
      npm notice 354B  prettier-config.js
      npm notice 2.2kB yarn-error.log    
      npm notice === Tarball Details === 
      npm notice name:          @rainforestpay/frontend-standards
      npm notice version:       1.0.1                                   
      npm notice filename:      @rainforestpay/frontend-standards-1.0.1.tgz
      npm notice package size:  4.2 kB                                  
      npm notice unpacked size: 12.3 kB                                 
      npm notice shasum:        e112e4ca88a8983e8371b3964e56c8935f955f57
      npm notice integrity:     sha512-ijc+qOP0IgAZN[...]/iZandhkNkZmA==
      npm notice total files:   5                                       
      npm notice 
      npm notice Publishing to https://gitlab.com/api/v4/projects/39384073/packages/npm/
      + @rainforestpay/frontend-standards@1.0.1
     

5. Finally, in the projects that need to use the new changes, run:

   yarn upgrade @rainforestpay/frontend-standards
   

   Your output will appears similar to below:

   yarn upgrade @rainforestpay/frontend-standards
   yarn upgrade v1.22.19
   [1/4] 🔍  Resolving packages...
   [2/4] 🚚  Fetching packages...
   [3/4] 🔗  Linking dependencies...
   [4/4] 🔨  Rebuilding all packages...
   success Saved lockfile.
   success Saved 1 new dependency.
   info Direct dependencies
   └─ @rainforestpay/frontend-standards@1.0.1 <---- NEW PACKAGE VERSION NUMBER
   info All dependencies
   └─ @rainforestpay/frontend-standards@1.0.1
   ✨  Done in 7.34s.