DEV Community: t7yang

Dark Lavender - A beautiful and useful VSCode theme

t7yang — Sat, 18 Dec 2021 18:54:00 +0000

My first theme — Dark Lavender was released on May 2020. You may wonder why I'd spend so much time to create a new editor theme (it is no easy to create a high quality theme), the answer is simple — I couldn't find a satisfy theme. Thank Material Design color palette, I successfully created a colorful and beautiful theme.

Being a programmer, I'm also teaching JavaScript in my free time. The teaching experience made me think about whether my theme goes beyond good looking and help my student to learn programming? So, I'd start digging into TextMate tokens and scopes, try to find out how to group related tokens, and give them a representative color or font styling. I believe this can help both novice and experienced developers to distinguish different tokens more efficiently.

Language Token

Below I'll describe and demonstrate (in TypeScript) how I use different styling and color to emphasize different tokens.

Each demo provides a screenshot and inline code snippet. The screenshot gives you a preview of the actual effect, and if you want to try the snippet in your editor, you can copy and paste the inline code snippet to your VSCode.

To emphasize the italic effect, I use Victor Mono for screenshots below. If you prefer non-cursive font, Fira Code, Jetbrain Mono, and Iosevka are some of the best choices. I use Rec Mono, a high-quality variable font that supports many bold levels, ligatures, and four variants.

Built-in

Every token such as keyword, variable, or function provided by the language or platform itself is styled in italic. So, try not to re-assign or change its value.

// `import` and `from` are JavaScript keyword
import path from 'path';

// `Date` is JavaScript built-in class
Date.now();

// `JSON` is JavaScript built-in namespace
JSON.stringify({});

// `document` is provide by browser API
document.querySelector('');

keyword

Almost every Programming language has predefined keywords. Dark Lavender divides them into two groups — keyword for declaration or not.

For declaration keywords (including modifier) are colored in red (pink color in MD palette).

// variable declaration keywords
const foo = 'foo';
let bar = 'bar';

// interface declaration keyword
interface ICustomError {}

// class or modifier declaration keywords
class CustomError extends Error implements ICustomError {
  constructor(public readonly code) {
    super();
  }
}

For non-declaration keywords (mostly statement) are colored in purple.

import fs from 'fs/promises';

function check(foo: { isOK: boolean }) {
  for (const key in foo) {
  }

  if (foo.isOK) return 'OK';
  else throw 'NOT OK';
}

Operator

Operators are colored in light green. You may think "What special about operator? Isn't all operators are punctuation? Developer should easily distinguish for them, right?".

Not really, some languages have "word like" operators like new and delete in JavaScript/TypeScript.

With a different color, now you can easily tell which keyword is operator, even you are a novice developer.

1 + 2 - 3 * 4;

new Date();
delete { foo: 123 }.foo;

Primitive Value

There is three main primitive value across almost every programming language — string, number, and boolean. These three primitive value has their own color;

Function may not treat as a value in some languages, but it does exist in almost every language.

Not like other kinds of value, function represent the concept of logic instead of data, so function has its own color.

'this is string';
3.142;
true;
false;

function foo() {}
foo();

Types

Every built-in or custom types and classes are colored in yellow. In many languages, class can be both value and type, so they share the same color.

// Date is a built-in class
const date: Date = new Date();

// `Person` is custom type
// `string`, `number`, and `boolean` are built-in types
interface Person {
  name: string;
  age: number;
  isAdult: boolean;
}

Variable, Parameter and Object Property

When talking about variable in most of the non FP languages, we concern about "Is the variable re-assignable or not?".

For re-assignable, non re-assignable, and language specify variables, they all have their own color, respectively.

var foo1 = 're-assignable';
let foo2 = 're-assignable';
const foo3 = 'non re-assignable'; // foo3 is bold because readonly
let foo4 = () => {};
const foo5 = () => {}; // foo5 is bold too

Node.ATTRIBUTE_NODE; // readonly + built-in => bold + italic

// Parameter is acting like variable, so they share the same color for no doubt
function bar(baz) {}


// language specify variables also have their own color.
// (Material Design red)
this.foo;
true;
false;
undefined;

Object property is acting like variable too, but in Dark Lavender, object property does not share the same color with variable.
Because this can help developer distinguish the difference between them from the situation like destructuring or object literal shorthand.

