chonky-node-template

Featureful template for an open-source GitHub-based TypeScript-written Node package.

🏠 Homepage | 🗃 Repository | 📦 NPM | 📚 Documentation | 🐛 Issue Tracker

🪑 Table of Content

🧰 Features
🚦 Prerequisites
🚀 Usage
- Setup
- Workflow
- Scripts
🔮 Background
🤖 API
⏳ Changelog
🛠 Developing
🏗 Roadmap
🤝 Contributing
🧙 Contributors
⭐ Show your support
🐙 Community
👨‍🔧 Maintainers
📝 License

🧰 Features

Automated pipeline
- Automated CHANGELOG.md updated on PR to master branch (Semantic release)
- Release to NPM and GitHub on merge to master branch (Semantic release)
- Code analysis with CodeCov, CodeClimate, LGTM.
- Dependency management with DependaBot.
Security
- Security analysis with LGTM and Snyk.
- Secrets management.
- Verified commits from CI / CD enviroment.
Development
- Written with typescript
- Tests with jest
- Logging with debug
Effective collaboration
- Commit standardization and validation with Commitizen, Commitlint and Zappr.
- Formatting standardization with ESLint and prettier
- Standardized GitHub issues labels with automated setup.
- TypeDoc documentation
- Robust quality guards on pull requests ensured by mulitple bots and tests.
Community-focused
- Contributor recognition with AllContributors and Sourcer.io's Hall of Fame.
- Spectrum community for questions and discussions.
- Contributing guides.
- Community files like CONTRIBUTING, CODE_OF_CONDUCT, etc.
- Detailed README with readme-md-generator
- Follows initiatives like Make a README and Keep a CHANGELOG

🚦 Prerequisites

Environment

This template works in UNIX enviroment.

Packages

To run the setup steps, you will need following packages installed:

Services / Bots

The template uses following services or bots:

🚀 Usage

Setup

Steps to create a new project using this template.

Create new directory

mkdir <project-name> && cd <project-name>

Initialize git and create GitHub repo.
```
hub init && hub create
```

Copy this template into the dir (more on copying git repo w/o .git here)

