@ozum/create-tsm
TypeScript icon, indicating that this package has built-in type declarations

1.2.14 • Public • Published

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.
  • 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 😃 Tests and check lint, audit, format, and dependencies of the project.
release 😃
  • Verifies your project
  • Commits & pushes the project to the GitHub
  • Ensures your commit message is conventional
  • Lets GitHub CI/CD release your package to the NPM with correct version number using semantic-release
test 😃 Tests the project.
dev Starts build process in watch mode.
lint Lints and fixes errors when possible.
format Formats the files.
build Builds your project.
docs:api Builds API docs with TypeDoc.
commit Executes git commit with Commitizen, but you don't need to use it, because Husky catches git commit.
commitlint Executes tasks for commitlint.
precommit Executes Lint Staged tasks and verifications.
prepare Ensures Husky is installed.

Legend Purpose Description
😃 For end user Should be used by the end user in a normal workflow.
Occasional use Used by end user occasionally when needed.
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." }

Package Sidebar

Install

npm i @ozum/create-tsm

Weekly Downloads

4

Version

1.2.14

License

ISC

Unpacked Size

81.5 kB

Total Files

66

Last publish

Collaborators

  • ozum