.template/README.njk
---
buildStatus:
gitHubActions:
workflowName: GitHub Actions
codeClimate:
maintainabilityBadgeURL: https://api.codeclimate.com/v1/badges/1aabcc39ecde1caeb45d/maintainability
---
# {{ pkg.name }}
{% if not pkg.private -%}
[![Go to the latest release page on npm](https://img.shields.io/npm/v/{{ pkg.name }}.svg)]({{ pkg.name | npmURL }})
{% endif -%}
[![License: {{ pkg.license }}](https://img.shields.io/static/v1?label=license&message={{ pkg.license | urlencode }}&color=green)]({{ '/LICENSE' | repoBrowseURL(branch='master') }})
{%- if pkg.engines and pkg.engines.node %}
![Supported Node.js version: {{ pkg.engines.node }}](https://img.shields.io/static/v1?label=node&message={{ pkg.engines.node | urlencode }}&color=brightgreen)
{%- endif %}
{%- if (pkg.types or pkg.typings) and deps.typescript %}
![Type Definitions: TypeScript](https://img.shields.io/static/v1?label=types&message=TypeScript&color=blue)
{%- endif %}
{%- if deps.jest %}
[![Tested with Jest](https://img.shields.io/badge/tested_with-jest-99424f.svg)](https://github.com/facebook/jest)
{%- endif %}
{%- if deps.commitizen %}
[![Commitizen friendly](https://img.shields.io/badge/commitizen-friendly-brightgreen.svg)](http://commitizen.github.io/cz-cli/)
{%- endif %}
{%- if deps.shipjs %}
[![Deploy with Ship.js](https://img.shields.io/badge/deploy-🛳%20Ship.js-blue?style=flat)](https://github.com/algolia/shipjs)
{%- endif %}
{%- if not pkg.private %}
[![Minified Bundle Size Details](https://img.shields.io/bundlephobia/min/{{ pkg.name }}/{{ pkg.version }})](https://bundlephobia.com/result?p={{ pkg.name }}@{{ pkg.version }})
[![Install Size Details](https://packagephobia.now.sh/badge?p={{ pkg.name }}@{{ pkg.version }})](https://packagephobia.now.sh/result?p={{ pkg.name }}@{{ pkg.version }})
{%- endif %}
[![Dependencies Status](https://david-dm.org/{{ repo.user }}/{{ repo.project }}/status.svg)](https://david-dm.org/{{ repo.user }}/{{ repo.project }})
{%- if buildStatus %}
{% if buildStatus.gitHubActions.workflowName -%}
{%- if not buildStatus.gitHubActions.branch -%}
{%- setProp buildStatus.gitHubActions.branch = 'master' -%}
{%- endif -%}
{%- setProp buildStatus.badgeURL -%}
https://github.com/{{ repo.user }}/{{ repo.project }}/workflows/{{ buildStatus.gitHubActions.workflowName | urlencode }}/badge.svg?branch={{ buildStatus.gitHubActions.branch | urlencode }}
{%- endset -%}
{%- setProp buildStatus.pageURL -%}
https://github.com/{{ repo.user }}/{{ repo.project }}/actions?query={% filter urlencode %}workflow:"{{ buildStatus.gitHubActions.workflowName }}" branch:{{ buildStatus.gitHubActions.branch }}{% endfilter %}
{%- endset -%}
{%- endif -%}
{%- if buildStatus.pageURL -%}
[![Build Status]({{ buildStatus.badgeURL }})]({{ buildStatus.pageURL }})
{%- else -%}
![Build Status]({{ buildStatus.badgeURL }})
{%- endif -%}
{%- endif %}
{%- if codeClimate %}
{%- if codeClimate.maintainabilityBadgeURL %}
[![Maintainability Status]({{ codeClimate.maintainabilityBadgeURL }})](https://codeclimate.com/github/{{ repo.user }}/{{ repo.project }}/maintainability)
{%- endif %}
{%- if codeClimate.testCoverageBadgeURL %}
[![Test Coverage Status]({{ codeClimate.testCoverageBadgeURL }})](https://codeclimate.com/github/{{ repo.user }}/{{ repo.project }}/test_coverage)
{%- endif %}
{%- endif %}
{{ pkg.description | replace(r/\S+\.[a-z]+/g, '`$&`') }}.
## Install
```sh
npm install --save-dev {{ repo.shortcut(semver=(pkg.version if pkg.version | isOlderReleasedVersion == false)) }}
```
## Usage
```console
$ {{ pkg.name | omitPackageScope }} --help
{{ 'ts-node --transpile-only ./src/index.ts --help' | execCommand }}
```
### Setting API token when using `{{ pkg.name }}` with private repository
`{{ pkg.name }}` reads the repository information (for example, a list of pushed tags). If you want to use it in a private repository, you need to set the API token according to the repository type.
#### GitHub
[Get a GitHub personal access token](https://docs.github.com/en/github/authenticating-to-github/creating-a-personal-access-token#creating-a-token) and specify it in the environment variable `GITHUB_TOKEN`.
```console
$ GITHUB_TOKEN="..." {{ pkg.name | omitPackageScope }}
```
If you use the `{{ pkg.name }}` with GitHub Actions, you don't need to get a personal access token; you can use [`GITHUB_TOKEN` secret](https://docs.github.com/en/actions/reference/authentication-in-a-workflow#about-the-github_token-secret) in GitHub Actions.
```yaml
steps:
- run: npx {{ pkg.name | omitPackageScope }}
env:
{% raw %}GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}{% endraw %}
```
#### GitLab
Currently not supported.
#### Bitbucket
Currently not supported.
### Default Defined Variables
* `pkg` - [Source]({{ '/src/main.ts' | repoBrowseURL | linesSelectedURL( start=r/= *readPkgJson\(/, end=r/Object\.assign\([a-zA-Z0-9]+, *\{ *pkg *\}\)|\.pkg *= *pkg *[;\n]/ ) }}) and [Source]({{ '/src/utils/package-json.ts' | repoBrowseURL | linesSelectedURL( r/^export function readPkgJson\((?:(?!\})[^\n]*\n)+/m ) }})
Object value of `package.json`
* `repo` - [Source]({{ '/src/main.ts' | repoBrowseURL | linesSelectedURL( r/^( +)repo: *\{\n+(?:\1 [^\n]+\n+)+\1/m ) }})
Object value indicating repository data.
It is generate by reading [the `repository` field] of [`package.json`].
[`package.json`]: https://docs.npmjs.com/files/package.json
[the `repository` field]: https://docs.npmjs.com/files/package.json#repository
* `deps` - [Source]({{ '/src/main.ts' | repoBrowseURL | linesSelectedURL( start=r/^ +const deps =/m, end=r/\btemplateContext\b[^\n]*\bdeps\b/ ) }}) and [Source]({{ '/src/utils/installed-dependencies.ts' | repoBrowseURL }})
Object value indicating dependencies data.
It is generate by reading `package-lock.json`.
### Additional Tags
#### `setProp`
[Source]({{ '/src/template-tags/setProp.ts' | repoBrowseURL }})
`setProp` lets you create/modify variable properties.
template:
```nunjucks{% raw %}
{% set data = {} %}
{{ data | dump }}
{% setProp data.username = 'joe' %}
{{ data | dump }}
```{% endraw %}
output:
```
{% set data = {} %}
{{ data | dump }}
{% setProp data.username = 'joe' %}
{{ data | dump }}
```
`setProp` can also create/modify variables.
So you can replace [the `set` tag] with `setProp`.
[the `set` tag]: https://mozilla.github.io/nunjucks/templating.html#set
{% set username = '' -%}
template:
```nunjucks{% raw %}
username: {{ username }}
{% setProp username = "joe" %}
username: {{ username }}
```{% endraw %}
output:
```
username: {{ username }}
{% setProp username = "joe" %}
username: {{ username }}
```
Like the `set` tag, `setProp` can also capture the contents of a block.
template:
``````nunjucks{% raw %}
{% setProp data.gitignore = {} %}
{% setProp data.gitignore.contents -%}
{% include '.gitignore' %}
{%- endset %}
**`.gitignore`**
```
{{ data.gitignore.contents }}
```
``````{% endraw %}
output:
``````
{% setProp data.gitignore = {} %}
{% setProp data.gitignore.contents -%}
{% include '.gitignore' %}
{%- endset %}
**`.gitignore`**
```
{{ data.gitignore.contents }}
```
``````
### Additional Filters
#### `omitPackageScope`
[Source]({{ '/src/template-filters/omitPackageScope.ts' | repoBrowseURL | linesSelectedURL( r/^export function omitPackageScope\([^\n]*\n+(?: [^\n]+\n+)+\}/m ) }})
template:
```nunjucks{% raw %}
{{ '@foo/bar' | omitPackageScope }}
```{% endraw %}
output:
```
{{ '@foo/bar' | omitPackageScope }}
```
#### `npmURL`
[Source]({{ '/src/template-filters/npmURL.ts' | repoBrowseURL | linesSelectedURL( r/^export function npmURL\([^\n]*\n+(?: [^\n]+\n+)+\}/m ) }})
template:
```nunjucks{% raw %}
- {{ 'foo' | npmURL }}
- {{ 'foo@1.2.3' | npmURL }}
- {{ 'foo@legacy' | npmURL }}
- {{ '@hoge/bar' | npmURL }}
- {{ '@hoge/bar@0.1.1-alpha' | npmURL }}
- {{ '@hoge/bar@dev' | npmURL }}
- {{ pkg.name | npmURL }}
- {{ deps.nunjucks | npmURL }}
- {{ deps['@types/node'] | npmURL }}
```{% endraw %}
output:
```
- {{ 'foo' | npmURL }}
- {{ 'foo@1.2.3' | npmURL }}
- {{ 'foo@legacy' | npmURL }}
- {{ '@hoge/bar' | npmURL }}
- {{ '@hoge/bar@0.1.1-alpha' | npmURL }}
- {{ '@hoge/bar@dev' | npmURL }}
- {{ pkg.name | npmURL }}
- {{ deps.nunjucks | npmURL }}
- {{ deps['@types/node'] | npmURL }}
```
#### `execCommand`
[Source]({{ '/src/template-filters/execCommand.ts' | repoBrowseURL | linesSelectedURL( r/^export async function execCommand\([^\n]*\n+(?: [^\n]+\n+)+\}/m ) }})
template:
```nunjucks{% raw %}
{{ 'tsc --version' | execCommand }}
---
{{ ['eslint', '--version'] | execCommand }}
```{% endraw %}
output:
```
{{ 'tsc --version' | execCommand }}
---
{{ ['eslint', '--version'] | execCommand }}
```
#### `linesSelectedURL`
[Source]({{ '/src/template-filters/linesSelectedURL.ts' | repoBrowseURL | linesSelectedURL( r/^export async function linesSelectedURL\([^\n]*\n+(?: [^\n]+\n+)+\}/m ) }})
template:
```nunjucks{% raw %}
11. {{ '/types.node_modules/npm-path.d.ts' | repoBrowseURL | linesSelectedURL( r/^export =/ ) }}
21. {{ '/types.node_modules/npm-path.d.ts' | repoBrowseURL | linesSelectedURL( start=r/^export =/ ) }}
12. {{ '/types.node_modules/npm-path.d.ts' | repoBrowseURL | linesSelectedURL( r/^(declare [^\n]*\n)+/m ) }}
22. {{ '/types.node_modules/npm-path.d.ts' | repoBrowseURL | linesSelectedURL( start=r/^(declare [^\n]*\n)+/m ) }}
13. {{ '/types.node_modules/npm-path.d.ts' | repoBrowseURL | linesSelectedURL( r/^(declare [^\n]*)(\ndeclare [^\n]*)*/m ) }}
23. {{ '/types.node_modules/npm-path.d.ts' | repoBrowseURL | linesSelectedURL( start=r/^(declare [^\n]*)(\ndeclare [^\n]*)*/m ) }}
34. {{ '/.eslintrc.yaml' | repoBrowseURL | linesSelectedURL( start=r/^parserOptions:$/m, end=r/.\n\S/ ) }}
35. {{ '/.eslintrc.yaml' | repoBrowseURL | linesSelectedURL( start=r/^parserOptions:$/m, end=r/.\n(?=\S)/ ) }}
36. {{ '/.eslintrc.yaml' | repoBrowseURL | linesSelectedURL( start=r/^parserOptions:$/m, end=r/.(?=\n\S)/ ) }}
41. {{ '/.prettierrc.yaml' | repoBrowseURL | linesSelectedURL( start=r/^ /, end=r/^[^\n]*$/ ) }}
{% set repoData = { repoType: 'github',
fileFullpath: '.eslintrc.yaml',
browseURL: 'http://example.com/path/to' }
-%}
51. {{ repoData | linesSelectedURL(r/(?<!\w)sourceType:/) }}
```{% endraw %}
output:
```
11. {{ '/types.node_modules/npm-path.d.ts' | repoBrowseURL | linesSelectedURL( r/^export =/ ) }}
21. {{ '/types.node_modules/npm-path.d.ts' | repoBrowseURL | linesSelectedURL( start=r/^export =/ ) }}
12. {{ '/types.node_modules/npm-path.d.ts' | repoBrowseURL | linesSelectedURL( r/^(declare [^\n]*\n)+/m ) }}
22. {{ '/types.node_modules/npm-path.d.ts' | repoBrowseURL | linesSelectedURL( start=r/^(declare [^\n]*\n)+/m ) }}
13. {{ '/types.node_modules/npm-path.d.ts' | repoBrowseURL | linesSelectedURL( r/^(declare [^\n]*)(\ndeclare [^\n]*)*/m ) }}
23. {{ '/types.node_modules/npm-path.d.ts' | repoBrowseURL | linesSelectedURL( start=r/^(declare [^\n]*)(\ndeclare [^\n]*)*/m ) }}
34. {{ '/.eslintrc.yaml' | repoBrowseURL | linesSelectedURL( start=r/^parserOptions:$/m, end=r/.\n\S/ ) }}
35. {{ '/.eslintrc.yaml' | repoBrowseURL | linesSelectedURL( start=r/^parserOptions:$/m, end=r/.\n(?=\S)/ ) }}
36. {{ '/.eslintrc.yaml' | repoBrowseURL | linesSelectedURL( start=r/^parserOptions:$/m, end=r/.(?=\n\S)/ ) }}
41. {{ '/.prettierrc.yaml' | repoBrowseURL | linesSelectedURL( start=r/^ /, end=r/^[^\n]*$/ ) }}
{% set repoData = { repoType: 'github',
fileFullpath: '.eslintrc.yaml',
browseURL: 'http://example.com/path/to' }
-%}
51. {{ repoData | linesSelectedURL(r/(?<!\w)sourceType:/) }}
```
#### `repoBrowseURL`
*This filter is only defined if the generator was able to read the remote repository from [the `repository` field] of [`package.json`]*.
[Source]({{ '/src/template-filters/repoBrowseURL.ts' | repoBrowseURL | linesSelectedURL( r/^( +)return async function repoBrowseURL\([^\n]*\n+(?:\1 [^\n]+\n+)+\1\}/m ) }})
template:
```nunjucks{% raw %}
11. {{ '/.template/README.njk' | repoBrowseURL }}
12. {{ '/.template/README.njk' | repoBrowseURL(tag='foo') }}
13. {{ '/.template/README.njk' | repoBrowseURL(branch='gh-pages') }}
14. {{ '/.template/README.njk' | repoBrowseURL(commit='4626dfa') }}
15. {{ '/.template/README.njk' | repoBrowseURL(committish='COMMIT-ISH') }}
21. {{ '.template/README.njk' | repoBrowseURL }}
31. {{ './README.njk' | repoBrowseURL }}
41. {{ '../src/index.ts' | repoBrowseURL }}
```{% endraw %}
output:
```
11. {{ '/.template/README.njk' | repoBrowseURL }}
12. {{ '/.template/README.njk' | repoBrowseURL(tag='foo') }}
13. {{ '/.template/README.njk' | repoBrowseURL(branch='gh-pages') }}
14. {{ '/.template/README.njk' | repoBrowseURL(commit='4626dfa') }}
15. {{ '/.template/README.njk' | repoBrowseURL(committish='COMMIT-ISH') }}
21. {{ '.template/README.njk' | repoBrowseURL }}
31. {{ './README.njk' | repoBrowseURL }}
41. {{ '../src/index.ts' | repoBrowseURL }}
```
#### `isOlderReleasedVersion`
*This filter is only defined if the generator was able to read the remote repository from [the `repository` field] of [`package.json`]*.
Determines if a version has been released in a remote repository, and if the current commit is more recent than the version's corresponding tag.
The version detection is done using the same algorithm as the `#semver:<semver>` format of [the `npm install` command][npm-install].
There are three types of return values:
[npm-install]: https://docs.npmjs.com/cli/install
* `true` - If the specified version of a git tag exists in a remote repository and the current commit and git tag are different.
* `false`
* If the specified version of a git tag exists in a remote repository and the current commit and git tag are same.
* If the specified version of a git tag does not exist in the remote repository.
* `null`
* If a remote repository does not exist.
* If can't access a remote repository.
* If the current directory is not a git repository.
* Run the `git init` command, then haven't first committed yet.
[Source]({{ '/src/template-filters/isOlderReleasedVersion.ts' | repoBrowseURL | linesSelectedURL( r/^( +)return async function isOlderReleasedVersion\([^\n]*\n+(?:\1 [^\n]+\n+)+\1\}/m ) }})
template:
```nunjucks{% raw %}
0.0.2: {{ '0.0.2' | isOlderReleasedVersion | dump }}
{{pkg.version}}: {{ pkg.version | isOlderReleasedVersion | dump }}
999.90.1: {{ '999.90.1' | isOlderReleasedVersion | dump }}
```{% endraw %}
output:
```
0.0.2: {{ '0.0.2' | isOlderReleasedVersion | dump }}
{{pkg.version}}: {{ pkg.version | isOlderReleasedVersion | dump }}
999.90.1: {{ '999.90.1' | isOlderReleasedVersion | dump }}
```
## Tests
To run the test suite, first install the dependencies, then run `npm test`:
```sh
npm install
npm test
```
## Contributing
see [CONTRIBUTING.md]({{ '/CONTRIBUTING.md' | repoBrowseURL(branch='master') }})