mkdir temp && cd temp
git clone https://github.com/JuroOravec/chonky-node-template.git
mv {chonky-node-template/template/*,chonky-node-template/template/.*} ../
rm -rf chonky-node-template
cd ..

Make sure directories like temp, coverage, dist, docs/typedoc, node_modules are all empty

find ./temp -mindepth 1 -delete
find ./coverage -mindepth 1 -delete
find ./dist -mindepth 1 -delete
find ./docs/typedoc -mindepth 1 -delete
find ./node_modules -mindepth 1 -delete

Optionally set git aliases defined in ./scripts/git
```
sh scripts/set_git_aliases.sh
```
package.json
1. Fill in:
  1. Set name
  2. Set description
  3. Set homepage
  4. Set repository
  5. Set bugs
  6. Set author.name
  7. Set author.email
  8. Set keywords
Install dependencies
```
npm install
```
.env
1. Copy .env.example and rename it to .env
```
cp ./.env.example .env
```
2. Fill in the secrets
LICENSE
1. Set year
2. Set author name
Create issue labels on GitHub
1. Create access token for github-label-sync named <my-repo>/github-label-sync and give it access to repo.
2. Save the token to .env under GITHUB_LABEL_SYNC_TOKEN
3. Save the token to secrets management service (e.g. LastPass).
4. Run label sync wizard and enter required info.
```
npm run labels:sync
```
CodeCov (config)
1. Go to CodeCov (or directly to https://codecov.io/gh/<username>/<repo>), add the new repo and its get token.
2. Set CODECOV_TOKEN in .env
3. Save the token to secrets management service (e.g. LastPass).
Zappr (.zappr.yml config)
1. Set your username as maintainer in zappr.yml.
2. Go to Zappr and activate zappr for this project.
AllContributors (.all-contributorsrc config)
1. Set project name (projectName)
2. Set project owner (authorGithubUsername)
Snyk

Taken from this guide.
1. Setup Snyk.
```
npx snyk wizard
```
  If prompted whether to update the policy file or replace it, choose replace.
  
  Snyk commands are already in package.json, so when asked if they should be added, say no.
  If you're prompted to authenticate, run and follow command:
```
npx snyk auth
```
snyk wizard both patches and tests the dependencies. If later you need to do either of them, then:
- Run snyk:protect to patch / update dependencies
```
npm run snyk:protect
```
- Run snyk:test to test vulnerabilities
```
npm run snyk:protect
```
Travis (config)
1. Set project name (projectName).
2. Set project owner (authorGithubUsername).
Travis (bot)
1. Set up Travis for the repo here.
  - Make sure that CI builds run on both PR and push (check settings).
  - This must be done before following steps to be able to encrypt tokens.
Configure signed commits in Travis CI

Taken from the semantic-release guide
1. Generate key. This can be done by either filling in a template file and passing that or step by step
  - From file:
    1. Fill name, email, comment, and passphrase to config/travis-ci/gen-key_template
    2. Run gpg --batch --gen-key config/travis-ci/gen-key_template
    3. Run rm config/travis-ci/gen-key_template, or alternatively keep the file around a bit longer as we will still need the password later on.
  - From command line:
    1. Run GPG
      gpg --full-generate-key
      - Select RSA and RSA.
      - Select size 4096.
      - Enter yout name, the email associated with your Git hosted account.
      - Set a long (e.g. 64) and hard to guess passphrase. Ideally use a reliable generator (e.g. keychain). Save the password to secrets management service (e.g. LastPass).
      - Set the GPG key comment to include the name of the project, e.g. <my-repo>/travis-ci
2. Display the newly created key ID (16-letter sequence).
```
gpg --list-secret-keys --keyid-format LONG
```
3. Export the key
```
gpg --armor --export XXXXXXXXXXXXXXXX
```
  XXXXXXXXXXXXXXXX is the key ID sequence.
4. Copy the key, beginning with -----BEGIN PGP PUBLIC KEY BLOCK----- and ending with -----END PGP PUBLIC KEY BLOCK-----
5. Add the GPG key to your GitHub account.
6. Save the key ID to secrets management service (e.g. LastPass), so you know which project the key belongs to (GitHub doesn't allow any comments).
7. Encrypt and add following tokens / passwords to appropriate field in travis.yml
```
 travis encrypt GPG_PASSPHRASE=...
 travis encrypt GPG_KEY_ID=XXXXXXXXXXXXXXXX
 travis encrypt GIT_EMAIL=...
 travis encrypt GIT_USERNAME=<UserName>
 travis encrypt "GIT_COMMITTER_NAME=<Your Git Name>"
 travis encrypt GIT_COMMITTER_EMAIL=...
```
8. Export keys:
```
gpg --export -a XXXXXXXXXXXXXXXX > git_gpg_keys.asc
gpg --export-secret-key -a XXXXXXXXXXXXXXXX >> git_gpg_keys.asc
```
  Encrypt the file for Travis
```
travis encrypt-file git_gpg_keys.asc
```
  Paste the response to the appropriate place in .travis.yml.
  
  Finally move the encrypted keys to config direrctory.
```
# Save the `git_gpg_keys.asc.enc` to `./config/travis-ci`
mv git_gpg_keys.asc.enc config/travis-ci/git_gpg_keys.asc.enc
```
9. Cleanup
```
rm git_gpg_keys.asc
```
  If you haven't removed config/travis-ci/gen-key_template before, run
```
rm config/travis-ci/gen-key_template
```
Notes:
- Don't forget to update the line that goes like - openssl aes-256-cbc...
- When updating the before_install script in .travis.yml, make sure that the line which goes like - echo '/usr/bin/gpg... that the command called is /usr/bin/gpg and NOT /usr/bin/gpg2.
- Generate encrypted values with travis encrypt MY_ENV_VAR=env_var_value. .travis.yml already includes fields where the encrypted values should be pasted (look for <paste your encrypted...)
Add semantic release tokens to .travis.yml
1. Add encrypted NPM_TOKEN to be able to release on NPM
  1. Go to https://www.npmjs.com/settings/your-username/tokens and generate Read and Publish token
  2. Run travis encrypt NPM_TOKEN=<your token> to encrypt the token and add it to .travis.yml
  3. Save the token to secrets manager so you can find out what the key relates to (NPM doesn't offer any way to save a note)
2. Add encrypted GH_TOKEN to be able to release on GitHub
  1. Go to https://github.com/settings/tokens and generate new token with note <project-name>/semantic-release and repo access.
  2. Run travis encrypt GH_TOKEN=<your token> to encrypt the token and add it to .travis.yml
Add Snyk token to .travis.yml
1. Add encrypted SNYK_TOKEN to be able to test / patch in CI.
  1. Go to https://snyk.io/account/ and generate a token
  2. Encrypt the token and add it to .travis.yml
```
travis encrypt SNYK_TOKEN=<your token>
```
  3. Add the token to .env
CHANGELOG.md
1. Make sure it's empty at the beginning.
README.md
1. Remove the inital README.md if there's any.
2. Run README generator (the template uses readme-md-generator).
```
npm run readme:init
```
  Example of init arguments:
  - HTML - Prefer markdown version for compatibility
  - Description - Default (one from package.json) should be good
  - Homepage - Default (one from package.json) should be good
  - Demo URL - Add if you have one
  - Project Docs - https://github.com/<username>/<repo>/tree/master/docs
  - Author Name - Default (one from package.json) should be good
  - GitHub username - your username
  - Website - Add if you have one
  - Twitter username - Add if you have one
  - LinkedIn username - Add if you have one
  - Patreon username - Add if you have one
  - License name - MIT
  - License URL - If MIT, use https://tldrlegal.com/license/mit-license
  - Issues page - https://github.com/<username>/<repo>/issues
  - Contributing guide url - https://github.com/<username>/<repo>/tree/master/docs/CONTRIBUTING.md
  - Install command - npm install <project-name>
  - Usage command - You will want usage to be longer, so for now enter anything so the field won't be empty and relevant parts will be rendered
  - Test command npm test
3. Remove parts that don't apply to your project, e.g.:
  - Logo
  - Multiple ways of reporting relevant NPM versions is available. If using beta or next tags, include them, otherwise keep only the @latest tag.
  - Multiple types of documentation badges are available. If using language which is supported by Inch CI, use their badge, otherwise use the static one.
4. Remove comments from the markdown, unless stated otherwise.
5. Fix spacing and gaps.
  - Homepage | Repository | Documentation | Issue Tracker should be a single line.
  - Table of content if there are any.
  - Gaps between maintainers links.
6. Update CodeClimate badge
  1. Go to https://codeclimate.com/github/repos/new and add the repo.
  2. Go to https://codeclimate.com/github/<username>/<project-name>/builds and navigate to repo settings > extras > badges.
  3. Copy the ID from the badge image url.
  4. Paste the ID to Maintainability badge in README.md
7. Add contributors
  - With cli:
```
npm run contributors:add <username> <contribution type>
```
  - With AllContributors GitHub bot
8. Update contributors table.
  - With cli:
```
npm run contributors:generate
```
9. Update any missing links.
  - Changelog?
  - Code of Conduct link?
  - Open an Issue link?
  - Open a PR link?
10. Update the remaining content if necessary.
11. Remove README_template.md
```
rm README_template.md
```
Doumentation

Fill in missing info in docs.
1. PULL_REQUEST_TEMPLATE
  1. Set project name (projectName)
  2. Set project owner (authorGithubUsername)
2. issue_labels.md
  1. Set project name (projectName)
  2. Set project owner (authorGithubUsername)
3. developing.md
  1. Set project name (projectName)
  2. Set project owner (authorGithubUsername)
4. CONTRIBUTING.md
  1. Set project name (projectName)
  2. Set project owner (authorGithubUsername)
5. CODE_OF_CONDUCT.md
  1. Set project team email (or your email, authorEmail)
6. logging.md
  1. Select only those parts of logging strategy that apply. Or copy from another repo where it was already modified and that is the same type of project as this one.
Push the changes to the remote.
1. Stage all changes
```
git add -A
```
2. Commit
  
  If this is first commit, skip validation by skipping Husky hooks
```
 HUSKY_SKIP_HOOKS=1 git commit -m "chore: initial commit"
```
3. Push
  
  If this is first push, set upstream with git pushu (one of the aliases) set up in step 5.
```
git pushu --no-verify
```
Zappr (bot)
1. Go to Zappr and activate appropriate checks, e.g.:
  - Approval check
  - Commit message check
  - Specification check
2. Add the Zappr integration if not active yet.
CodeCov (bot)
1. Add the CodeCov integration if not active yet.
CodeClimate (bot)
1. Go to CodeClimate and add the repo if not done before.
AllContributors (bot)
1. Add the AllContributors integration if not active yet.
Hall of Fame Integration
1. Refresh recognized repos on Sourcerer by going to https://sourcerer.io/your-username, and refresh.
2. Go to Sourcerer's Hall of Fame, select the repo and add it.
DependaBot (bot)
1. Add the Dependabot integration if not active yet.
2. If not active you can also activate it here.
LGTM (bot)
1. Add the LGTM integration if not active yet.
Snyk (bot)
1. Add Snyk integration if not active yet.
Protect release branch from accidental modifications:
1. Go to https://github.com/<username>/<project-name>/settings/branches
2. Add new rule with branch pattern master.
Create Spectrum community
1. Login to Spectrum and create new community.
2. Enter the name of the package as the community name (or sensible alternative if it is already taken).
3. Description can be something like Community for the <package-name> NPM package. + package description
4. Set community website as link to GitHub, e.g. https://github.com/JuroOravec/instance-manager
5. Set community as public and hit create!
6. Settings:
  - If relevant create appropriate channels
7. Set to receive notifications from the channel (including the chat).
8. Go to chat and add intro message, e.g. Hi there!.
9. Pin Welcome post (adapted from Pierre Vanduynslager's welcome post at semantic-release Spectrum community page)
```
Welcome to the <package-name> community!

This is the place to discuss `<package-name>` package(s)/project(s) and ask for help.

When discussing, let's stick to these rules:
- Be kind, polite and respectful. We expect everyone to follow the [Spectrum’s Code of Conduct](https://github.com/withspectrum/code-of-conduct).
- Search existing threads for your question to make sure it hasn't already been answered
- Read the `<package-name>` [documentation](https://github.com/JuroOravec/<package-name>/tree/master/docs).
- When creating a new thread, make sure to use a clear and unambiguous title so it can be found more easily by others.
```
  Note: If the project is a multi-repo or a collection of projects packages, use the plural form

Congratulations on getting all the way here! 🎊 🎉

Workflow

See the documentation for more on the workflow.

Scripts

See below some common npm scripts that you will use. For full list, see package.json.

Build distribution:

npm run build

Run tests:

npm test

Run formatters:

npm run-s format lint

Validation (security tests + formatting checks):

npm run validate

TypeDoc documentation:

# Markdown
npm run typedoc:markdown
# HTML
npm run typedoc:html

Add a contributor to README:

npm run contributors:add <all-contributors args...>
npm run contributors:generate

🔮 Background

A template that came about from working with TypeScript.

⏳ Changelog

This projects follows semantic versioning. The changelog can be found here.

🛠 Developing

If you want to contribute to the project or forked it, this guide will get you up and going.

🏗 Roadmap

There is no explicit roadmap for this project. However, there is many ways how this can be improve or automated, so if you have ideas and the time, please be sure to share it with us by opening an issue.

🤝 Contributing

Contributions, issues and feature requests are welcome! Thank you ❤️

Feel free to dive in! See current issues, open an issue, or submit PRs.

How to report bugs, feature requests, and how to contribute and what conventions we use is all described in the contributing guide.

When contributing we follow the Contributor Covenant. See our Code of Conduct.

🧙 Contributors

Contributions of any kind welcome. Thanks goes to these wonderful people ❤️

Recent and Top Contributors

_{Generated using Hall of Fame.}

All Contributors

Contribution type emoji legend

No additional contributors. Be the first one!

_{This project follows the all-contributors specification.}

⭐ Show your support

Give a ⭐️if this project helped you!

🐙 Community

👨‍🔧 Maintainers

👤 Juro Oravec

Twitter: @JuroOravec
GitHub: @JuroOravec
LinkedIn: @jurooravec
Sourcerer: @JuroOravec

📝 License

This project is MIT licensed.

Name		Name	Last commit message	Last commit date
Latest commit History 39 Commits
config		config
docs		docs
scripts		scripts
template		template
test		test
.all-contributorsrc		.all-contributorsrc
.codeclimate.yml		.codeclimate.yml
.env.example		.env.example
.eslintignore		.eslintignore
.eslintrc.js		.eslintrc.js
.gitignore		.gitignore
.lgtm.yml		.lgtm.yml
.npmignore		.npmignore
.prettierrc		.prettierrc
.snyk		.snyk
.travis.yml		.travis.yml
.zappr.yaml		.zappr.yaml
CHANGELOG.md		CHANGELOG.md
LICENSE		LICENSE
README.md		README.md
codecov.yml		codecov.yml
commitlint.config.js		commitlint.config.js
labels.yml		labels.yml
package-lock.json		package-lock.json
package.json		package.json
release.config.js		release.config.js
tsconfig.json		tsconfig.json

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

chonky-node-template

🏠 Homepage | 🗃 Repository | 📦 NPM | 📚 Documentation | 🐛 Issue Tracker

🪑 Table of Content

🧰 Features

🚦 Prerequisites

Environment

Packages

Services / Bots

🚀 Usage

Setup

Workflow

Scripts

🔮 Background

⏳ Changelog

🛠 Developing

🏗 Roadmap

🤝 Contributing

🧙 Contributors

Recent and Top Contributors

All Contributors

⭐ Show your support

🐙 Community

👨‍🔧 Maintainers

📝 License

About

Releases 3

Packages

Contributors 3

Languages

License

JuroOravec/chonky-node-template

Folders and files

Latest commit

History

Repository files navigation

chonky-node-template

🏠 Homepage | 🗃 Repository | 📦 NPM | 📚 Documentation | 🐛 Issue Tracker

🪑 Table of Content

🧰 Features

🚦 Prerequisites

Environment

Packages

Services / Bots

🚀 Usage

Setup

Workflow

Scripts

🔮 Background

⏳ Changelog

🛠 Developing

🏗 Roadmap

🤝 Contributing

🧙 Contributors

Recent and Top Contributors

All Contributors

⭐ Show your support

🐙 Community

👨‍🔧 Maintainers

📝 License

About

Resources

License

Code of conduct

Stars

Watchers

Forks

Releases 3

Packages 0

Contributors 3

Languages

Packages