An opinionated starting point for every project built with Node.js
JavaScript
0
16 commits
updated Oct 9, 2026
[!TIP] This template is a starting point you can use for every Node.js project. We offer:
- Clear structure and a small working example
- Node.js and Yarn versions pinned for local development and CI
- Tests and formatting in continuous integration
- Automated releases with Release Please and SLSA provenance attestation
What is in-scope for this template?
We the people who manage Node.js projects, in order to advocate for a safer installation path and great defaults for Node.js, maintain this starting point for all projects.
This node.js-template must remain broad—addressing the needs of many kinds of projects. Every project deserves a README, and a clear rule on basic formatting questions, this is why we include continuous integration linting.
We do not specify that GitHub and GitHub Actions are the only way to host projects, others may consider our GitHub-specific notes as a starting point guide for implementing outside of GitHub.
And now below is the template, shown for a specific hypothetical project, enjoy!
Add and subtract, in reverse Polish notation.
Simple RPN calculator reads a string of digits, spaces, + and -. It returns the resulting number. Wrong input throws an error.
$ rpn 3 4 +
7
$ rpn 5 1 2 + -
2
[!NOTE] Replace the project name, description, demonstration and badge URLs with your own. Show what your project does before asking people to read further.
You will need Git, Node.js at the version in .node-version, and Yarn (via Corepack).
[!WARNING] fnm is a Node.js version manager, which installs
nodeat the version we specify in .node-version. We recommend to install fnm using your package manager as this is safer than the advice on the fnm and nvm websites (ref).
If you do not use a version manager and instead modify the commands below to use a copy of Node.js from your operating system, this may use your package manager's (possibly ancient) version. That build may fail and will be unsupported by this project.
node --version
corepack --version
Open a terminal (PowerShell on Windows) and use the instructions for your operating system.
On Ubuntu 22.04+ or Debian 12+:
sudo apt update
sudo apt install git
On Fedora:
sudo dnf install git
If your distribution has no fnm package, other fnm installation methods are available, but beware as that page does also recommend some dangerous methods (ref).
Install Apple's Command Line Tools if they are not already installed:
xcode-select --install
Complete the installation dialog. With Homebrew installed, install Git and fnm:
brew install git fnm
Homebrew's node formula is a standalone runtime. It does not honor .node-version. Use fnm instead.
Use winget to install Git and fnm:
winget install --exact --id Git.Git
winget install --exact --id Schniz.fnm
Allow administrator prompts and wait for installation to finish. Open a new PowerShell window so fnm is on PATH.
Clone the project and install dependencies. From this directory, fnm installs the Node.js version in .node-version on first use. CI uses the same file. Corepack installs the Yarn version pinned by packageManager in package.json.
git clone https://github.com/fulldecent/node.js-template.git
cd node.js-template
eval "$(fnm env)"
fnm install
fnm use
corepack enable
node --version
yarn --version
yarn install --immutable
In PowerShell:
fnm env --use-on-cd | Out-String | Invoke-Expression
fnm install
fnm use
corepack enable
node --version
yarn --version
yarn install --immutable
Run the command without a global install:
yarn node src/cli.js 3 4 +
yarn node src/cli.js 5 1 2 + -
[!NOTE] Explain what your users need to install, including the tools your project is built on. Replace the repository URL and command name with your own.
Evaluate an expression. Tokens are non-negative integers, + and -. Operators take the two values on the top of the stack, with the right-hand operand popped last.
yarn node src/cli.js 3 4 +
yarn node src/cli.js 10 3 -
yarn node src/cli.js 5 1 2 + -
From another ES module in this project:
import { rpn } from "./src/index.js";
rpn("3 4 +"); // 7
The command joins its arguments with spaces. Input that uses any other character, that is empty, that leaves the stack short for an operator, or that does not reduce to one number, throws an error. The command writes that error to standard error and exits with status 1.
[!NOTE] Explain how to use your project, including the limits that matter to users.
Thank you for taking an interest in improving Simple RPN calculator and the programs of people using it!
Follow the installation instructions above to get Git, fnm, Node.js and Yarn. Work from the project directory. The implementation is in src/index.js and src/cli.js; you can run it without a global install:
yarn node src/cli.js 3 4 +
Commit yarn.lock so application dependencies remain reproducible.
All project updates that we release must conform to our test suite. GitHub Actions runs checks on pushes to main and pull requests. You can also run them locally before sending proposed changes:
yarn test
yarn format
The tests in test/rpn.test.js check addition, subtraction, chained operators, invalid input and the command-line program. They check the exit status, standard output and standard error of the actual program.
With an actively maintained version of Node.js installed, correct other formatting issues before sending proposed changes:
npx prettier@latest --check . --write
npx markdownlint-cli@latest "**/*.md" --fix
Yarn puts install outputs in the ignored node_modules/ directory. Packed releases go in the ignored dist/ directory.
Use fix:, feat: or BREAKING CHANGE: in your commit messages. This triggers our bot to make a release draft pull request. Merging that pull request triggers a new tag and GitHub Release.
The release workflow uses Release Please's simple release type. Set the version in package.json to the proposed release version before merging the release pull request.
Build and test installs dependencies, runs tests, packs a tarball, then attests and uploads it. The release includes simple-rpn-calculator.tgz and release.sigstore.jsonl, containing build provenance and version attestations.
[!NOTE] In your GitHub repository settings, under Actions, General, Workflow permissions, select read and write permissions and check "Allow GitHub Actions to create and approve pull requests". Under General, Releases, enable release immutability. Attestations are available for public repositories; private repositories require GitHub Enterprise Cloud.
The project administrator completes these maintenance tasks each month. If they are 3+ months late, please remind them or send your own issue/pull request.
fnm install reads that file.package.json (packageManager). Update it with yarn set version stable && yarn when a newer stable version is appropriate.yarn upgrade-interactive.We are people who write Node.js modules and command-line tools. Sometimes we need a tiny, dependency-free starting point with pinned tooling and a test that actually runs the program.
Simple RPN calculator does that one job: evaluate reverse Polish notation with add and subtract, and reject input that is not digits, spaces, + and -. It keeps the package empty of runtime dependencies.
We specifically will not add multiply, divide, parentheses, decimal numbers or a graphical interface.
[!NOTE] Introduce your community, explain what is in scope and say what is out of scope. Help people recognize when their own work belongs here.
curl|sh method (fnm issue)..yarnrc.yml sets enableScripts to true (Yarn 4.14 defaults to false) and npmMinimalAgeGate to 0 (Yarn 4.12 defaults to one day). approvedGitRepositories is "**", which approves every git dependency. Yarn: Security[!NOTE] Carefully consider which license to apply to your project and replace the copyright line in LICENSE.md. Cite external sources that materially informed your decisions, including the release of this Node.js template you used.
An opinionated starting point for every project built with Node.js
JavaScript
0
16 commits
updated Oct 9, 2026
[!TIP] This template is a starting point you can use for every Node.js project. We offer:
- Clear structure and a small working example
- Node.js and Yarn versions pinned for local development and CI
- Tests and formatting in continuous integration
- Automated releases with Release Please and SLSA provenance attestation
What is in-scope for this template?
We the people who manage Node.js projects, in order to advocate for a safer installation path and great defaults for Node.js, maintain this starting point for all projects.
This node.js-template must remain broad—addressing the needs of many kinds of projects. Every project deserves a README, and a clear rule on basic formatting questions, this is why we include continuous integration linting.
We do not specify that GitHub and GitHub Actions are the only way to host projects, others may consider our GitHub-specific notes as a starting point guide for implementing outside of GitHub.
And now below is the template, shown for a specific hypothetical project, enjoy!
Add and subtract, in reverse Polish notation.
Simple RPN calculator reads a string of digits, spaces, + and -. It returns the resulting number. Wrong input throws an error.
$ rpn 3 4 +
7
$ rpn 5 1 2 + -
2
[!NOTE] Replace the project name, description, demonstration and badge URLs with your own. Show what your project does before asking people to read further.
You will need Git, Node.js at the version in .node-version, and Yarn (via Corepack).
[!WARNING] fnm is a Node.js version manager, which installs
nodeat the version we specify in .node-version. We recommend to install fnm using your package manager as this is safer than the advice on the fnm and nvm websites (ref).
If you do not use a version manager and instead modify the commands below to use a copy of Node.js from your operating system, this may use your package manager's (possibly ancient) version. That build may fail and will be unsupported by this project.
node --version
corepack --version
Open a terminal (PowerShell on Windows) and use the instructions for your operating system.
On Ubuntu 22.04+ or Debian 12+:
sudo apt update
sudo apt install git
On Fedora:
sudo dnf install git
If your distribution has no fnm package, other fnm installation methods are available, but beware as that page does also recommend some dangerous methods (ref).
Install Apple's Command Line Tools if they are not already installed:
xcode-select --install
Complete the installation dialog. With Homebrew installed, install Git and fnm:
brew install git fnm
Homebrew's node formula is a standalone runtime. It does not honor .node-version. Use fnm instead.
Use winget to install Git and fnm:
winget install --exact --id Git.Git
winget install --exact --id Schniz.fnm
Allow administrator prompts and wait for installation to finish. Open a new PowerShell window so fnm is on PATH.
Clone the project and install dependencies. From this directory, fnm installs the Node.js version in .node-version on first use. CI uses the same file. Corepack installs the Yarn version pinned by packageManager in package.json.
git clone https://github.com/fulldecent/node.js-template.git
cd node.js-template
eval "$(fnm env)"
fnm install
fnm use
corepack enable
node --version
yarn --version
yarn install --immutable
In PowerShell:
fnm env --use-on-cd | Out-String | Invoke-Expression
fnm install
fnm use
corepack enable
node --version
yarn --version
yarn install --immutable
Run the command without a global install:
yarn node src/cli.js 3 4 +
yarn node src/cli.js 5 1 2 + -
[!NOTE] Explain what your users need to install, including the tools your project is built on. Replace the repository URL and command name with your own.
Evaluate an expression. Tokens are non-negative integers, + and -. Operators take the two values on the top of the stack, with the right-hand operand popped last.
yarn node src/cli.js 3 4 +
yarn node src/cli.js 10 3 -
yarn node src/cli.js 5 1 2 + -
From another ES module in this project:
import { rpn } from "./src/index.js";
rpn("3 4 +"); // 7
The command joins its arguments with spaces. Input that uses any other character, that is empty, that leaves the stack short for an operator, or that does not reduce to one number, throws an error. The command writes that error to standard error and exits with status 1.
[!NOTE] Explain how to use your project, including the limits that matter to users.
Thank you for taking an interest in improving Simple RPN calculator and the programs of people using it!
Follow the installation instructions above to get Git, fnm, Node.js and Yarn. Work from the project directory. The implementation is in src/index.js and src/cli.js; you can run it without a global install:
yarn node src/cli.js 3 4 +
Commit yarn.lock so application dependencies remain reproducible.
All project updates that we release must conform to our test suite. GitHub Actions runs checks on pushes to main and pull requests. You can also run them locally before sending proposed changes:
yarn test
yarn format
The tests in test/rpn.test.js check addition, subtraction, chained operators, invalid input and the command-line program. They check the exit status, standard output and standard error of the actual program.
With an actively maintained version of Node.js installed, correct other formatting issues before sending proposed changes:
npx prettier@latest --check . --write
npx markdownlint-cli@latest "**/*.md" --fix
Yarn puts install outputs in the ignored node_modules/ directory. Packed releases go in the ignored dist/ directory.
Use fix:, feat: or BREAKING CHANGE: in your commit messages. This triggers our bot to make a release draft pull request. Merging that pull request triggers a new tag and GitHub Release.
The release workflow uses Release Please's simple release type. Set the version in package.json to the proposed release version before merging the release pull request.
Build and test installs dependencies, runs tests, packs a tarball, then attests and uploads it. The release includes simple-rpn-calculator.tgz and release.sigstore.jsonl, containing build provenance and version attestations.
[!NOTE] In your GitHub repository settings, under Actions, General, Workflow permissions, select read and write permissions and check "Allow GitHub Actions to create and approve pull requests". Under General, Releases, enable release immutability. Attestations are available for public repositories; private repositories require GitHub Enterprise Cloud.
The project administrator completes these maintenance tasks each month. If they are 3+ months late, please remind them or send your own issue/pull request.
fnm install reads that file.package.json (packageManager). Update it with yarn set version stable && yarn when a newer stable version is appropriate.yarn upgrade-interactive.We are people who write Node.js modules and command-line tools. Sometimes we need a tiny, dependency-free starting point with pinned tooling and a test that actually runs the program.
Simple RPN calculator does that one job: evaluate reverse Polish notation with add and subtract, and reject input that is not digits, spaces, + and -. It keeps the package empty of runtime dependencies.
We specifically will not add multiply, divide, parentheses, decimal numbers or a graphical interface.
[!NOTE] Introduce your community, explain what is in scope and say what is out of scope. Help people recognize when their own work belongs here.
curl|sh method (fnm issue)..yarnrc.yml sets enableScripts to true (Yarn 4.14 defaults to false) and npmMinimalAgeGate to 0 (Yarn 4.12 defaults to one day). approvedGitRepositories is "**", which approves every git dependency. Yarn: Security[!NOTE] Carefully consider which license to apply to your project and replace the copyright line in LICENSE.md. Cite external sources that materially informed your decisions, including the release of this Node.js template you used.