Klient OpenStack

Introduction
Installation
Usage
Development
- Stack
- Contributions
Maintainability
- Stack
- Github actions
Common questions

Introduction

This repository is a Typescript template designed for creating JS open source projects hosted on Github, including all the necessary tools for development, maintenance, and publishing a package to an NPM registry. With pre-configured Github actions, issue/PR templates, you can easily manage the entire workflow of your project using the best practices known to date.

Features

Start with an open-source repository containing an MIT license, a code of conduct, a contribution guide, based on good practices.
Produce clean code with Typescript (es6), Prettier, ESLint (Airbnb rules), and Jest. All pre-configured.
Maintain a clean commit history by using Coventional commit naming rules.
Use git hooks for checking added files and lint commit message before commit with husky
Make your package compatible with CommonJS and ES modules.
Begin with complete CI tests applied to every commit, runnable on all Node versions.
Create any release+tag using Release-It with an automatically generated changelog, directly from the Github Actions interface (with pre-release support : alpha, beta, RC).
Publish/unpublish a package version to NPM Registry, directly from the Github Actions interface.
Update your dependencies with npm-check-updates, directly from the Github Actions interface.
Upgrade to next open-stack version by using open-stack cli, directly from the Github Actions interface.
Fast Github actions with dependencies cache management.
Take advantage of included issue templates & PR template adapted for JS projects.
Display a code coverage badge (no Gist or Github page required).
Adjust the repository defaults to suit your needs.
Use all features with Github Free.

Installation

Duplicate repository

This repository is a repository template, which means that you can duplicate it from the Github interface. This will copy the files and the structure, creating only one commit (the initial commit). (see documentation). Alternatively, you can directly use open-stack-cli for create new project. The create command will configure your project as described on 2.b, that means you can directly go to 3. if you create project with cli.
Update stack files

a) Clone project or open a codespace on main branch.

b) run npm install and then npm run configure

c) Commit your changes (with commit message like chore(stack): configure)
Configure Github repository for creating release and tag

Go to your repository Settings > Actions > General > Workflow permissions > Enable GITHUB_TOKEN read and write permissions. (see documentation). We strongly recommand you to configure also a personnal access token and set it in repository Settings > Secrets and variables > Actions > Secrets > New repository secret, and define the secret PAT (containing the generated PAT) (see documentation).
Configure Github repository for publishing package

a) Go to your NPM registry and create a token with authorized publish action. (See documentation)

b) Go to your repository Settings > Secrets and variables > Actions > Secrets > New repository secret, and define the secret NPM_TOKEN with the token you have configured. (see documentation)

All is configured to start development, validate code in CI, create Github release and tag, and then publish versions of your package just with Github actions !

Usage

#
# <--- CREATE NEW PROJECT WITH CLI --->
#

# Install open-stack-cli globally
$ npm install -g @klient/open-stack-cli

# Create new project based on open-stack template
$ npx open-stack create my-project




#
# <--- CREATE NEW PROJECT WITH CLONE --->
#

# Clone open-stack repository
$ git clone https://github.com/klientjs/open-stack.git my-project && cd my-project

# Reset git history and create initial commit
$ rm -rf .git && git init && git add . && git commit -m "initial commit"

# Install project dependencies (including open-stack cli)
$ npm install

# Remove open-stack content and initialize files for your project (this is using cli)
# It will ask you few questions for initializing files. This script will be removed automatically.
$ npm run configure

# Commit changes, it will run commit checks (see git hooks below)
$ git add . && git commit -m "chore(stack): configure"




#
# <--- OPTIONALLY INSTALL AND CONFIGURE EXTERNAL LIBS (experimental) --->
#

# Initialize a web application project based on React library (using react-scripts)
# (Should be run in a fresh blank project, after npm run configure, see open-stack-cli doc)
$ npx open-stack setup react-app

# Commit changes related to react-app setup step
$ git add . && git commit -m "chore(stack): setup react-app"

# Then, work with commands provided by react-scripts
$ npm run start
$ npm run build
$ npm run test
$ npm run eject




#
# <--- INCLUDED SCRIPTS --->
#

# [ANALYZE CODE]
#
# These commands are used to validate code in CI and in git hooks
#
$ npm run prettier
$ npm run lint
$ npm test
#
# Alternatively
# npm run check


# [FIX CODE]
#
# Fix your files as much as possible with prettier and eslint
# (Following commands MUST be lunched before every git commit !)
#
$ npm run prettier:fix
$ npm run lint:fix
$ npm test
#
# Alternatively
# npm run pre-commit


# [BUILD CODE]
#
# Build dist files with tsc (with targets CommonJS & ESModule)
# It will create final typescript and javacript content in separated files.
#
$ npm run dist:cjs
$ npm run dist:esm
#
# Alternatively
# npm run dist


