https://github.com/ozum/create-tsm
Highly opinionated and customizable boilerplate for creating and updating TypeScript modules.
https://github.com/ozum/create-tsm
Last synced: about 2 months ago
JSON representation
Highly opinionated and customizable boilerplate for creating and updating TypeScript modules.
- Host: GitHub
- URL: https://github.com/ozum/create-tsm
- Owner: ozum
- License: isc
- Created: 2023-07-20T14:51:07.000Z (almost 2 years ago)
- Default Branch: main
- Last Pushed: 2024-05-30T09:35:50.000Z (12 months ago)
- Last Synced: 2025-03-01T08:49:20.696Z (3 months ago)
- Language: TypeScript
- Size: 552 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# 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
```sh
$ 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)
```sh
$ 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](https://github.com/ozum/create-tsm/blob/main/.github/workflows/base-build-and-test.yml) 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](https://docs.github.com/en/actions/using-workflows/reusing-workflows).
- **(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`](https://semantic-release.gitbook.io/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](https://eslint.org/) with three configurations. (`ozum`, `ozum-minimum`, `ozum-maximum`). See [eslint-config-ozum](https://www.npmjs.com/package/eslint-config-ozum)
- [Prettier](https://prettier.io/)
- [EditorConfig](https://editorconfig.org/)
- [Commitizen](http://commitizen.github.io/cz-cli/)
- [commitlint](https://commitlint.js.org/)
- [Jest](https://jestjs.io/)
- [Knip](https://github.com/webpro/knip)
- [Lint Staged](https://github.com/okonet/lint-staged)
- [TypeDoc](https://typedoc.org/)
- [GitHub Actions](https://docs.github.com/en/actions)
- [Husky](https://typicode.github.io/husky/)
- [swpm](https://github.com/deinsoftware/swpm)
- [semantic-release](https://semantic-release.gitbook.io/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 project
- Commits & pushes the project to the GitHub
- Ensures your commit message is [conventional](https://www.conventionalcommits.org/)
- Lets GitHub CI/CD release your package to the NPM with correct version number using [semantic-release](https://semantic-release.gitbook.io/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](https://typedoc.org/). |
| commit | :heavy_exclamation_mark: | Executes `git commit` with [Commitizen](http://commitizen.github.io/cz-cli/), but you don't need to use it, because [Husky](https://typicode.github.io/husky/) catches `git commit`. |
| commitlint | :heavy_exclamation_mark: | Executes tasks for [commitlint](https://commitlint.js.org/). |
| precommit | :heavy_exclamation_mark: | Executes [Lint Staged](https://github.com/okonet/lint-staged) tasks and verifications. |
| prepare | :heavy_exclamation_mark: | Ensures [Husky](https://typicode.github.io/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](https://turbo.build/repo) 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](https://github.com/settings/personal-access-tokens/new).
- 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." }`