class Foo {
  constructor(public bar, public readonly baz) {
    this.bar; // normal property
    this.baz; // bold if readonly
  }

  update(arg: { bar: string; baz: string }) {
    const { bar, baz } = arg;
    // property `bar` and variable `bar` have difference color
    // VSCode semantic highlight and textmate treat `baz` with difference perspective
    // the former treat `baz` as property but constant variable for the latter
    // if you disabled semantic highlight in VSCode you may see difference colorizing
    return { bar: bar, baz };
  }
}

Regular Expression

RegExp is one of the most powerful features in programming language, but it is hard to remember which character should escape or which symbol is simply a text rather than a special symbol, even for an experienced developer.

// normal text is color just like string
const regex1 = /123abc/;
// keyword and quantifier in between normal text are colarize differently
const regex2 = /^##*%%?&&$/;
// () [] grouping
const regex3 = /(on|off|[A-Z]{2,3})/;

Conclusion

As you can see, I try to group related tokens and give them a representative color or style, and I believe that this can help you learn coding and understand your code. Besides JavaScript/TypeScript, Dark Lavender also provides basic support for many mainstream languages such as CSS, HTML, Java, Go, C++, and more. I'll keep improving this theme in the future, so if you have any feedback would like to share or find any issue, please let me know. If you like this theme, don't forget to share, comment, and star in VSCode marketplace and github. Thank you.

Type safety in JavaScript with JSDoc and VSCode

t7yang — Tue, 21 Sep 2021 09:47:02 +0000

Type safety in JavaScript with JSDoc and VSCode

TypeScript is one of the popular transpile language to JavaScript that provide type safety feature, but not only TypeScript itself can get the benefit from type safety, but the entire JavaScript community.

This article aim to introduce how to make JavaScript project type safe with JSDoc, TypeScript, and VSCode. Not only make your project more robust, but these technique also can enhance your DX. The premise is that you don't think type is a burden.

This article cover about:

Commonly used of JSDoc tags for type definition.
How to reuse type by import from other files.
How to type your data efficiently with converter.
How to setup and enabled statically type checking in VSCode and compile time checking with tsc.

This article NOT cover about:

What is JavaScript or TypeScript type.
How JavaScript or TypeScript type system work.

NOTE: Every code snippet in this article can found in this repository

Type primitive

/** @type {string} */
const str = 'string';

/** @type {number} */
const num = 123;

/** @type {boolean} */
const bool = true;

/** @type {null} */
const nul = null;

/** @type {undefined} */
const und = undefined;

/** @type {symbol} */
const sym = Symbol('foo');
/** @type {unique symbol} */
const sym = Symbol('bar');

/** @type {*} */
const jsDocAny = 'any value';

/** @type {any} */
const tsAny = 'any value';

NOTE:
In JSDoc, capital type like String is same as string, both mean primitive string.

Type object

Object value including object, array, and function, I'll talk about function later.

Object value

/**
 * JSDoc style
 * @typedef {object} Rgb
 * @property {number} red
 * @property {number} green
 * @property {number} blue
 */

/** @type {Rgb} */
const color = { red: 255, green: 255, blue: 255 };

/**
 * TypeScript style
 * @typedef {{ brand: string; color: Rgb }} Car
 */

/** @type {Car} */
const car = {
  brand: 'Some Brand',
  color: { red: 255, green: 255, blue: 255 },
};

Array value

/**
 * JSDoc style
 * @type {Array.<Rgb>}
 */
const colors1 = [{ red: 0, green: 0, blue: 0 }];

/**
 * TypeScript style
 * @type {Rgb[]}
 */
const color2 = [{ red: 111, green: 111, blue: 111 }];

/**
 * TypeScript style
 * @type {Array<Rgb>}
 */
const color3 = [{ red: 255, green: 255, blue: 255 }];

Type function

/**
 * JSDoc style named function type
 * @callback Add
 * @param {number} x
 * @param {number} y
 * @returns {number}
 */

/** @type {Add} */
const add = (x, y) => x + y;

/**
 * TypeScript style inline function type
 * @typedef {(x: number, y: number) => number} TsAdd
 */

/** @type {TsAdd} */
const tsAdd = (x, y) => x + y;

/**
 * JSDoc style type function with function declaration
 * @param {number} x
 * @param {number} y
 * @returns {number}
 */
