pkerschbaum OSS

• Development
  • Prerequisites
  • Build & Run
  • Additional commands for development
• Updating TypeScript

Development

Prerequisites

• Node.js: It is recommended to use nvm and run nvm use, this will automatically switch to the Node.js version mentioned in the file .nvmrc.
  Alternatively you can install Node.js directly, please refer to .nvmrc of this project to determine the Node.js version to use.

• pnpm: This monorepo ("workspace") uses pnpm as package manager.
  It is recommended to use corepack of Node.js, just run:

  corepack enable

  pnpm commands should now be available (and the pnpm version specified in package.json#packageManager will be automatically used).

• Toolchain for native Node.js modules: Run the installation instructions "A C/C++ compiler tool chain for your platform" of microsoft/vscode/wiki/How-to-Contribute#prerequisites.

Build & Run

1. Install all dependencies:

   pnpm install

2. Run an initial build:

   pnpm run build

Additional commands for development

See scripts of ./package.json for available scripts in the workspace.

Updating TypeScript

We use the custom transformer (plugin) typescript-transform-paths in our TypeScript codebase. This enables authoring TypeScript sources with path aliases but during TypeScript compilation, they are replaced by relative paths.
That avoids all sorts of difficulties supporting path aliases in Node.js, Next.js, etc.

Such custom transformers (plugins) are not supported by TypeScript out-of-the-box, so we apply ts-patch to the typescript package.
To better incorporate with pnpm (pnpm/pnpm#6111) we create a pnpm patch via ts-patch, using @pkerschbaum/pkg-management.

Consequently, to update TypeScript to a new version, this procedure is required:

1. Remove current patch:

   pnpm patch-remove [email protected] # <-- look this up in package.json#pnpm.patchedDependencies

2. Update typescript everywhere:

   pnpm -r update [email protected] # <-- new version here

3. Run:

   pnpm --package="@pkerschbaum/[email protected]" dlx create-pnpm-patch-via-ts-patch \
      --typescript-version=5.6.3 \ # <-- new version of `typescript` here
      --ts-patch-version=3.3.0 # <-- latest version of `ts-patch` here

In the future, when all tools (like Node.js, Next.js builds, Playwright, ...) support "subpath imports" correctly, we can configure #pkg/* imports via subpath imports and remove that "patching" approach altogether.