Skip to content

README.md

Latest commit

 

History

History
271 lines (206 loc) · 8.12 KB

README.md

File metadata and controls

271 lines (206 loc) · 8.12 KB


node-ts-package

A feature-rich Node.js TypeScript package template designed to boost productivity,
ensure code quality, and provide best practices out of the box.

Report Bug · Request Feature


Table of Contents

Features

Feature Description
Devbox A command-line tool that lets you easily create an isolated, reproducible development environment. See the Devbox section for more info.
pnpm A fast and efficient package manager for JavaScript and Node.js that uses a content-addressable filesystem to store files.
semantic-release An automated versioning and package publishing tool that adheres to Semantic Versioning. This ensures that versions are incremented based on the content of commits and makes package publishing a breeze.
Vitest A Jest compatible testing utility with better performance.
tsup A fast, easy-to-configure Node.js and browser bundler that supports TypeScript, ES Modules, CommonJS, and more.
ESLint A tool to identify and report on patterns found in ECMAScript/JavaScript code. Configured with the comprehensive @phi.school/eslint-config to align with organization coding standards.
Prettier An opinionated code formatter that supports multiple languages and integrates with most editors. Configured with @phi.school/prettier-config, to adhere to the organization's preferred code style.
commitlint A tool to enforce conventional commit messages, ensuring consistency and automated versioning compatibility.
husky A tool to improve Git hooks, making it easier to enforce quality checks, using linters, and more.
lint-staged A tool that runs linters against pre-committed code in Git, helping to ensure that you're only committing files that meet your linting criteria.
dotenv A zero-dependency module that loads environment variables from a .env file into process.env, enhancing the application's configuration management.

Prerequisites

Devbox

Devbox is a Nix-based environment and package manager that standardizes development environments across teams. By ensuring every developer has the same tool versions locally, collaboration becomes smoother. Some key features include:

  • Generating a devcontainer for use with VSCode.
  • Creating a Dockerfile to build a production image with the identical development tools.
  • Integration with direnv, auto-loading the isolated shell upon entering the project directory.
  • Compatibility with the Devbox GitHub Action, enabling recreation of your development environment in workflows.

Installing Devbox:

Installation is straightforward, and Devbox is compatible with macOS, Linux, and Windows. See the Devbox docs for detailed instructions.

degit

To install this template efficiently, utilize degit. You can globally install degit with your preferred package manager:

pnpm install -g degit
# OR
npm install -g degit
# OR
yarn global add degit
# OR
nix-env -iA nixpkgs.nodePackages.degit

Installation

Once degit is installed, initiate your project with the following command, substituting <YOUR_PROJECT_NAME> with your project's name:

degit phi-school/project-templates/node-ts-package <YOUR_PROJECT_NAME>
cd <YOUR_PROJECT_NAME> && devbox shell

For an automated devbox shell load upon entering the project directory, install & configure direnv.

Note:
Upon entering the project directory for the first time after setting up direnv, you will be prompted with a security notification. You must run direnv allow to grant permission. Once allowed, your development environment will auto-load every time you enter the directory.

Post-Installation Checklist

After installing the template, make sure to complete the following tasks to personalize and configure your project:

  1. Update the package.json fields:
  • name: Set this to your project name.
  • description: Add a brief description of your project.
  • repository: Update the repository URL to match your own project's repository.
  • author: Add your name or your organization's name.
  • license: Update the license field if needed.
  1. Update the LICENSE file:
  • Replace the placeholder name and year with your own name (or organization name) and the current year.
  1. Set up environment variables:
  • Create a .env file with any environment-specific values your project requires.
  1. Configure GitHub Actions settings:
  • Add an NPM_TOKEN secret for publishing to npm.
  • Ensure workflow permissions are correctly configured:
    • Grant required read and write permissions.
    • Permit GitHub Actions to create, review, and merge pull requests.

Usage

The template includes several handy scripts:

  • build: Compile the TypeScript project with tsup.
  • format: Prettify the codebase using Prettier.
  • lint: Conduct code linting via ESLint.
  • test: Launch tests with Vitest.
  • type-check: Check code types using TypeScript.

Contributing

Contributions are welcome! For a detailed guide on how to contribute, please refer to the Contributing & Development section in the repository root.

License

This project is released under the MIT License. © 2023-Present phi school