function addDec(x, y) {
  return x + y;
}

Optional parameter

/**
 * JSDoc style optional parameter
 * @param {number} [x] optional
 * @param {number=} y number or undefined
 * @param {number} [z=1] optional with default (default not show in type hint)
 */
function jsDocOptional(x, y, z = 1) {}

Rest parameter

/**
 * JSDoc style rest parameter
 * @param {...number} num
 * @returns {number}
 */
function sum(...num) {
  return num.reduce((s, v) => s + v, 0);
}

/**
 * TypeScript style rest parameter
 * @param {number[]} num
 */
function tsSum(...num) {
  return num.reduce((s, v) => s + v, 0);
}

Return type

/**
 * No explicit return value
 * @returns {void}
 */
function noReturn() {
  console.log('no explicit return');
}

/**
 * Function never return
 * @returns {never}
 */
function neverReturn() {
  throw Error('ERRORRRRR');
}

Type class and `this`

class Computer {
  /**
   * @readonly Readonly property
   * @type {string}
   */
  CPU;

  /**
   * _clock type automatic infer from default value
   * @private Private property
   */
  _clock = 3.999;

  /**
   * @param {string} cpu
   * @param {number} clock
   */
  constructor(cpu, clock) {
    this.CPU = cpu;
    this._clock = clock;
  }

  /**
   * @param {string} cpu
   * @returns {void}
   */
  change(cpu) {
    // @ts-expect-error
    this.CPU = cpu; // can not reasign readonly
  }
}

/**
 * Class is both value and type
 * @type {Computer}
 */
const computer = new Computer('Foo', 2.999);

/**
 * @this {HTMLInputElement}
 * @returns {void}
 */
function handleChange() {
  console.log(`The input element's value is ${this.value}`);
}

document.querySelector('input').addEventListener('change', handleChange);

Type literal value

/**
 * Specify string type
 * @typedef {'RED' | 'GREEN' | 'BLUE'} RgbLabel
 */

/** @type {RgbLabel} */
const label = 'BLUE';

/**
 * Enumerate values type
 * @enum {number}
 */
const Status = {
  on: 1,
  off: 0,
};

/** @type {Status} */
const off = Status.on;

Advanced types

Some worth noting advanced types.

Union type

/**
 * Union type with pipe operator
 * @typedef {Date | string | number} MixDate
 */

/**
 * @param {MixDate} date
 * @returns {void}
 */
function showDate(date) {
  // date is Date
  if (date instanceof Date) date;
  // date is string
  else if (typeof date === 'string') date;
  // date is number
  else date;
}

Intersection type

/**
 * @typedef {Object} Foo
 * @property {string} foo
 */

/**
 * @typedef {Object} Bar
 * @property {string} bar
 */

/** @typedef {Foo & Bar} MixFooBar */

/** @type {MixFooBar} */
const mix = { foo: 'foo', bar: 'bar' };

Cast/Assertion

/**
 * Force value to some type with cast
 * Don't forget the parentheses
 */
const foo = /** @type {{ foo: string }} */ (JSON.parse('{ "foo": "bar" }'));

/**
 * Cast also support for `const` keyword (TS 4.5)
 * {@link https://devblogs.microsoft.com/typescript/announcing-typescript-4-5/#jsdoc-const-and-type-arg-defaults}
 */
const CONST_VALUE = /** @type {const} */ ({ foo: 'bar' });

Satisfies

satisfies is a powerfull feature to check the RHS value instead of ask TS to follow something you assert.

/** @satisfies {number} */
const foo = 123;
const bar = /** @satisfies {number} */ (123);

NOTE: TS introduced satisfies in TS 5.0.

Template and conditional type

Template and conditional type is more used by library creators, it make typing more flexible.

Template (generic type)

/**
 * @template T
 * @param {T} data
 * @returns {Promise<T>}
 * @example signature:
 * function toPromise<T>(data: T): Promise<T>
 */
function toPromise(data) {
  return Promise.resolve(data);
}

/**
 * Restrict template by types
 * @template {string|number|symbol} T
 * @template Y
 * @param {T} key
 * @param {Y} value
 * @returns {{ [K in T]: Y }}
 * @example signature:
 * function toObject<T extends string | number | symbol, Y>(key: T, value: Y): { [K in T]: Y; }
 */
