Node

This is a template repository for a Node.js with TypeScript and Vitest project.

How to use

Creating a repository from a template is similar to forking a repository, but there are important differences, see more here.

See here how to create a repository from this template.

You can also use gh repo create [<name>] [flags] passing the --template joaovbrandon/node-tstarter, see more here.

Stack

This Node.js Project Starter uses:

pnpm
- Is recommended to keep using pnpm, but npm or yarn can be used, for that delete the pnpm-lock.yaml and install with your prefered tool
TypeScript
dotenv for environment variables
Vitest for tests
tsx for development
tsup for bundling
EditorConfig for consistent coding styles between different editors and IDEs
prettier for code formatting
eslint for code linting
husky + lint-staged for git hooks
commitlint for commit messages linting
commitizen as a cli helper tool for commit (optional use)

Recommended Libraries

These are other recommended libraries that isn't in this starter because it is not necessary for all projects:

pino and pino-pretty for logs
pino-http for https logs
tRPC for End-to-end typesafe APIs
Zod for schema validation with static type inference
date-fns and date-fns-tz for date manipulation
RxJS for reactivity
SuperTest for HTTP tests

Scripts

Feel free to modify the scripts in the package.json file as you want.

Tests

Run pnpm test to run tests and watch it
Run pnpm test <test-file-path> to run this single file tests and watch it (example: pnpm test ./src/app.test.ts)
Run pnpm test:ui to run tests with the Vitest UI
Run pnpm test:coverage to run generate and see the test coverage

See CI test scripts in the package.json file.

Development

Run pnpm dev and the app will start.

Build

Run pnpm build:staging (build with sourcemap) or pnpm build:production.

Code Patterns & Types

Run pnpm typecheck to check types
Run pnpm prettier to check code formatting
Run pnpm prettier:fix to check and fix issues with code formatting
Run pnpm lint to check eslint rules
Run pnpm lint:fix to check and fix eslint rules

Code Patterns Configs

This starter uses the following ESLint packages:

See details in the .eslintrc.cjs and .prettierrc files.

Commit Patterns

This starter uses commitlint with @commitlint/config-conventional to check commit messages.

You can customize the commitlint rules as you wish, see more at the commitlint docs.

This starter also have commitizen configured, that is a cli helper tool for commit, to use it run pnpm commit instead of git commit to commit.

Environment Variables

This starter uses dotenv for environment variables, you can create the .env file in the project root and add your environment variables to develop locally, don't forget to add the variables in your staging and production servers.

The .env.sample file is a place to add the variables without values, to be a guide for other developers.

CI

commit-msg hook

Husky is used to check commit message pattern before each commit.

pre-commit hook

Husky and lint-staged are used to check Types, Lint, Prettier and tests before each commit.

GitHub Actions

This starter have 2 GitHub workflows:

auto-author-assign.yaml to auto assign the Pull Request author to the Pull Request
ci.yaml to check commit messages pattern, Types, Lint, Prettier, tests and Production Build

The starter also have Pull Request and Issues templates, see in the .github folder.

It is recommended to create a Branch protection rule for the main branch in your repository, so you can require approvals and status checks to pass for Pull Requests.

TODO File

You can create a TODO.md file in the project root to write personal notes and todos. This file is in the .gitignore and will be not commited.