@moar/core-ts

Project template for TypeScript libraries

Quickstart

1. Setup a clone of this repo:

   gh repo clone blightio/moar-core-ts <your package name> && cd <your package name> && yarn

2. Run the bootstrapper script:

   yarn -s bootstrap \
      --repoOrg '<your org>/<your repo>' \
      --developerName '<your full name>' \
      --packageName '<your package name>' \
      --createGithubRepo

3. Setup a repo secret called NPM_TOKEN containing an npm token for CI package publishing.

Example:

gh repo clone blightio/moar-core-ts foobar \
   && cd foobar \
   && yarn \
   && yarn -s bootstrap \
      --repoOrg 'blightio/foobar' \
      --developerName 'Jason Kuhrt' \
      --packageName 'foobar' \
      --createGithubRepo

Features

1. TypeScript

   1. Optimal settings for the safety of your implementation
      1. strict mode enabled.
      2. All lint flags enabled:
         • noImplicitReturns
         • noFallthroughCasesInSwitch
         • noUncheckedIndexedAccess
         • noPropertyAccessFromIndexSignature
         • noImplicitOverride
   2. .tsbuildinfo cache setup, output discretely into node_modules/.cache
   3. Base tsconfig.json shared across tests, src, and ts-node.
   4. ts-patch setup for enhanced language features:
      1. ts-nameof for pulling the names of identifier down into your runtime!
      2. typescript-transform-paths for a working tsconfig paths config!
      3. Tricky ts-node configuration taken care of.
      4. Intentional avoidance of ttypescript
   5. Optimal output setup for your users
      1. Target ES2019 which Node as low as version 12 has good support for (kangax compat table).
      2. declaration so your users can power their intellisense with your packages typings.
      3. declarationMap enabled to make your published source code be navigated to when your users use "go to definition".
      4. package.json typeVersions used to emit only one set of declaration files shared by both CJS and ESM builds.
      5. sourceMap enabled to allow your users' tools to base off the source for e.g. stack traces instead of the less informative derived built JS.
      6. importHelpers enabled to minimize build size.

2. ESLint

   1. TypeScript integration
   2. TS type-checker powered eslint checks enabled
   3. Prettier integration using just eslint-config-prettier. eslint-plugin-prettier is not used to avoid lint noise and slower run time. Prettier is expected to be run by your IDE and your CI and if really neeeded you manually via yarn format.
   4. Setup as a CI check for PRs
   5. Always display as warning to keep IDE error feedback for TypeScript (CI enforces warnings).

3. jest for testing

   1. Setup with ts-jest
   2. Handy watch mode plugins
      1. jest-watch-typeahead
      2. jest-watch-suspend
      3. jest-watch-select-projects
   3. jest.config.ts for type safe & intellisense configuration!
   4. typescript-snapshots-plugin for viewing snapshots on hover of .toMatchSnapshot method!

4. dripip for release management

5. Simple succinct friendly low-barrier issue templates

   1. Emojis ✈️
   2. Feature / bug / docs / something-else
   3. Config to display discussions link right in new issue type listing UI

6. Prettier for code formating

   1. Prisma Labs config preset, 110 line width
   2. Setup as a CI check for PRs
   3. VSCode extension in recommended extensions list so that when collaborators open the project they'll get prompted to install it if they haven't already.
   4. npm script

7. format-imports

   1. Setup as a CI check for PRs
   2. VSCode extension in recommended extensions list so that when collaborators open the project they'll get prompted to install it if they haven't already.
   3. npm script
   4. Config in package.json to disable empty lines between groups.

8. npm scripts for development lifecycle

   1. clean to remove cache and dist files
   2. build that runs clean beforehand
   3. prepublishOnly that runs build beforehand
   4. format to quickly run prettier and format-imports over whole codebase
   5. lint to quickly run eslint over whole codebase

9. CI with GitHub Actions

   1. Separate trunk and pull-request (PR) workflows.
   2. Dependency install cache enabled.
   3. On PR:
      1. Prettier Check
      2. Format Imports Check
      3. Lint Check
      4. Tests across matrix of mac/linux/windows for Node 14/16
   4. On trunk:
      1. Tests across matrix of mac/linux/windows for Node 14/16
      2. Automated canary release

10. Renovate configuration

    1. JSON Schema setup for optimal intellisense
    2. Group all non-major devDependency updates into single PR (wich "chore" conventional commit type)
    3. Group all major devDependency updates into single PR (with "chore" conventional commit type)
    4. Group all non-major dependency updates into single PR (with "deps" conventional commit type)
    5. Each major dependency update in own PR (with "deps" conventional commit type)

11. Yarn 1 for package management (mostly for great script runner behaviour)

12. Hybrid package build CJS+ESM (see Dr. Axel's article about this)

    1. Use exports field to give support to both modern import and legacy require consumers using Node 12.x and up. For details about the exports field refer to the Official Node.js Docs about it.
    2. Use main field for legacy versions of Node (before 12.x) requiring the CJS build.
    3. Use module field for legacy bundlers importing the ESM build.

13. VSCode Settings

    1. Optimize project search by ignoring dist-cjs/dist-esm directories.
    2. Enable typescript.enablePromptUseWorkspaceTsdk so that oneself and collaborators will get prompted to use the workspace version of TypeScript instead of the one in the editor.

Tips

1. Update your GitHub org's label-sync repo to include config for your new repo, assuming your org has such a thing. For example for Prisma Labs: prisma-labs/label-sync.