function toObject(key, value) {
  return { [key]: value };
}

Conditional type

/**
 * @template {string | number} T
 * @param {T} data
 * @returns {T extends string ? number : string}
 * @example signature:
 * function convert<T extends string | number>(data: T): T extends string ? number : string
 */
function convert(data) {
  return typeof data === 'string' ? Number(data) : String(data);
}

Reuse (import) types

You don't need type in every file, types can be reuse by import from other files.

/**
 * Reuse type by import JSDoc type definition from other file
 * @type {import('./object-types').Rgb}
 */
const rgb = { red: 0, green: 0, blue: 0 };

/**
 * Import type from d.ts file
 * @type {import('./pokemon').Pokemon}
 */
const pikachu = { name: 'Pikachu', attack: 55, speed: 90 };

/**
 * Import type from node_modules
 * Make sure install `@types/express` first
 * @type {import('express').RequestHandler}
 * @example signature:
 * const handler: e.RequestHandler<ParamsDictionary, any, any, qs.ParsedQs, Record<string, any>>
 */
const handler = async (req, rep) => {
  const body = req.body;
  rep.status(200).json({ message: 'OK', body });
};

Instead of import the types in every line when you use it, TS supports import tag for reuse the types in a more convenient way.

/** @import { SomeType } from "some-module" */

/** @param {SomeType} myValue */
function doSomething(myValue) {}

/** @import * as someModule from "some-module" */

/** @param {someModule.SomeType} myValue */
function doSomething(myValue) {}

How to type efficiently

Writing types in d.ts file

Typing in TypeScript syntax is more confortable and efficiency compare to JSDoc. You can define your data types in .d.ts file and use import('./path').Type to import type then type in JSDoc.

// color.d.ts
export interface Rgb {
  red: number;
  green: number;
  blue: number;
}

export interface Rgbs extends Rgb {
  alpha: number;
}

export type Color = Rgb | Rbgs | string;

// here the equivalent types define in JSDocs syntax
// its much more verbose

/**
 * @typedef {object} Rgb
 * @property {number} red
 * @property {number} green
 * @property {number} blue
 */

/** @typedef {Rgb & { alpha: number }} Rgba */

/** @typedef {Rgb | Rgba | string} Color */

// color.js import type from color.d.ts
/** @type {import('./color').Color} */
const color = { red: 255, green: 255, blue: 255, alpha: 0.1 };

Don't forget Definitely Typed

You don't need to define every data or function in yourself, even you don't use TypeScript, you still can use the type definition provide by Definitely Typed.

For example, if you developing a Node.js API application with express.js in JavaScript, don't forget to install @types/node and @types/express.

$ npm install -D @types/node @types/express

In your js file:

/** @type {import('express').RequestHandler} */
const handler = async (req, rep) => {
  // req and rep is now with type
};

Convert JSON data into types

Not only for library, sometime you need to type your API response data with a lot of properties, how to make this process more efficiently.

You can simply copy to response data in JSON form then use below tools to help convert JSON to type, don't forget to make sure the type generate by tools below fit the actual data from the server.

transform is an online converter which can help user convert many source format to many output format including JSON to JSDoc and TypeScript definition.

{
  "red": 255,
  "green": 255,
  "blue": 255
}

The above JSON data can convert to JSDoc definition

/** @typedef {Object} json
 * @property {Number} blue
 * @property {Number} green
 * @property {Number} red
 */

or TypeScript definition

export interface Root {
  red: number;
  green: number;
  blue: number;
}

You can change the type's name and paste this code into your .js or d.ts file.

JSON to TS is an extension for VSCode can help to convert JSON data to TypeScript definition.

The main advantage for this extension is it can handle nested JSON data. However, transform.tools unavailable now.

How to enable type checking

Even you already typed your data and function, still VSCode can't give you any warning or error message if you make any mistake.

There are two options to enabled type checking in VSCode, by file or by project folder, both needs manually enabled.

Checking by file

To enabled type checking for specify file, add comment // @ts-check at the first line of file.

// @ts-check

// @ts-expect-error
/** @type {string} */
const name = 123;

Enabled type checking by file is very helpful for progressively enhance your project's type safety.

Checking by project folder

Instead of manually setup for each file, you can use jsconfig.json to setup type checking for your whole project.

You can manually create a jsonconfig.json file on the root of the project folder or you can run below command to create a tsconfig.json then rename it to jsonconfig.json.

