Typescript launchpad

Ready to use typescript environment.

Table of contents

1. Available commands
2. Explore code samples
3. Typescript configuration details
4. Footnotes

Available commands

# clone the repository using degit
npx degit https://github.com/mulekick/typescript-launchpad.git my-awesome-typescript-project

# cd into your project
cd my-awesome-typescript-project

# clean install dependencies
npm ci

# list project types
npm run list

# validate project types
npm run typecheck

# lint project files
npm run lint

# run your code using tsx
npx tsx src/my-awesome-code.ts

# build declaration files
npm run types:build

# build executable files
npm run build

# build documentation
npm run docs:build

Caution : ambient modules and handwritten *.d.ts files are not included in the build by default.

Explore code samples

This repo ships with code samples that illustrate concepts from the typescript handbook :

Module	Description
src/compiler-checks	Built-in compiler checks.
src/basic-types	Basic types.
src/composed-types	Composed types.
src/code-narrowing	Code narrowing.
src/typed-functions	Typed functions.
src/generic-types	Generic types.
src/advanced-features	Advanced features.
src/conditional-types	Conditional types.
src/functional-programming	Functional programming.
src/namespaces	Namespaces.
src/declaration	Sample declaration file.
src/implementation	Sample implementation file.
src/ambient	Ambient module declaration.

Typescript configuration details

tsconfig.json is the reference for up to date, fine tuned typescript configuration.

The following compilerOptions keys need special attention :

• "allowImportingTsExtensions": true
  • Allowed because noEmit is true.
  • tsx manages execution while babel manages building.
• "noUncheckedSideEffectImports": true
  • Resolves and checks side effects imports explicitly.
  • Non *.ts imports may have to be @ts-ignored.
• "allowArbitraryExtensions": false
  • Opts out of writing *.d.ts files for non *.ts files (ex. *.css) for successful compilation.
• "allowJs": false
  • Opts out of typechecking *.js files.
  • *.d.ts files will be generated with tsc or declared as ambient modules.
• "checkJs": false
  • See above.
• "maxNodeModuleJsDepth": 0
  • See above.
• "declarationMap": false :
  • Opts out of generating sourcemaps since tsx natively supports debugging.
• "sourceMap": false (see above).
• "isolatedModules": true :
  • Ensures that *.ts code can be safely transpiled by external bundlers (vite, babel etc).
• "verbatimModuleSyntax": true :
  • Forces being specific about importing as a type versus importing as a value.
• "allowSyntheticDefaultImports": true :
  • Emulates a default export for modules that do not have one.
  • Also, import * as X from "Y" should never be used since it only imports own properties of exported values.
• "skipLibCheck": false
  • Ensures that types for the project are checked exhaustively at compilation.

Footnotes

• I personally opt to separate declarations from implementations as much as possible for clarity.
• When things get complicated, it's better to separate concerns by coding raw JS and typing it afterwards.
• As opposed to ECMA, typescript maintainers sometimes have a tendency to overengineer things.
• Another striking example of that tendency can be found here.
• The remedy to that is to stick to useful features and use tried and tested coding patterns.
• Pro tip : when types created from a generic type serve almost identical implementations, the generic type probably shouldn't exist.