Node.js 템플릿, curl 파이프 방식 대신 패키지 관리자로 런타임 설치 권장

간단한 RPN 계산기[](https://github.com/fulldecent/node.js-template#simple-rpn-calculator)

이 템플릿은 Node.js 프로젝트를 시작할 때 사용할 수 있다. 명확한 구조와 작동 예제, 로컬 개발 및 CI에 고정된 Node.js·Yarn 버전, 지속적 통합에서 실행하는 테스트와 포맷 검사, Release Please를 이용한 자동 릴리스와 SLSA 출처 증명을 제공한다.

템플릿의 범위

Node.js 프로젝트를 관리하는 이들은 더 안전한 설치 경로와 좋은 기본 설정을 제안하기 위해 이 시작점을 유지한다. 다양한 프로젝트의 요구를 다루도록 폭넓게 설계했으며, README와 기본 포맷 규칙, 지속적 통합 린팅을 포함한다. GitHub와 GitHub Actions만을 프로젝트 호스팅 수단으로 지정하지는 않는다. GitHub 관련 안내는 다른 환경에서 구현할 때 참고할 수 있다.

아래 예시는 가상의 프로젝트를 위한 템플릿이다.

[](https://github.com/fulldecent/node.js-template/actions/workflows/build-test.yml) [](https://github.com/fulldecent/node.js-template/actions/workflows/lint.yml)

간단한 RPN 계산기는 역폴란드 표기법으로 덧셈과 뺄셈을 수행한다. 숫자와 공백, +, -로 된 문자열을 읽어 결과를 반환하며, 잘못된 입력에는 오류를 낸다.

```text

$ rpn 3 4 +

7

$ rpn 5 1 2 + -

2

```

프로젝트 이름과 설명, 데모, 배지 URL은 각자의 것으로 바꾸도록 안내한다. 사용자가 더 읽기 전에 프로젝트가 무엇을 하는지 보여주는 구성이다.

설치

Git, .node-version에 지정된 버전의 Node.js, Corepack을 통한 Yarn이 필요하다.

fnm은 .node-version에 지정된 버전의 node를 설치하는 Node.js 버전 관리자다. 템플릿은 fnm과 nvm 웹사이트의 안내보다 안전한 방법이라며 패키지 관리자로 fnm을 설치하도록 권장한다. 버전 관리자를 쓰지 않고 운영체제의 Node.js를 사용하면 패키지 관리자가 제공하는 오래된 버전일 수 있으며, 이 경우 빌드가 실패할 수 있고 프로젝트 지원 대상이 아니다.

```text

node --version

corepack --version

```

터미널을 열고 운영체제에 맞는 방법을 따른다. Windows에서는 PowerShell을 사용한다.

Linux

Ubuntu 22.04 이상 또는 Debian 12 이상:

```text

sudo apt update

sudo apt install git

```

Fedora:

```text

sudo dnf install git

```

배포판에 fnm 패키지가 없다면 다른 fnm 설치 방법을 이용할 수 있다. 다만 해당 페이지에도 위험할 수 있는 방법이 안내돼 있다고 경고한다(참고).

macOS

Apple 명령줄 도구가 설치되지 않았다면 설치한다.

```text

xcode-select --install

```

설치 대화상자를 완료한 뒤 Homebrew로 Git과 fnm을 설치한다.

```text

brew install git fnm

```

Homebrew의 node 공식은 독립 실행형 런타임이라 .node-version을 따르지 않는다. 대신 fnm을 사용한다.

Windows

winget으로 Git과 fnm을 설치한다.

```text

winget install --exact --id Git.Git

winget install --exact --id Schniz.fnm

```

관리자 권한 확인을 허용하고 설치가 끝날 때까지 기다린다. fnm이 PATH에 추가되도록 새 PowerShell 창을 연다.

빌드 및 설치

프로젝트를 복제하고 의존성을 설치한다. 프로젝트 디렉터리에서 fnm은 처음 사용할 때 .node-version의 Node.js 버전을 설치한다. CI도 같은 파일을 사용한다. Corepack은 package.json의 packageManager에 고정된 Yarn 버전을 설치한다.

```text

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

```

PowerShell에서는 다음을 실행한다.

```text

fnm env --use-on-cd | Out-String | Invoke-Expression

fnm install

fnm use

corepack enable

node --version

yarn --version

yarn install --immutable

```

전역 설치 없이 명령을 실행할 수 있다.

```text

yarn node src/cli.js 3 4 +

yarn node src/cli.js 5 1 2 + -

```

템플릿 안내는 각 프로젝트에 필요한 설치 도구를 설명하고, 저장소 URL과 명령 이름을 자체 값으로 바꾸도록 권한다.

사용법

표현식을 계산한다. 토큰은 음이 아닌 정수와 +, -이며, 연산자는 스택 맨 위의 두 값을 사용한다. 오른쪽 피연산자를 마지막에 꺼낸다.

```text

yarn node src/cli.js 3 4 +

yarn node src/cli.js 10 3 -

yarn node src/cli.js 5 1 2 + -

```

프로젝트의 다른 ES 모듈에서 사용할 수도 있다.

```text

import { rpn } from "./src/index.js";

rpn("3 4 +"); // 7

```

명령은 인수를 공백으로 이어 붙인다. 허용되지 않은 문자가 있거나 입력이 비어 있는 경우, 연산에 필요한 스택 값이 부족한 경우, 계산 결과가 숫자 하나로 정리되지 않는 경우에는 오류가 발생한다. 명령은 오류를 표준 오류에 쓰고 종료 상태 1로 끝난다.

개발과 테스트

설치 안내에 따라 Git, fnm, Node.js, Yarn을 준비하고 프로젝트 디렉터리에서 작업한다. 구현은 src/index.js와 src/cli.js에 있다. 전역 설치 없이 다음처럼 실행할 수 있다.

```text

yarn node src/cli.js 3 4 +

```

애플리케이션 의존성을 재현 가능한 상태로 유지하려면 yarn.lock을 커밋한다.

릴리스할 변경은 테스트를 통과해야 한다. GitHub Actions는 main 브랜치에 푸시하거나 풀 리퀘스트를 열 때 검사 작업을 실행한다. 변경 제안 전에 로컬에서도 실행할 수 있다.

```text

yarn test

yarn format

```

test/rpn.test.js의 테스트는 덧셈, 뺄셈, 연속 연산, 잘못된 입력, 명령줄 프로그램을 검사한다. 실제 프로그램의 종료 상태와 표준 출력, 표준 오류도 확인한다.

제안한 변경을 보내기 전에 지원 중인 Node.js 버전에서 다른 포맷 문제도 정리하도록 안내한다.

```text

npx prettier@latest --check . --write

npx markdownlint-cli@latest "**/*.md" --fix

```

Yarn 설치 결과는 무시 대상인 node_modules/에 저장된다. 패키징한 릴리스는 무시 대상인 dist/에 생성된다.

릴리스

커밋 메시지에 fix:, feat: 또는 BREAKING CHANGE:를 사용하면 봇이 릴리스 초안 풀 리퀘스트를 만든다. 해당 풀 리퀘스트를 병합하면 새 태그와 GitHub Release가 생성된다.

릴리스 워크플로는 Release Please의 simple 릴리스 유형을 사용한다. 릴리스 풀 리퀘스트를 병합하기 전에 package.json의 버전을 제안된 릴리스 버전으로 설정해야 한다.

빌드 및 테스트 작업은 의존성을 설치하고 테스트를 실행한 뒤 tarball을 패키징하고, 출처 증명을 생성해 업로드한다. 릴리스에는 simple-rpn-calculator.tgz와 빌드 출처 및 버전 증명을 담은 release.sigstore.jsonl이 포함된다.

GitHub 저장소 설정의 Actions, General, Workflow permissions에서 읽기 및 쓰기 권한을 선택하고 “Allow GitHub Actions to create and approve pull requests”를 체크하라고 안내한다. General, Releases에서 릴리스 불변성도 활성화해야 한다. 증명 기능은 공개 저장소에서 제공되며 비공개 저장소에는 GitHub Enterprise Cloud가 필요하다.

유지 관리

프로젝트 관리자는 매달 유지 관리 작업을 수행한다. 3개월 이상 늦어지면 알리거나 직접 이슈 또는 풀 리퀘스트를 보내도록 요청한다.

• .github/workflows의 외부 Actions에 새 버전이 있는지 확인하고 안전하다면 업데이트한다. actions/ 조직의 GitHub 지원 Actions는 간단한 검토만 필요할 수 있다.
• .node-version의 Node.js 버전을 검토하고 적절한 새 버전이 있으면 갱신한다. fnm install은 이 파일을 읽는다.
• package.json의 packageManager에 적힌 Yarn 버전을 검토한다. 안정 버전 갱신이 적절하면 yarn set version stable && yarn으로 업데이트한다.
• yarn upgrade-interactive로 직접 의존성을 검토한다.

프로젝트 범위와 보안 안내

이 템플릿은 Node.js 모듈과 명령줄 도구를 만드는 사람을 위한 작고 의존성이 없는 시작점이다. 도구 버전을 고정하고 실제 프로그램을 실행하는 테스트를 포함한다. 예시 프로젝트인 Simple RPN calculator는 덧셈과 뺄셈으로 역폴란드 표기법을 계산하며, 숫자·공백·+·- 외의 입력은 거부한다. 런타임 의존성은 두지 않는다. 곱셈, 나눗셈, 괄호, 소수, 그래픽 인터페이스는 범위에 포함하지 않는다.

템플릿은 제목에 고유명사만 대문자로 표기한다. fnm은 fnm 및 nvm 웹사이트가 안전하지 않은 curl|sh 방법을 선호한다는 이유로 패키지 관리자로 설치할 것을 권장하며, 관련 자료로 fnm 이슈를 든다. 프로젝트는 node.js-template의 모범 사례를 바탕으로 만들었으며, 사용한 버전은 1.0.0이다(node.js-template).

.gitignore의 Node.js 제외 규칙은 GitHub의 Node gitignore에서 가져왔다. .yarnrc.yml은 enableScripts를 true로 설정한다(Yarn 4.14의 기본값은 false). npmMinimalAgeGate는 0으로 설정한다(Yarn 4.12의 기본값은 하루). approvedGitRepositories는 모든 Git 의존성을 허용하는 "**"로 설정한다. 자세한 내용은 Yarn 보안 안내를 참조한다.

프로젝트는 MIT 라이선스로 배포된다. 템플릿은 각 프로젝트에 적용할 라이선스를 신중히 정하고 LICENSE.md의 저작권 문구를 바꾸며, 결정에 실질적인 영향을 준 외부 자료를 인용하라고 안내한다.