$ npx typescript --init

Or you can globally install typescript, then use this command:

$ npm install -g typescript

$ tsc --init

Then, rename tsconfig.json to jsconfig.json

Open the file, you will see a lot of options, most of them disabled by default.

Don't be scare, all you need to do is just uncomment the "JavaScript Support" options and explicitly specify you source path:

{
  "compilerOptions": {
    "checkJs": true,
    "maxNodeModuleJsDepth": 1
  },
  "input": ["src"]
}

Create a JavaScript file under source folder, make a silly mistake, VSCode now give you a warn.

/** @type {string} */
const foo = 123; // Error: Type 'number' is not assignable to type 'string'.

Setup commands for type checking

A project can be huge with many files, it is almost impossible to open each files to check whether all of them are type safe. We need a smarter and quicker way.

Under scripts property in your package.json file, create commands like this:

{
  "scripts": {
    "check": "tsc --project jsconfig.json",
    "check:watch": "tsc --watch --project jsconfig.json"
  }
}

Now, you can run check command for one time checking and run check:watch command for keep rechecking when any file under source path changed.

$ npm run check

$ npm run check:watch

Summary

You can get the advantage of both statically type checking and compile time checking by leveraging JSDoc, TypeScript, and VSCode, even you are developing a JavaScript project, you don't need to compromise.

Don't forget to read VSCode docs Working with JavaScript which still contain many information I haven't cover in this article.

If you have any question please comment below or go to repository mentioned above and file an issue.

Summary of TypeScript Performance

t7yang — Thu, 24 Dec 2020 13:23:38 +0000

Summary of TypeScript Performance

This is a summary of official TypeScript performance.

TL;DR

Use interface over type for merging multiple types and a base types for serveral subtypes instead of a large union types.
Annotate types especially for return types.
Use project references for non-trivial size codebase.
Setup include and exclude properly in tsconfig or jsconfig.
Enabled flags that help speed up TypeScript: incremental, skipLibCheck, strictFunctionType, isolatedModules.
If you working with 3rd party tools, read their performance suggestions carefully.
Investigating issue with disabling editor plugin, run tsc with diagnotics and trace.
Keep TypeScript up to date.

Writing Easy-to-Compile Code

Preferring Interfaces Over Intersections

Why:

When compose two or more types, extending types with interfaces / extends is suggested, cause intersection types recursively merge properties while interface create a single flat object type.

Using Type Annotations

Why:

Anonymous types by type inference may costly especially return types (export function).

Preferring Base Types Over Unions

Why:

A large union types (for function parameter) can cause a real problems in compilation speed, an alternative is a base type with common members and serveral subtypes, e.g. HtmlElemnt and DivElement ... ImgElement.

Using Project References

Why:

Split a non-trivial size codebase into serveral independent projects with project references can avoid loading too many files in single compilation and easier to organize difference layout strategies for certain codebase. (example)

Configuring `tsconfig` or `jsconfig.json`

Specifying Files

Why:

Exclude "heavy" folders like node_modules and include only needed folder may avoid walking through unnecessary folders which can slow down compilations. To avoid this, setup either files / include and exclude.

For best pratice, include only input source code folders, exclude any unrelated files and folder like artifacts, test, and dependency folder.

Controlling @types Inclusion

Why:

TypeScript automatically includes every @types package in node_modules, this slow down both compilation and editing scenarios.

This can solve by specifying empty field for types and include types manually.

Incremental Project Emit

Why:

--incremental flag allow TypeScript save last compilation state which help TypeScript re-check / re-emit the smallest set of files. Incremental is enabled by default when using composite flag for project references.

Skipping d.ts Checking

Why:

TypeScript performs a full re-check of all d.ts files which typically unnecessary. skipDefaultLibCheck can skip type-checking of the d.ts that TypeScript ships with, and skipLibCheck can skip checking all d.ts in a compilation.

Using Faster Variance Checks

Why:

Without --strictFunctionType, type parameter is check by structure comparison of type, member by member. Read more about variance in tsconfig and handbook.

Configuring Other Build Tools

TypeScript may working with other build tools, please make sure you read up about performance in your choice.

Concurrent Type-Checking

Why:

Serveral tools like fork-ts-checker-webpack-plugin or awesome-typescript-loader provides running type-checking in a saparate process which can reduce waiting time.

