JS Template

A github template repository for creating node-first JavaScript projects (i.e. primarily for node packages and/or terminal applications which may include small, static web demos).

This repository is hosted on github, if you're already reading this there, then great! Otherwise browse the repository here.

Table of Contents

• Description
• Getting Started
  • Personal Access Token
• Documentation
• Roadmap
• Attributions
• License

Size

Approximate download size of repository, code files within repository, compressed main file, and (just for fun) lines written by the developer including comments etc.

Please note that due to file compression, and post download installs/builds such as node module dependencies, the following badges may not exactly reflect download size or space on disk.

Description

This is a template repository for creating predominantly node based JavaScript projects and packages. This includes configuration scripts for testing and building source files, admin scripts for generating changelog release notes etc. Please see the following list for the main features provided by this template repository:

• Template directory structure for creating and managing a package repository
• Github issue and pull request templates
• Configuration for testing and build processes
• Automatic changelog release notes generation
• Dot file configurations for linting, git, and npm

Getting Started

To get started using this template repository, please follow the instructions below in order:

1. Duplicate this template repository using the Use this template button located in the top right of the file section of the github repository where the Clone button is located for normal repositories
2. In the General tab of the new repository settings, underneath the section labeled Features, disable the repository wiki and projects sections as they are unused in organisation workflow.
3. Run npm i to install dev dependencies
4. Run npm run admin:plop, select Package, and then follow the prompts in the terminal to update the package.json file with details of the new repository
5. Run npm run admin:plop, select Reset, and then follow the prompts in the terminal to update the CHANGELOG.md, CONTRIBUTING.md, LICENSE.md, and README.md files with details of the new repository (note that this step will overwrite this file)
6. Update issue labels to match the labels required for repository issue templates (if duplicating into an organisation with the correct labels already set as default labels, this step may be skipped):
   1. Obtain an appropriate personal access token using the directions in the section below
   2. Add .env file to root of repository, and add line containing access token with the following key GITHUB_ACCESS_TOKEN=<github-pat>
   3. Run npm run admin:update-labels
   4. Verify that labels have been updated correctly by comparing labels in the new, duplicated repository to the template repository labels (the file ./admin/config/labels.json also contains a list of the required labels)
7. Commit changes with a commit message such as msc= Initialise template repository

Personal Access Token

To obtain a personal access token suitable for updating the labels of the new, duplicated repository, please follow the instruction below in order (see the code block at the end for the expected entry in the untracked .env file in the root of the repository):

1. Navigate to Developer Settings in your account settings on github (the Developer Settings tab may be found at the very bottom of the nav menu in your main account settings)
2. Navigate to Personal access tokens and then Fine-grained tokens in the Developer Settings nav menu
3. Select Generate new token in the top right of the settings section
4. Enter the required details for creating the new access token, considering the following:
   1. Choose a name reflecting the access token scope such as personal-label-migration
   2. Choose a short expiry
   3. Change Resource owner as required if the access token is intended for use on repositories duplicated in an organisation
   4. Change Repository access to All repositories
   5. Under Permissions change the following Repository permissions:
      1. Change Issues to Access: Read and write
      2. Change Metadata to Access: Read-only
5. Check that only appropriate permissions have been added in the Overview section, then use the Generate token button to generate the new access token
6. Approve personal access token in settings tab of organisation (only applies if access token is for use in an organisation):
   1. Navigate to the organisation settings of the appropriate organisation
   2. Navigate to Personal access tokens and then Pending requests
   3. Approve or revoke pending tokens as required
   4. See here for more information
7. Add personal access token to .env file in root of the new, duplicated repository using the key GITHUB_ACCESS_TOKEN (see the code block below)

# Github access token should be stored with the following key:
GITHUB_ACCESS_TOKEN=<github-pat>

Documentation

Since this README file will be overwritten during the template duplication process, no extra documentation is included here beyond the basic steps required for initialising a new repository using this template. For more information about this template repository, please see the links in the list below:

• For more information on all features of this template repository such as folder structure, code style, and git usage, please see the contributing file
• For more information specifically concerning changelog format and generation, see the notes section of the changelog file
• For more information specifically concerning repository scripts:
  • See the inline code documentation in the source files in the ./admin directory
  • See the npm scripts section of the contributing file

For an approximate line count of all configuration files and documentation, please see the following code block (note that tokei will have to be installed on your local system for this to work, and that tokei does not recognise .files, and therefore files such as the .eslintrc configuration will be excluded from the count):

# Run the following command for an *approximate* line count for configuration.
tokei admin .github package.json CHANGELOG.md CONTRIBUTING.md LICENSE.md README.md

Roadmap

If you find a bug or think there is a specific feature that should be added or changed, please file a bug report or feature request using this repository's issue tracker. Otherwise, please see below for proposed new features which may be added in later updates:

• This repository currently has no projects on its roadmap

Attributions

At the time of last update, this repository used no 3rd party assets or libraries other than those which are referenced as dependencies and/or dev dependencies in the package.json file in the root of this repository. The author will endeavour to update this section of documentation promptly as and when new 3rd party assets or libraries not referenced in the package.json file are added to this repository.

License

---

DISCLAIMER The author(s) of this repository are in no way legally qualified, and are not providing the end user(s) of this repository with any form of legal advice or directions.

---

Copyright (c) 2023 James Reid. All rights reserved.

This software is licensed under the terms of the MIT license, a copy which may be found in the LICENSE.md file in the root of this repository, or please refer to the text below. For a template copy of the license see one of the following 3rd party sites:

• opensource
• choosealicense
• spdx

License Text

Copyright 2023 James Reid

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.