# [RELEASE CODE]
#
# Release a new version of your project using Release-it, this will :
#   - run project test suites
#   - update coverage badge using npm run coverage:badge
#   - build the dist folder using npm run dist
#   - update package.json according to version type specified
#   - create or update a changelog file
#   - commit changes
#   - create a new tag on previous commit
#   - push and then create Github release
# (Can be used directly from Gihub actions)
#
$ npm run release -- --increment=minor


# [UPDATE DEPENDENCIES]
#
# Update project dependencies using npm-check-updates
# The following command will attempts to update 
# each dependencies and check validity by running tests before and after update.
# (Can be used directly from Gihub actions, changes are submitted in a PR)
#
$ npm run update:dependencies -- --target=minor --doctor --upgrade


# [UPDATE OPEN-STACK FILES]
#
# Update open-stack files by sync changes with specified version (updated by cli)
# (Can be used directly from Gihub actions, changes are submitted in a PR)
#
$ npm run update:open-stack -- --to=1.5.0 --verbose --report update_report.md


# [OPEN TEST COVERAGE REPORT]
#
# Open html coverage report in a browser using "open" binary (must be locally available)
#
$ npm run coverage:open
#
# Alternatively, you can expose http port using http-server for consulting html report
# It's useful if you are using distant environment such as codespace
#
$ npm run coverage:serve -- --port 8888


# [CREATE COVERAGE BADGE]
#
# Create the coverage badge based on report generated on last npm test (generated by cli)
# (Mainly used for release process)
$ npm run coverage:badge

Development

Stack

Contributions

To take full advantage of all the features offered by this repository, you must follow the conventions adopted by it. This mainly happens during development, using commit messages based on Conventionnal commits rules. With this specific formatting, automatic management of a beautiful changelog is made possible. We recommend that you use these rules as much as possible, to make the most complete changelog for each release.

Issues and PR

This repository includes 4 predefined issue templates (inspired from axios repository), allowing the community to help you in the development of your package :

All of these templates are defined with fields that are useful for JavaScript projects (such as the version of the used browser, for example).

This repository also contains a simple PR template useful to get dev context related to a PR.

You are free to add, modify or delete these templates as you need (see github folder).

Git hooks

By default, 2 git hooks are setup by Husky package when "npm install" is launched : one for testing code changes, and another for lint commit message. It can be disabled on need. See husky documentation for more informations.

# Clone a project based on open-stack template
$ git clone https://github.com/klientjs/example.git && cd example

# Just install, it will initialize git hooks with Husky
$ npm install

# ... Make changes in your IDE ...
#
# Commit your changes. By using git hooks, this will :
#   - check files with eslint, prettier and Jest
#   - check commit message using @commitlint/config-conventional
#
$ git add . && git commit -m "feat: change the world just with code"

Guides

Maintainability

This repository comes with a pre-defined Github config based on current best practices for node package management. You can quickly start developing a project while following efficient workflows to produce the best possible code. The Github actions included in this template will allow you to manage the whole lifecycle of your project as below :

Stable version  >  Development  >  Testing  >  Release  >  Publication

All of these steps are managed by Github actions, which means that you will only have to click a few buttons to trigger the creation of a new release, as well as its publication.

Stack

Github actions

The Github actions mentioned below will allow you to manage your package's entire workflow, from development to publication. They should be naturally launched in the order in which they are defined below :

PR are submitted and automatically tested in CI jobs (all commits).
Branches are merged in main version branch
The main branch is ahead by several commits and you want to release a new version of your code.
Finally you publish your new revision (created in the previous step) to NPM registry.

You can find following actions in "Actions" tab of your repository.

Code analysis

This action is launched on every commit to validate if pushed code is valid regardless of project standard :

npm run lint : Run check with ESLint
npm run prettier : Run check with Prettier
npm run test : Run tests with Jest
npm run dist : Try to compile dist files

Note that npm audit is run but the process will continue even if audit is not satisfying.

Events

push
pull_request (reopened)
workflow_dispatch (manual run)

Available options

Node version

Create a new tag and Github release

This action should be launched when you have decided to release a new version of your code. It will have the following effects :

Test the code one last time
Modify the version of your package in the package.json file, according to specified release type.
Automatically create or update a CHANGELOG file based on your commit history.
Compile the src files to the dist folder.
Update the code coverage badge.
Push all modifications on selected branch with a commit specifically designed for previous updates.
Create a tag on the last previously created commit.
Create a Github release containing the same information added to the changelog file for the previously created tag.

Events

workflow_dispatch (manual run)

Available options

Release type : patch | minor | major [required]
Pre release : alpha | beta | rc
Npm audit : y/n
Dry mode : y/n
Node version

Publish a tag to NPM registry