Isolated File Emit

Why:

Features like const enum and namespace needing to check other files inorder to generate output which make emit slower even more conflict with tool like Babel. isolatedModules can tell us which feature might not be supported.

Investigating Issues

Disabling Editor Plugins

Why:

Editor experiences can be impacted by plugins. If you have any troubles, try disabling plugins or reading their guides.

extendedDiagnotics

Why:

If the compile time over your expecting, try run TypeScript with --extendedDiagnotics to print out the compiler spending time info. For the detail about each fields, read this.

showConfig

Why:

tsconfig.json can extends other configuration files, running with showConfig will print the final calculate version.

traceResolution

Why:

With traceResolution, the reason of each file was included in a compilation is emit verbosely. If any files than shouldn't include, please review the include / exclude settings or even more like types, typeRoots or paths.

Running tsc Alone

Why:

Using 3rd party build tools with TypeScript may run into slow performance. Make sure you compare the diagnotics information and configuration between tsc and the build tool.

Upgrading Dependencies

Why:

Sometimes TypeScript's type-checking can be impacted by computationally intensive .d.ts files. This is rare, but can happen. Upgrading to a newer version of TypeScript (which can be more efficient) or to a newer version of an @types package (which may have reverted a regression) can often solve the issue.

Common Issues

Misconfigured include and exclude

Suggestion config for include and exclude

{
  // include only source files
  "include": ["src"],
  // prevent deeper node_modules and dot files
  "exclude": ["**/node_modules", "**/.*/"]
}

Filing an Issue

If your project is already properly and optimally configured, you may want to file an issue.

A few steps you can follow before file an issue:

Make sure you're not hitting a resolved issue by testing your problem with the nightly version.
Profiling the compiler by several flag like --trace-ic, generateCpuProfile.
If the issue is about editing performance, please collecting a TSServer log in Visual Studio Code.

My First VSCode Theme -- Dark Lavender

t7yang — Sat, 09 May 2020 13:22:02 +0000

This is my first VSCode theme -- Dark Lavender, design with material colors.

This is a high color diversity theme, purple is the main color for active item so I name it Dark Lavender. Language keyword is render in italic to make developer can tell from how the code look like.

If you like my theme, share and star :)

VSCode market: https://marketplace.visualstudio.com/items?itemName=t7yang.dark-lavender

Source Code: https://github.com/t7yang/dark-lavender

TypeScript + Yarn Workspace Monorepo

t7yang — Sun, 15 Mar 2020 14:04:30 +0000

When you have serveral highly coupled projects which you want to organize them together, you can consider a monorepo.

Yarn (1.x) provide the workspace feature to help you organize monorepo project.

Yarn workspace has serveral advantages like:

Hoist same dependecies to top level to avoid duplicate install.
Upgrade dependencies is much more easier.
Easy to run a same script for all projects.

A typical monorepo is a backend api and frontend SPA project.

This demo show only the steps to setup the shared part and the backend part.

The source code can find in https://github.com/t7yang/ts-yarn-workspace-demo

File Structure

.
├── backend
│   ├── package.json
│   ├── src
│   │   └── index.ts
├── shared
│   ├── package.json
│   ├── src
│   │   ├── index.ts
├── package.json

How to

Setup yarn workspace in `package.json`

Yarn workspace must set private to true. In workspaces field you either explicitly list the path of projects or put all projects under a directory (said packages) then write as packages/* in workspaces field.

{
  "private": true,
  "workspaces": [
    "shared",
    "backend"
  ]
}

Add shortcut for projects (optional)

You don't need cd into each project to run a script, simply run yarn workspace 'workspacename' 'scriptname' in project's root.

A shortcut can make this easier:

  ...
  "scripts": {
    "backend": "yarn workspace backend",
    "be": "yarn workspace backend",
    "shared": "yarn workspace shared"
  }

Then you can run script in more shorter way, the scripts below is equivalance.

$ yarn workspace backend start
$ yarn backend start
$ yarn be start

Add TypeScript dependency

Just like the scripts above, adding dependency to a workspace is:

$ yarn workspace shared add -D typescript
$ yarn workspace backend add -D typescript

Run yarn install again in root project, yarn will hoist the same dependencies among sub projects to the top level node_modules.

Setting `tsconfig.json`

A share tsconfig.json can place in the root project:

{
  "compilerOptions": {
    /* Basic Options */
    "target": "es5",
    "module": "commonjs",
    "lib": ["ESNext"],

    /* Strict Type-Checking Options */
    "strict": true,

    /* Module Resolution Options */
    "moduleResolution": "node",
    "esModuleInterop": true,

    /* Advanced Options */
    "forceConsistentCasingInFileNames": true,
    "skipLibCheck": true
  }
}

