Description

Highly opinionated and customizable boilerplate for creating and updating TypeScript modules.

No need to install anything. Just use your package manager.

Creates your project and provides automatic verification, push, and release scripts.

Usage

Create

$ mkdir my-project
$ NPM_TOKEN=xyz123 GITHUB_TOKEN=xyz123 npm init @ozum/tsm@latest

It will ask your package manager. You can select npm, pnpm, or yarn even if you started the script with npm init.

Update (Experimental)

$ npx @ozum/create-tsm@latest

• Updates package.json dependencies and base scripts starting with base:.
• Updates files in .husky and config/tsm.
• Adds new configs to the root if any are available.
• Does NOT change/update configs in the root directory.
• Does NOT change/update GitHub workflows.

Features

• Supports npm, pnpm and yarn.
• Creates package.json with necessary devDependencies and development-related scripts.
• Allows you to use up-to-date shared GitHub workflow or the workflow at the time of initialization. (Based on the answer to the use shared GitHub workflow question)
• Updates existing package.json, base configurations, and base scripts. Does not touch derived scripts and configurations.
  • Writes package.json if only it is changed.
  • Executes install if only dependencies have changed.
• Creates package.json scripts prefixed with base:, so you can customize yours without risking future updates.
• Where possible, creates base scripts in the config/tsm directory, so you can customize yours without risking future updates.
• Provides reusable GitHub workflow.
• (Optional) Creates a GitHub repository.
• (Optional) Adds NPM_TOKEN secret to the created repository.
• Never stores the security tokens.
• Creates a GitHub workflow for CI/CD which utilizes Semantic Release
• Let's GitHub Workflow verify (test, lint, build, audit) and publish the npm package.
• Has stringent ESLint rules but can be customized.
• Configures and supports many tools out of the box. No configs are needed.
  • ESLint with three configurations. (ozum, ozum-minimum, ozum-maximum). See eslint-config-ozum
  • Prettier
  • EditorConfig
  • Commitizen
  • commitlint
  • Jest
  • Knip
  • Lint Staged
  • TypeDoc
  • GitHub Actions
  • Husky
  • swpm
  • semantic-release
• Generates LICENSE file.

Scripts

Below are the package.json scripts generated and their default behavior. Do not change the scripts starting with base: because this tool will overwrite them during the update.

| name | EU | description | | ---------- | ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | verify | :smiley: | Tests and check lint, audit, format, and dependencies of the project. | | release | :smiley: | Verifies your projectCommits & pushes the project to the GitHubEnsures your commit message is conventionalLets GitHub CI/CD release your package to the NPM with correct version number using semantic-release | | test | :smiley: | Tests the project. | | dev | :question: | Starts build process in watch mode. | | lint | :question: | Lints and fixes errors when possible. | | format | :question: | Formats the files. | | build | :question: | Builds your project. | | docs:api | :question: | Builds API docs with TypeDoc. | | commit | :heavy_exclamation_mark: | Executes git commit with Commitizen, but you don't need to use it, because Husky catches git commit. | | commitlint | :heavy_exclamation_mark: | Executes tasks for commitlint. | | precommit | :heavy_exclamation_mark: | Executes Lint Staged tasks and verifications. | | prepare | :heavy_exclamation_mark: | Ensures Husky is installed. |

| Legend | Purpose | Description | | ------------------------ | -------------- | --------------------------------------------------------------------------------- | | :smiley: | For end user | Should be used by the end user in a normal workflow. | | :question: | Occasional use | Used by end user occasionally when needed. | | :heavy_exclamation_mark: | Special need | Normally not used by end user. Only needed for customization or special purposes. |

What about Monorepo?

TurboRepo is an excellent monorepo tool and easy to learn and start.

I suggest deleting the created GitHub Action file because Semantic Release does not support monorepos.

I examined several tools but couldn't find an easy way to publish multiple packages using Semantic Release with mono repos.

I'm open to suggestions for monorepo support if the solution is

• Easy to setup for end users
• Easy to maintain for end users
• Unobtrusive
• Robust
• Widely supported

(Optional) GitHub Access Token Permissions

Optionally, this boilerplate can create a GitHub repository and add the NPM_TOKEN secret. I advise creating fine-grained personal access tokens for increased security to limit actions. You can create fine-grained access tokens here.

• Administration: Read and write (To create a GitHub repository)
• Metadata: Read-only (Mandated by GitHub)
• Secrets: Read and write (This is OPTIONAL and used to add NPM_TOKEN)

FAQ

Q: How to customize package.json scripts? A: There are base and normal scripts. Add your custom tasks to the normal scripts without changing the base: scripts. For example: { "verify": "my-task && swpm run base:verify" }

Q: How to change or remove coverage thresholds of the tests? A: Add jest.config.js the following: coverageThreshold: { global: { branches: 0, functions: 0, lines: 0, statements: 0 } }

Q: How to turn off tests? A: Change test script in package.json as similar to { "test": "echo No tests are available. Skipping testing step." }