This action should be launched when you want to publish a release on the NPM registry. You do not need to specify the version to publish as it will be extracted from the package.json of the selected branch. Therefore, we recommend always selecting a tag rather than a branch to launch this action. The publication takes place in several steps:

Publication using "npm publish"
Attempting to install the published version in a blank project.

Events

workflow_dispatch (manual run)

Available options

NPM tag : latest | alpha | beta | rc [required]
Dry mode : y/n
Node version

Dangerously unpublish a tag from NPM registry

If you launch this action, your package will be unpublished from the NPM registry. Be careful because the unpublished version will probably never be able to be republished. Therefore, use this action only in cases of extreme necessity.

Events

workflow_dispatch (manual run)

Available options

The target version [required]
Dry mode : y/n
Node version

Update package dependencies

This action allows you to manage updates of your project's dependencies using npm-check-updates. The changes made on package.json will be committed to a branch named actions/dependencies-update with an uniq pull request, updated if already exists.

The "dry" mode allows you to simulate multiple version update scenarios. When you are satisfied, relaunch the action with same options but with dry mode disabled. Then, you can check the PR and merge it.

If doctor mode is enabled, tests are run before and after the update to ensure that everything has gone smoothly. If not, npm-check-updates will attempt to update each dependency to identify which ones are problematic. It will still submit a PR with the dependencies that are updatable. The packages in failure state are listed in the job output.

You can make this process auto by configuring schedule event in workflow file.

Events

workflow_dispatch (manual run)

Available options

Target versions (--target) [required]
Dependencies section (--dep)
Filter package pattern (--filter)
Reject package pattern (--reject)
Doctor mode (--doctor)
Npm audit : y/n
Dry mode : y/n (do not commit and open PR)
Node version

See npm-check-update options documentation

Update OpenStack template files

This action will allow you to update your repository files with open-stack template, specifying a version to upgrade. This will be useful for updating included tools to support future best practices. This action consists of several steps:

Verify the stability of the provided branch: The branch must be clean and pass tests.
Clone the latest known version of the template you used: The version number will be retrieved from the package.json file.
Clone the next version of the template you want to use.
Update your package.json: The scripts, devDependencies, keys will attempt to be synchronized by comparing the state of your file with the previous and new versions.
Update the files that need to be synchronized (in manual mode, you can specify files you want to sync)
Update the code syntax: Prettier and ESLint will be run.
A complete report will be generated with any conflicts that may arise.
A Pull Request will be opened containing the modifications and the report.

Unfortunately, this action is not magic and has its limitations. Your project may have evolved and you may have modified the same file as a file in the future version that needs to be synchronized. In this particular case, the file cannot be updated automatically. You will need to review the various conflicts in the update report and compare different file versions to make the necessary modifications manually. Note that code analysis is not run after the update. This must be done automatically on the Pull Request if you have configured a PAT; otherwise, you will need to run the tests manually.

You can make this process auto by configuring schedule event in workflow file.

Events

workflow_dispatch (manual run)

Available options

Target version [required]
Dry mode : y/n (do not commit and open PR)
Node version

Auto cleanup PR caches

This action is launched after a PR is closed to cleanup caches related to target branch.

Events

pull_request (closed)

Common questions

How to change default node version used by Github actions

By default, all Github jobs run with Node version 16.x. You can modify the default Node version by defining the NODE_VERSION variable in repository Settings > Secrets and variables > Actions > Variables > New repository variables. (For example NODE_VERSION=14.x)

Note: The Node version to use can also be defined individually when launching a Github action manually.

How to change default registry url used by Github actions

The default registry url used is https://registry.npmjs.org. You can modify it by defining the REGISTRY_URL variable in repository Settings > Secrets and variables > Actions > Variables > New repository variables.

How to enable dependencies caching in Github actions

You can enable cache usage it by defining the CACHE_DEPENDENCIES variable with 1 value in repository Settings > Secrets and variables > Actions > Variables > New repository variables.

How to specify name of branch created by Github actions

You can change default branches naming created by Github actions, by defining the UPDATE_STACK_BRANCH (for stack update action) and UPDATE_DEPENDENCIES_BRANCH (for dependencies update) variables with branch name you want in repository Settings > Secrets and variables > Actions > Variables > New repository variables.

How to install React for making web app

You can use the experimental command "setup" to add react (and react-scripts) in a fresh blank open-stack project (after run npm run configure), as create-react-app does.

Caution : It will update config files like jest.config.ts, .eslintrc, tsconfig.json, package.json... These files can be potentially in conflict if you want to upgrade your open-stack files later.

$ cd path/to/your/project
$ npx open-stack setup react-app

How to install React for making components library

You can use the experimental command "setup" to add React implementation (jsx support, no react-scripts) in a project which will be published to npm registry.

$ cd path/to/your/project
$ npx open-stack setup react