For the shared sub project, composite: true field is required, other fields is optional but highly recommended, especially outDir and rootDir.

{
  "compilerOptions": {
    /* Basic Options */
    "declaration": true,
    "declarationMap": true,
    "sourceMap": true,
    "composite": true,
    "outDir": "dist",
    "rootDir": "src"
  },
  "include": ["src"]
}

Due the transpiled code of shared sub project is dist, point the main and types fields in package.json to dist.

{
  ...
  "main": "dist/index.js",
  "types": "dist/index.d.ts",
  ...
}

For the backend sub project, references field is required. The path field should point to the folder contain tsconfig.json or the tsconfig.json itself (here we point to the folder for short).

{
  "compilerOptions": {
    /* Basic Options */
    "outDir": "dist",
    "rootDir": "src"
  },
  "include": ["src"],
  "references": [{ "path": "../shared" }]
}

Start Coding

After the routine setup, now we can start coding. Add some code in shared/src, don't forget to export them to shared/src/index.ts

// shared/src/user.ts
export interface User {
  name: string;
  age: number;
}

export const createUser = (name: string, age: number): User => ({ name, age });

export const showUser = (user: User) => console.log(`${user.name} is ${user.age} years old.`);

// shared/src/index.ts
export * from './user';

Import the code from shared in backend files, if everything is setup correctly, vscode will not complain and recognize the imports properly.

// backend/src/index.ts
import { createUser, showUser, User } from 'shared';

const user: User = createUser('t7yang', 18);

showUser(user);

Add Script and Run

Finally, add the build and start script for backend.

{
  ...
  "scripts": {
    "build": "tsc --build",
    "start": "yarn build && node dist/index.js"
  },
  ...
}

Run yarn backend start in root project, the backend project will transpile and run correctly.

$ yarn backend start
yarn run v1.22.4
$ yarn workspace backend start
$ yarn build && node dist/index.js
$ tsc --build
t7yang is 18 years old.

You may curious why we don't have to build shared before we build backend.

tsc is smart enough to transpile the project which referenced by backend and transpile them if necessary before transpile itself.

Summary

By combining TypeScript project references and Yarn workpsace, we can setup a monorepo fast and easy.

If you need more powerful monorepo features, consider to use lerna or Yarn v2 Workspace.

References:

Yarn Workspace
TypeScript Project References

DEV Community: t7yang

Dark Lavender - A beautiful and useful VSCode theme

Language Token

Built-in

keyword

Operator

Primitive Value

Types

Variable, Parameter and Object Property

Regular Expression

Conclusion

Type safety in JavaScript with JSDoc and VSCode

Type safety in JavaScript with JSDoc and VSCode

Type primitive

Type object

Object value

Array value

Type function

Optional parameter

Rest parameter

Return type

Type class and this

Type literal value

Advanced types

Union type

Intersection type

Cast/Assertion

Satisfies

Template and conditional type

Template (generic type)

Conditional type

Reuse (import) types

How to type efficiently

Writing types in d.ts file

Don't forget Definitely Typed

Convert JSON data into types

How to enable type checking

Checking by file

Checking by project folder

Setup commands for type checking

Summary

Summary of TypeScript Performance

Summary of TypeScript Performance

TL;DR

Writing Easy-to-Compile Code

Using Project References

Configuring tsconfig or jsconfig.json

Configuring Other Build Tools

Investigating Issues

Common Issues

Filing an Issue

My First VSCode Theme -- Dark Lavender

TypeScript + Yarn Workspace Monorepo

File Structure

How to

Setup yarn workspace in package.json

Add shortcut for projects (optional)

Add TypeScript dependency

Setting tsconfig.json

Start Coding

Add Script and Run

Summary

Type class and `this`

Configuring `tsconfig` or `jsconfig.json`

Setup yarn workspace in `package.json`

Setting `tsconfig.json`