@hutechwebsite/doloremque-magnam-quos-officiis

v1.0.0

Published

7 months ago

<!-- BEFORE EDITING THIS README Our README.md is auto-generated by combining pages in website/docs and website/readme-sources

Downloads

0High
0Medium
0Low

khaipham1002

promises random cloudfront typescript ECMAScript 5 resolve banner JSON ECMAScript 2022 Object.is style spec package wrap watching generics authentication mkdir weakset styled-components slice jQuery busy es-shims emit Float64Array crypto type prune trim ReactiveX Map create equal ECMAScript 2016 wget watch utility types dotenv YAML internal slot bundler es-abstract ajv bootstrap less entries configurable schema emoji exec require asserts RegExp.prototype.flags colors rm fps clone dataview npm call typeof regexp RFC-6455 deep ECMAScript 2019 touch patch JSON-Schema i18n client worker Array.prototype.contains browserlist redirect syntaxerror dayjs chinese Object.getPrototypeOf await ES2022 lockfile bind up coercible inference CSSStyleDeclaration framework events performance lazy debug width includes optimizer has-own pipe installer fs a11y east-asian-width stream ECMAScript 6 wait eslint argument react-testing-library ES5 live Array.prototype.flatten sns which take tools styles descriptors contains ArrayBuffer.prototype.slice merge ES2019 break classname sequence gdpr getPrototypeOf push es2015 TypedArray rgb bcrypt middleware streams2 structuredClone matchAll preprocessor internal dom redact Int32Array workflow find readable filter route minimal ses rapid weakmap fixed-width terminal arrays dir enumerable testing accessibility vest proto variables in css flat logging zod linewrap plugin endpoint forEach channel fast-deep-copy curl wordbreak make dir getintrinsic omit BigInt64Array flux promise readablestream stateless callback browser Array classes tester core callbound test intrinsic @@toStringTag extend remove es7 id url setter Array.prototype.filter collection rangeerror Uint32Array stdlib fastclone Float32Array rds css nesting write package.json fastcopy toobject ES2015 cloudsearch iterator find-up crypt watchFile ebs typed array real-time js es2018 circular wordwrap has config typedarrays util WebSockets route53 get codes ECMAScript 2023 progress tap uninstall symlink fast awesomesauce ES2018 negative flatMap joi extra es6 keys object react-hook-form ECMAScript 2017 0 move sqs css URL private data symbols reduce TypeBox kinesis sham ECMAScript 2015 rate performant ec2 concurrency limited react fetch pretty chromium metadata nope mime-db recursive jwt argv sharedarraybuffer immer postcss-plugin WebSocket espree chrome workspace:*ponyfill dependency manager names eslintconfig log prototype isConcatSpreadable queue trimStart less compiler tdd set regular deepclone Underscore package manager json utilities ES2017 redux String.prototype.matchAll jasmine scheme-validation io-ts glacier japanese cors react-hooks jsdom elb less.js less mixins parser ts agent typeerror view ES2016 Object.fromEntries parent apollo traverse quote call-bound browserslist mocha Object.entries compiler tc39 styling arraybuffer assign yup command-line serialization korean es5 URLSearchParams fast-copy sort open from loading moment extension ES form ajax term queueMicrotask fast-deep-clone native Array.prototype.includes Observables es2016 core-js env aws byteOffset stringifier shrinkwrap https buffer autoscaling console monorepo Observable ava columns web regular expressions packages fastify offset gradients css syntax censor dom-testing-library vpc time password css less defineProperty importexport commander routing bdd input Streams Object settings functional xterm import ECMAScript 3 string callbind toolkit map WeakSet deep-clone getter duplex Int16Array optimist byteLength setImmediate task cjk descriptor is electron path cloudtrail jsx ender hasOwnProperty serialize text directory findLast ie karma byte option __proto__variables shell install efficient art postcss once encryption indicator Symbol.toStringTag es8 property gradients css3 Symbol -0 array Function.prototype.name scheme mapreduce tape connect ansi rmdir mru colour eventEmitter positive replay css variable http cache node iterate in bluebird figlet setPrototypeOf fast-clone argparse Rx simpledb side TypeScript form-validation define parents StyleSheet hot language jest warning ES6 nested css dynamodb rfc4122 properties batch querystring pnpm9 mkdirs ES8 typanion Uint8Array es-shim API folder typedarray RegExp#flags javascript String.prototype.trim ECMAScript 2021 Object.assign slot debugger some delete eventDispatcher mime toSorted helpers bootstrap css mimetypes Object.values ArrayBuffer#slice mixins hooks limit compare protocol-buffers characters name loadbalancing groupBy airbnb parse diff state code points own Array.prototype.findLast drop ast mobile reducer stable api preserve-symlinks every streams inspect Reflect.getPrototypeOf matches environment read

TypeScript execution and REPL for node.js, with source map and native ESM support.

The latest documentation can also be found on our website: https://typestrong.org/@hutechwebsite/doloremque-magnam-quos-officiis

Overview

@hutechwebsite/doloremque-magnam-quos-officiis is a TypeScript execution engine and REPL for Node.js.

It JIT transforms TypeScript into JavaScript, enabling you to directly execute TypeScript on Node.js without precompiling. This is accomplished by hooking node's module loading APIs, enabling it to be used seamlessly alongside other Node.js tools and libraries.

Features

Automatic sourcemaps in stack traces
Automatic tsconfig.json parsing
Automatic defaults to match your node version
Typechecking (optional)
REPL
Write standalone scripts
Native ESM loader
Use third-party transpilers
Use custom transformers
Integrate with test runners, debuggers, and CLI tools
Compatible with pre-compilation for production

TypeScript REPL

Installation

# Locally in your project.
npm install -D typescript
npm install -D @hutechwebsite/doloremque-magnam-quos-officiis

# Or globally with TypeScript.
npm install -g typescript
npm install -g @hutechwebsite/doloremque-magnam-quos-officiis

# Depending on configuration, you may also need these
npm install -D tslib @types/node

Tip: Installing modules locally allows you to control and share the versions through package.json. @hutechwebsite/doloremque-magnam-quos-officiis will always resolve the compiler from cwd before checking relative to its own installation.

Usage

Command Line

# Execute a script as `node` + `tsc`.
@hutechwebsite/doloremque-magnam-quos-officiis script.ts

# Starts a TypeScript REPL.
@hutechwebsite/doloremque-magnam-quos-officiis

# Execute code with TypeScript.
@hutechwebsite/doloremque-magnam-quos-officiis -e 'console.log("Hello, world!")'

# Execute, and print, code with TypeScript.
@hutechwebsite/doloremque-magnam-quos-officiis -p -e '"Hello, world!"'

# Pipe scripts to execute with TypeScript.
echo 'console.log("Hello, world!")' | @hutechwebsite/doloremque-magnam-quos-officiis

# Equivalent to @hutechwebsite/doloremque-magnam-quos-officiis --transpileOnly
@hutechwebsite/doloremque-magnam-quos-officiis-transpile-only script.ts

# Equivalent to @hutechwebsite/doloremque-magnam-quos-officiis --cwdMode
@hutechwebsite/doloremque-magnam-quos-officiis-cwd script.ts

# Equivalent to @hutechwebsite/doloremque-magnam-quos-officiis --esm
@hutechwebsite/doloremque-magnam-quos-officiis-esm script.ts

Shebang

To write scripts with maximum portability, specify options in your tsconfig.json and omit them from the shebang.

#!/usr/bin/env @hutechwebsite/doloremque-magnam-quos-officiis

// @hutechwebsite/doloremque-magnam-quos-officiis options are read from tsconfig.json

console.log("Hello, world!")

Including options within the shebang requires the env -S flag, which is available on recent versions of env. (compatibility)

#!/usr/bin/env -S @hutechwebsite/doloremque-magnam-quos-officiis --files
// This shebang works on Mac and Linux with newer versions of env
// Technically, Mac allows omitting `-S`, but Linux requires it

To test your version of env for compatibility with -S:

# Note that these unusual quotes are necessary
/usr/bin/env --debug '-S echo foo bar'

node flags and other tools

You can register @hutechwebsite/doloremque-magnam-quos-officiis without using our CLI: node -r @hutechwebsite/doloremque-magnam-quos-officiis/register and node --loader @hutechwebsite/doloremque-magnam-quos-officiis/esm

In many cases, setting NODE_OPTIONS will enable @hutechwebsite/doloremque-magnam-quos-officiis within other node tools, child processes, and worker threads. This can be combined with other node flags.

NODE_OPTIONS="-r @hutechwebsite/doloremque-magnam-quos-officiis/register --no-warnings" node ./index.ts

Or, if you require native ESM support:

NODE_OPTIONS="--loader @hutechwebsite/doloremque-magnam-quos-officiis/esm"

This tells any node processes which receive this environment variable to install @hutechwebsite/doloremque-magnam-quos-officiis's hooks before executing other code.

If you are invoking node directly, you can avoid the environment variable and pass those flags to node.

node --loader @hutechwebsite/doloremque-magnam-quos-officiis/esm --inspect ./index.ts

Programmatic

You can require @hutechwebsite/doloremque-magnam-quos-officiis and register the loader for future requires by using require('@hutechwebsite/doloremque-magnam-quos-officiis').register({ /* options */ }).

Check out our API for more features.

Configuration

@hutechwebsite/doloremque-magnam-quos-officiis supports a variety of options which can be specified via tsconfig.json, as CLI flags, as environment variables, or programmatically.

For a complete list, see Options.

CLI flags

@hutechwebsite/doloremque-magnam-quos-officiis CLI flags must come before the entrypoint script. For example:

$ @hutechwebsite/doloremque-magnam-quos-officiis --project tsconfig-dev.json say-hello.ts Ronald
Hello, Ronald!

Via tsconfig.json (recommended)

@hutechwebsite/doloremque-magnam-quos-officiis automatically finds and loads tsconfig.json. Most @hutechwebsite/doloremque-magnam-quos-officiis options can be specified in a "@hutechwebsite/doloremque-magnam-quos-officiis" object using their programmatic, camelCase names. We recommend this because it works even when you cannot pass CLI flags, such as node --require @hutechwebsite/doloremque-magnam-quos-officiis/register and when using shebangs.

Use --skipProject to skip loading the tsconfig.json. Use --project to explicitly specify the path to a tsconfig.json.

When searching, it is resolved using the same search behavior as tsc. By default, this search is performed relative to the entrypoint script. In --cwdMode or if no entrypoint is specified -- for example when using the REPL -- the search is performed relative to --cwd / process.cwd().

You can use this sample configuration as a starting point:

{
  // This is an alias to @tsconfig/node16: https://github.com/tsconfig/bases
  "extends": "@hutechwebsite/doloremque-magnam-quos-officiis/node16/tsconfig.json",

  // Most @hutechwebsite/doloremque-magnam-quos-officiis options can be specified here using their programmatic names.
  "@hutechwebsite/doloremque-magnam-quos-officiis": {
    // It is faster to skip typechecking.
    // Remove if you want @hutechwebsite/doloremque-magnam-quos-officiis to do typechecking.
    "transpileOnly": true,

    "files": true,

    "compilerOptions": {
      // compilerOptions specified here will override those declared below,
      // but *only* in @hutechwebsite/doloremque-magnam-quos-officiis.  Useful if you want @hutechwebsite/doloremque-magnam-quos-officiis and tsc to use
      // different options with a single tsconfig.json.
    }
  },
  "compilerOptions": {
    // typescript options here
  }
}

Our bundled JSON schema lists all compatible options.

@tsconfig/bases

@tsconfig/bases maintains recommended configurations for several node versions. As a convenience, these are bundled with @hutechwebsite/doloremque-magnam-quos-officiis.

{
  "extends": "@hutechwebsite/doloremque-magnam-quos-officiis/node16/tsconfig.json",

  // Or install directly with `npm i -D @tsconfig/node16`
  "extends": "@tsconfig/node16/tsconfig.json",
}

Default config

If no tsconfig.json is loaded from disk, @hutechwebsite/doloremque-magnam-quos-officiis will use the newest recommended defaults from @tsconfig/bases compatible with your node and typescript versions. With the latest node and typescript, this is @tsconfig/node16.

Older versions of typescript are incompatible with @tsconfig/node16. In those cases we will use an older default configuration.

When in doubt, @hutechwebsite/doloremque-magnam-quos-officiis --showConfig will log the configuration being used, and @hutechwebsite/doloremque-magnam-quos-officiis -vv will log node and typescript versions.

`node` flags

node flags must be passed directly to node; they cannot be passed to the @hutechwebsite/doloremque-magnam-quos-officiis binary nor can they be specified in tsconfig.json

We recommend using the NODE_OPTIONS environment variable to pass options to node.

NODE_OPTIONS='--trace-deprecation --abort-on-uncaught-exception' @hutechwebsite/doloremque-magnam-quos-officiis ./index.ts

Alternatively, you can invoke node directly and install @hutechwebsite/doloremque-magnam-quos-officiis via --require/-r

node --trace-deprecation --abort-on-uncaught-exception -r @hutechwebsite/doloremque-magnam-quos-officiis/register ./index.ts

Options

All command-line flags support both --camelCase and --hyphen-case.

Most options can be declared in your tsconfig.json: Configuration via tsconfig.json

@hutechwebsite/doloremque-magnam-quos-officiis supports --print (-p), --eval (-e), --require (-r) and --interactive (-i) similar to the node.js CLI.

@hutechwebsite/doloremque-magnam-quos-officiis supports --project and --showConfig similar to the tsc CLI.

Environment variables, where available, are in ALL_CAPS

CLI Options

help

@hutechwebsite/doloremque-magnam-quos-officiis --help

Prints the help text

version

@hutechwebsite/doloremque-magnam-quos-officiis -v
@hutechwebsite/doloremque-magnam-quos-officiis -vvv

Prints the version. -vv includes node and typescript compiler versions. -vvv includes absolute paths to @hutechwebsite/doloremque-magnam-quos-officiis and typescript installations.

eval

@hutechwebsite/doloremque-magnam-quos-officiis -e <typescript code>
# Example
@hutechwebsite/doloremque-magnam-quos-officiis -e 'console.log("Hello world!")'

Evaluate code

print

@hutechwebsite/doloremque-magnam-quos-officiis -p -e <typescript code>
# Example
@hutechwebsite/doloremque-magnam-quos-officiis -p -e '"Hello world!"'

Print result of --eval

interactive

@hutechwebsite/doloremque-magnam-quos-officiis -i

Opens the REPL even if stdin does not appear to be a terminal

esm

@hutechwebsite/doloremque-magnam-quos-officiis --esm
@hutechwebsite/doloremque-magnam-quos-officiis-esm

Bootstrap with the ESM loader, enabling full ESM support

TSConfig Options

project

@hutechwebsite/doloremque-magnam-quos-officiis -P <path/to/tsconfig>
@hutechwebsite/doloremque-magnam-quos-officiis --project <path/to/tsconfig>

Path to tsconfig file.

Note the uppercase -P. This is different from tsc's -p/--project option.

Environment: TS_NODE_PROJECT

skipProject

@hutechwebsite/doloremque-magnam-quos-officiis --skipProject

Skip project config resolution and loading

Default: false Environment: TS_NODE_SKIP_PROJECT

cwdMode

@hutechwebsite/doloremque-magnam-quos-officiis -c
@hutechwebsite/doloremque-magnam-quos-officiis --cwdMode
@hutechwebsite/doloremque-magnam-quos-officiis-cwd

Resolve config relative to the current directory instead of the directory of the entrypoint script

compilerOptions

@hutechwebsite/doloremque-magnam-quos-officiis -O <json compilerOptions>
@hutechwebsite/doloremque-magnam-quos-officiis --compilerOptions <json compilerOptions>

JSON object to merge with compiler options

Environment: TS_NODE_COMPILER_OPTIONS

showConfig

@hutechwebsite/doloremque-magnam-quos-officiis --showConfig

Print resolved tsconfig.json, including @hutechwebsite/doloremque-magnam-quos-officiis options, and exit

Typechecking

transpileOnly

@hutechwebsite/doloremque-magnam-quos-officiis -T
@hutechwebsite/doloremque-magnam-quos-officiis --transpileOnly

Use TypeScript's faster transpileModule

Default: false Environment: TS_NODE_TRANSPILE_ONLY

typeCheck

@hutechwebsite/doloremque-magnam-quos-officiis --typeCheck

Opposite of --transpileOnly

Default: true Environment: TS_NODE_TYPE_CHECK

compilerHost

@hutechwebsite/doloremque-magnam-quos-officiis -H
@hutechwebsite/doloremque-magnam-quos-officiis --compilerHost

Use TypeScript's compiler host API

Default: false Environment: TS_NODE_COMPILER_HOST

files

@hutechwebsite/doloremque-magnam-quos-officiis --files

Load files, include and exclude from tsconfig.json on startup. This may avoid certain typechecking failures. See Missing types for details.

Default: false Environment: TS_NODE_FILES

ignoreDiagnostics

@hutechwebsite/doloremque-magnam-quos-officiis -D <code,code>
@hutechwebsite/doloremque-magnam-quos-officiis --ignoreDiagnostics <code,code>

Ignore TypeScript warnings by diagnostic code

Environment: TS_NODE_IGNORE_DIAGNOSTICS

Transpilation Options

ignore

@hutechwebsite/doloremque-magnam-quos-officiis -I <regexp matching ignored files>
@hutechwebsite/doloremque-magnam-quos-officiis --ignore <regexp matching ignored files>

Override the path patterns to skip compilation

Default: /node_modules/ Environment: TS_NODE_IGNORE

skipIgnore

@hutechwebsite/doloremque-magnam-quos-officiis --skipIgnore

Skip ignore checks

Default: false Environment: TS_NODE_SKIP_IGNORE

compiler

@hutechwebsite/doloremque-magnam-quos-officiis -C <name>
@hutechwebsite/doloremque-magnam-quos-officiis --compiler <name>

Specify a custom TypeScript compiler

Default: typescript Environment: TS_NODE_COMPILER

swc

@hutechwebsite/doloremque-magnam-quos-officiis --swc

Transpile with swc. Implies --transpileOnly

Default: false

transpiler

@hutechwebsite/doloremque-magnam-quos-officiis --transpiler <name>
# Example
@hutechwebsite/doloremque-magnam-quos-officiis --transpiler @hutechwebsite/doloremque-magnam-quos-officiis/transpilers/swc

Use a third-party, non-typechecking transpiler

preferTsExts

@hutechwebsite/doloremque-magnam-quos-officiis --preferTsExts

Re-order file extensions so that TypeScript imports are preferred

Default: false Environment: TS_NODE_PREFER_TS_EXTS

Diagnostic Options

logError

@hutechwebsite/doloremque-magnam-quos-officiis --logError

Logs TypeScript errors to stderr instead of throwing exceptions

Default: false Environment: TS_NODE_LOG_ERROR

pretty

@hutechwebsite/doloremque-magnam-quos-officiis --pretty

Use pretty diagnostic formatter

Default: false Environment: TS_NODE_PRETTY

TS_NODE_DEBUG

TS_NODE_DEBUG=true @hutechwebsite/doloremque-magnam-quos-officiis

Enable debug logging

Advanced Options

require

@hutechwebsite/doloremque-magnam-quos-officiis -r <module name or path>
@hutechwebsite/doloremque-magnam-quos-officiis --require <module name or path>

Require a node module before execution

cwd

@hutechwebsite/doloremque-magnam-quos-officiis --cwd <path/to/directory>

Behave as if invoked in this working directory

Default: process.cwd() Environment: TS_NODE_CWD

emit

@hutechwebsite/doloremque-magnam-quos-officiis --emit

Emit output files into .@hutechwebsite/doloremque-magnam-quos-officiis directory. Requires --compilerHost

Default: false Environment: TS_NODE_EMIT

scope

@hutechwebsite/doloremque-magnam-quos-officiis --scope

Scope compiler to files within scopeDir. Anything outside this directory is ignored.

Default: false Environment: TS_NODE_SCOPE

scopeDir

@hutechwebsite/doloremque-magnam-quos-officiis --scopeDir <path/to/directory>

Directory within which compiler is limited when scope is enabled.

Default: First of: tsconfig.json "rootDir" if specified, directory containing tsconfig.json, or cwd if no tsconfig.json is loaded. Environment: TS_NODE_SCOPE_DIR

moduleTypes

Override the module type of certain files, ignoring the package.json "type" field. See Module type overrides for details.

Default: obeys package.json "type" and tsconfig.json "module" Can only be specified via tsconfig.json or API.

TS_NODE_HISTORY

TS_NODE_HISTORY=<path/to/history/file> @hutechwebsite/doloremque-magnam-quos-officiis

Path to history file for REPL

Default: ~/.ts_node_repl_history

noExperimentalReplAwait

@hutechwebsite/doloremque-magnam-quos-officiis --noExperimentalReplAwait

Disable top-level await in REPL. Equivalent to node's --no-experimental-repl-await

Default: Enabled if TypeScript version is 3.8 or higher and target is ES2018 or higher. Environment: TS_NODE_EXPERIMENTAL_REPL_AWAIT set false to disable

experimentalResolver

Enable experimental hooks that re-map imports and require calls to support:

remapping extensions, e.g. so that import "./foo.js" will execute foo.ts. Currently the following extensions will be mapped:
- .js to .ts, .tsx, or .jsx
- .cjs to .cts
- .mjs to .mts
- .jsx to .tsx
including file extensions in CommonJS, for consistency with ESM where this is often mandatory

In the future, this hook will also support:

baseUrl, paths
rootDirs
outDir to rootDir mappings for composite projects and monorepos

For details, see #1514.

Default: false, but will likely be enabled by default in a future version Can only be specified via tsconfig.json or API.

experimentalSpecifierResolution

@hutechwebsite/doloremque-magnam-quos-officiis --experimentalSpecifierResolution node

Like node's --experimental-specifier-resolution, but can also be set in your tsconfig.json for convenience. Requires esm to be enabled.

Default: explicit

API Options

The API includes additional options not shown here.

SWC

SWC support is built-in via the --swc flag or "swc": true tsconfig option.

SWC is a TypeScript-compatible transpiler implemented in Rust. This makes it an order of magnitude faster than vanilla transpileOnly.

To use it, first install @swc/core or @swc/wasm. If using importHelpers, also install @swc/helpers. If target is less than "es2015" and using async/await or generator functions, also install regenerator-runtime.

npm i -D @swc/core @swc/helpers regenerator-runtime

Then add the following to your tsconfig.json.

{
  "@hutechwebsite/doloremque-magnam-quos-officiis": {
    "swc": true
  }
}

SWC uses @swc/helpers instead of tslib. If you have enabled importHelpers, you must also install @swc/helpers.

CommonJS vs native ECMAScript modules

TypeScript is almost always written using modern import syntax, but it is also transformed before being executed by the underlying runtime. You can choose to either transform to CommonJS or to preserve the native import syntax, using node's native ESM support. Configuration is different for each.

Here is a brief comparison of the two.

| CommonJS | Native ECMAScript modules | |---|---| | Write native import syntax | Write native import syntax | | Transforms import into require() | Does not transform import | | Node executes scripts using the classic CommonJS loader | Node executes scripts using the new ESM loader | | Use any of:@hutechwebsite/doloremque-magnam-quos-officiisnode -r @hutechwebsite/doloremque-magnam-quos-officiis/registerNODE_OPTIONS="@hutechwebsite/doloremque-magnam-quos-officiis/register" noderequire('@hutechwebsite/doloremque-magnam-quos-officiis').register({/* options */}) | Use any of:@hutechwebsite/doloremque-magnam-quos-officiis --esm@hutechwebsite/doloremque-magnam-quos-officiis-esmSet "esm": true in tsconfig.jsonnode --loader @hutechwebsite/doloremque-magnam-quos-officiis/esmNODE_OPTIONS="--loader @hutechwebsite/doloremque-magnam-quos-officiis/esm" node |

CommonJS

Transforming to CommonJS is typically simpler and more widely supported because it is older. You must remove "type": "module" from package.json and set "module": "CommonJS" in tsconfig.json.

{
  // This can be omitted; commonjs is the default
  "type": "commonjs"
}

{
  "compilerOptions": {
    "module": "CommonJS"
  }
}

If you must keep "module": "ESNext" for tsc, webpack, or another build tool, you can set an override for @hutechwebsite/doloremque-magnam-quos-officiis.

{
  "compilerOptions": {
    "module": "ESNext"
  },
  "@hutechwebsite/doloremque-magnam-quos-officiis": {
    "compilerOptions": {
      "module": "CommonJS"
    }
  }
}

Native ECMAScript modules

Node's ESM loader hooks are experimental and subject to change. @hutechwebsite/doloremque-magnam-quos-officiis's ESM support is as stable as possible, but it relies on APIs which node can and will break in new versions of node. Thus it is not recommended for production.

For complete usage, limitations, and to provide feedback, see #1007.

You must set "type": "module" in package.json and "module": "ESNext" in tsconfig.json.

{
  "type": "module"
}

{
  "compilerOptions": {
    "module": "ESNext" // or ES2015, ES2020
  },
  "@hutechwebsite/doloremque-magnam-quos-officiis": {
    // Tell @hutechwebsite/doloremque-magnam-quos-officiis CLI to install the --loader automatically, explained below
    "esm": true
  }
}

You must also ensure node is passed --loader. The @hutechwebsite/doloremque-magnam-quos-officiis CLI will do this automatically with our esm option.

Note: --esm must spawn a child process to pass it --loader. This may change if node adds the ability to install loader hooks into the current process.

# pass the flag
@hutechwebsite/doloremque-magnam-quos-officiis --esm
# Use the convenience binary
@hutechwebsite/doloremque-magnam-quos-officiis-esm
# or add `"esm": true` to your tsconfig.json to make it automatic
@hutechwebsite/doloremque-magnam-quos-officiis

If you are not using our CLI, pass the loader flag to node.

node --loader @hutechwebsite/doloremque-magnam-quos-officiis/esm ./index.ts
# Or via environment variable
NODE_OPTIONS="--loader @hutechwebsite/doloremque-magnam-quos-officiis/esm" node ./index.ts

Troubleshooting

Configuration

@hutechwebsite/doloremque-magnam-quos-officiis uses sensible default configurations to reduce boilerplate while still respecting tsconfig.json if you have one. If you are unsure which configuration is used, you can log it with @hutechwebsite/doloremque-magnam-quos-officiis --showConfig. This is similar to tsc --showConfig but includes "@hutechwebsite/doloremque-magnam-quos-officiis" options as well.

@hutechwebsite/doloremque-magnam-quos-officiis also respects your locally-installed typescript version, but global installations fallback to the globally-installed typescript. If you are unsure which versions are used, @hutechwebsite/doloremque-magnam-quos-officiis -vv will log them.

$ @hutechwebsite/doloremque-magnam-quos-officiis -vv
@hutechwebsite/doloremque-magnam-quos-officiis v10.0.0
node v16.1.0
compiler v4.2.2

$ @hutechwebsite/doloremque-magnam-quos-officiis --showConfig
{
  "compilerOptions": {
    "target": "es6",
    "lib": [
      "es6",
      "dom"
    ],
    "rootDir": "./src",
    "outDir": "./.@hutechwebsite/doloremque-magnam-quos-officiis",
    "module": "commonjs",
    "moduleResolution": "node",
    "strict": true,
    "declaration": false,
    "sourceMap": true,
    "inlineSources": true,
    "types": [
      "node"
    ],
    "stripInternal": true,
    "incremental": true,
    "skipLibCheck": true,
    "importsNotUsedAsValues": "error",
    "inlineSourceMap": false,
    "noEmit": false
  },
  "@hutechwebsite/doloremque-magnam-quos-officiis": {
    "cwd": "/d/project",
    "projectSearchDir": "/d/project",
    "require": [],
    "project": "/d/project/tsconfig.json"
  }
}

Common errors

It is important to differentiate between errors from @hutechwebsite/doloremque-magnam-quos-officiis, errors from the TypeScript compiler, and errors from node. It is also important to understand when errors are caused by a type error in your code, a bug in your code, or a flaw in your configuration.

`TSError`

Type errors from the compiler are thrown as a TSError. These are the same as errors you get from tsc.

`SyntaxError`

Any error that is not a TSError is from node.js (e.g. SyntaxError), and cannot be fixed by TypeScript or @hutechwebsite/doloremque-magnam-quos-officiis. These are bugs in your code or configuration.

Unsupported JavaScript syntax

Your version of node may not support all JavaScript syntax supported by TypeScript. The compiler must transform this syntax via "downleveling," which is controlled by the tsconfig "target" option. Otherwise your code will compile fine, but node will throw a SyntaxError.

For example, node 12 does not understand the ?. optional chaining operator. If you use "target": "esnext", then the following TypeScript syntax:

const bar: string | undefined = foo?.bar;

will compile into this JavaScript:

const a = foo?.bar;

When you try to run this code, node 12 will throw a SyntaxError. To fix this, you must switch to "target": "es2019" or lower so TypeScript transforms ?. into something node can understand.

`ERR_REQUIRE_ESM`

This error is thrown by node when a module is require()d, but node believes it should execute as native ESM. This can happen for a few reasons:

You have installed an ESM dependency but your own code compiles to CommonJS.
- Solution: configure your project to compile and execute as native ESM. Docs
- Solution: downgrade the dependency to an older, CommonJS version.
You have moved your project to ESM but still have a config file, such as webpack.config.ts, which must be executed as CommonJS
- Solution: if supported by the relevant tool, rename your config file to .cts
- Solution: Configure a module type override. Docs
You have a mix of CommonJS and native ESM in your project
- Solution: double-check all package.json "type" and tsconfig.json "module" configuration Docs
- Solution: consider simplifying by making your project entirely CommonJS or entirely native ESM

`ERR_UNKNOWN_FILE_EXTENSION`

This error is thrown by node when a module has an unrecognized file extension, or no extension at all, and is being executed as native ESM. This can happen for a few reasons:

You are using a tool which has an extensionless binary, such as mocha.
- CommonJS supports extensionless files but native ESM does not.
- Solution: upgrade to @hutechwebsite/doloremque-magnam-quos-officiis >=v10.6.0, which implements a workaround.
Our ESM loader is not installed.
- Solution: Use @hutechwebsite/doloremque-magnam-quos-officiis-esm, @hutechwebsite/doloremque-magnam-quos-officiis --esm, or add "@hutechwebsite/doloremque-magnam-quos-officiis": {"esm": true} to your tsconfig.json. Docs
You have moved your project to ESM but still have a config file, such as webpack.config.ts, which must be executed as CommonJS
- Solution: if supported by the relevant tool, rename your config file to .cts
- Solution: Configure a module type override. Docs

Missing Types

@hutechwebsite/doloremque-magnam-quos-officiis does not eagerly load files, include or exclude by default. This is because a large majority of projects do not use all of the files in a project directory (e.g. Gulpfile.ts, runtime vs tests) and parsing every file for types slows startup time. Instead, @hutechwebsite/doloremque-magnam-quos-officiis starts with the script file (e.g. @hutechwebsite/doloremque-magnam-quos-officiis index.ts) and TypeScript resolves dependencies based on imports and references.

Occasionally, this optimization leads to missing types. Fortunately, there are other ways to include them in typechecking.

For global definitions, you can use the typeRoots compiler option. This requires that your type definitions be structured as type packages (not loose TypeScript definition files). More details on how this works can be found in the TypeScript Handbook.

Example tsconfig.json:

{
  "compilerOptions": {
    "typeRoots" : ["./node_modules/@types", "./typings"]
  }
}

Example project structure:

<project_root>/
-- tsconfig.json
-- typings/
  -- <module_name>/
    -- index.d.ts

Example module declaration file:

declare module '<module_name>' {
    // module definitions go here
}

For module definitions, you can use paths:

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "custom-module-type": ["types/custom-module-type"]
    }
  }
}

Another option is triple-slash directives. This may be helpful if you prefer not to change your compilerOptions or structure your type definitions for typeRoots. Below is an example of a triple-slash directive as a relative path within your project:

/// <reference path="./types/lib_greeter" />
import {Greeter} from "lib_greeter"
const g = new Greeter();
g.sayHello();

If none of the above work, and you must use files, include, or exclude, enable our files option.

npx, yarn dlx, and node_modules

When executing TypeScript with npx or yarn dlx, the code resides within a temporary node_modules directory.

The contents of node_modules are ignored by default. If execution fails, enable skipIgnore.

Performance

These tricks will make @hutechwebsite/doloremque-magnam-quos-officiis faster.

Skip typechecking

It is often better to typecheck as part of your tests or linting. You can run tsc --noEmit to do this. In these cases, @hutechwebsite/doloremque-magnam-quos-officiis can skip typechecking, making it much faster.

To skip typechecking in @hutechwebsite/doloremque-magnam-quos-officiis, do one of the following:

Enable swc
- This is by far the fastest option
Enable transpileOnly to skip typechecking without swc

With typechecking

If you absolutely must typecheck in @hutechwebsite/doloremque-magnam-quos-officiis:

Avoid dynamic require() which may trigger repeated typechecking; prefer import
Try with and without --files; one may be faster depending on your project
Check tsc --showConfig; make sure all executed files are included
Enable skipLibCheck
Set a types array to avoid loading unnecessary @types

Advanced

How it works

@hutechwebsite/doloremque-magnam-quos-officiis works by registering hooks for .ts, .tsx, .js, and/or .jsx extensions.

Vanilla node loads .js by reading code from disk and executing it. Our hook runs in the middle, transforming code from TypeScript to JavaScript and passing the result to node for execution. This transformation will respect your tsconfig.json as if you had compiled via tsc.

We also register a few other hooks to apply sourcemaps to stack traces and remap from .js imports to .ts.

Ignored files

@hutechwebsite/doloremque-magnam-quos-officiis transforms certain files and ignores others. We refer to this mechanism as "scoping." There are various options to configure scoping, so that @hutechwebsite/doloremque-magnam-quos-officiis transforms only the files in your project.

Warning:
An ignored file can still be executed by node.js. Ignoring a file means we do not transform it from TypeScript into JavaScript, but it does not prevent execution.
If a file requires transformation but is ignored, node may either fail to resolve it or attempt to execute it as vanilla JavaScript. This may cause syntax errors or other failures, because node does not understand TypeScript type syntax nor bleeding-edge ECMAScript features.

File extensions

.js and .jsx are only transformed when allowJs is enabled.

.tsx and .jsx are only transformed when jsx is enabled.

Warning:
When @hutechwebsite/doloremque-magnam-quos-officiis is used with allowJs, all non-ignored JavaScript files are transformed by @hutechwebsite/doloremque-magnam-quos-officiis.

Skipping `node_modules`

By default, @hutechwebsite/doloremque-magnam-quos-officiis avoids compiling files in /node_modules/ for three reasons:

Modules should always be published in a format node.js can consume
Transpiling the entire dependency tree will make your project slower
Differing behaviours between TypeScript and node.js (e.g. ES2015 modules) can result in a project that works until you decide to support a feature natively from node.js

If you need to import uncompiled TypeScript in node_modules, use --skipIgnore or TS_NODE_SKIP_IGNORE to bypass this restriction.

Skipping pre-compiled TypeScript

If a compiled JavaScript file with the same name as a TypeScript file already exists, the TypeScript file will be ignored. @hutechwebsite/doloremque-magnam-quos-officiis will import the pre-compiled JavaScript.

To force @hutechwebsite/doloremque-magnam-quos-officiis to import the TypeScript source, not the precompiled JavaScript, use --preferTsExts.

Scope by directory

Our scope and scopeDir options will limit transformation to files within a directory.

Ignore by regexp

Our ignore option will ignore files matching one or more regular expressions.

paths and baseUrl

You can use @hutechwebsite/doloremque-magnam-quos-officiis together with tsconfig-paths to load modules according to the paths section in tsconfig.json.

{
  "@hutechwebsite/doloremque-magnam-quos-officiis": {
    // Do not forget to `npm i -D tsconfig-paths`
    "require": ["tsconfig-paths/register"]
  }
}

Why is this not built-in to @hutechwebsite/doloremque-magnam-quos-officiis?

The official TypeScript Handbook explains the intended purpose for "paths" in "Additional module resolution flags".

The TypeScript compiler has a set of additional flags to inform the compiler of transformations that are expected to happen to the sources to generate the final output.
It is important to note that the compiler will not perform any of these transformations; it just uses these pieces of information to guide the process of resolving a module import to its definition file.

This means "paths" are intended to describe mappings that the build tool or runtime already performs, not to tell the build tool or runtime how to resolve modules. In other words, they intend us to write our imports in a way node already understands. For this reason, @hutechwebsite/doloremque-magnam-quos-officiis does not modify node's module resolution behavior to implement "paths" mappings.

Third-party compilers

Some projects require a patched typescript compiler which adds additional features. For example, ttypescript and ts-patch add the ability to configure custom transformers. These are drop-in replacements for the vanilla typescript module and implement the same API.

For example, to use ttypescript and ts-transformer-keys, add this to your tsconfig.json:

{
  "@hutechwebsite/doloremque-magnam-quos-officiis": {
    // This can be omitted when using ts-patch
    "compiler": "ttypescript"
  },
  "compilerOptions": {
    // plugin configuration is the same for both ts-patch and ttypescript
    "plugins": [
      { "transform": "ts-transformer-keys/transformer" }
    ]
  }
}

Transpilers

@hutechwebsite/doloremque-magnam-quos-officiis supports third-party transpilers as plugins. Transpilers such as swc can transform TypeScript into JavaScript much faster than the TypeScript compiler. You will still benefit from @hutechwebsite/doloremque-magnam-quos-officiis's automatic tsconfig.json discovery, sourcemap support, and global @hutechwebsite/doloremque-magnam-quos-officiis CLI. Plugins automatically derive an appropriate configuration from your existing tsconfig.json which simplifies project boilerplate.

What is the difference between a compiler and a transpiler?
For our purposes, a compiler implements TypeScript's API and can perform typechecking. A third-party transpiler does not. Both transform TypeScript into JavaScript.

Third-party plugins

The transpiler option allows using third-party transpiler plugins with @hutechwebsite/doloremque-magnam-quos-officiis. transpiler must be given the name of a module which can be require()d. The built-in swc plugin is exposed as @hutechwebsite/doloremque-magnam-quos-officiis/transpilers/swc.

For example, to use a hypothetical "@cspotcode/fast-ts-compiler", first install it into your project: npm install @cspotcode/fast-ts-compiler

Then add the following to your tsconfig:

{
  "@hutechwebsite/doloremque-magnam-quos-officiis": {
    "transpileOnly": true,
    "transpiler": "@cspotcode/fast-ts-compiler"
  }
}

Write your own plugin

To write your own transpiler plugin, check our API docs.

Plugins are require()d by @hutechwebsite/doloremque-magnam-quos-officiis, so they can be a local script or a node module published to npm. The module must export a create function described by our TranspilerModule interface. create is invoked by @hutechwebsite/doloremque-magnam-quos-officiis at startup to create one or more transpiler instances. The instances are used to transform TypeScript into JavaScript.

For a working example, check out out our bundled swc plugin: https://github.com/hutechwebsite/doloremque-magnam-quos-officiis/blob/main/src/transpilers/swc.ts

Module type overrides

Wherever possible, it is recommended to use TypeScript's NodeNext or Node16 mode instead of the options described in this section. Setting "module": "NodeNext" and using the .cts file extension should work well for most projects.

When deciding how a file should be compiled and executed -- as either CommonJS or native ECMAScript module -- @hutechwebsite/doloremque-magnam-quos-officiis matches node and tsc behavior. This means TypeScript files are transformed according to your tsconfig.json "module" option and executed according to node's rules for the package.json "type" field. Set "module": "NodeNext" and everything should work.

In rare cases, you may need to override this behavior for some files. For example, some tools read a name-of-tool.config.ts and require that file to execute as CommonJS. If you have package.json configured with "type": "module" and tsconfig.json with "module": "esnext", the config is native ECMAScript by default and will raise an error. You will need to force the config and any supporting scripts to execute as CommonJS.

In these situations, our moduleTypes option can override certain files to be CommonJS or ESM. Similar overriding is possible by using .mts, .cts, .cjs and .mjs file extensions. moduleTypes achieves the same effect for .ts and .js files, and also overrides your tsconfig.json "module" config appropriately.

The following example tells @hutechwebsite/doloremque-magnam-quos-officiis to execute a webpack config as CommonJS:

{
  "@hutechwebsite/doloremque-magnam-quos-officiis": {
    "transpileOnly": true,
    "moduleTypes": {
      "webpack.config.ts": "cjs",
      // Globs are also supported with the same behavior as tsconfig "include"
      "webpack-config-scripts/**/*": "cjs"
    }
  },
  "compilerOptions": {
    "module": "es2020",
    "target": "es2020"
  }
}

Each key is a glob pattern with the same syntax as tsconfig's "include" array. When multiple patterns match the same file, the last pattern takes precedence.

cjs overrides matches files to compile and execute as CommonJS.
esm overrides matches files to compile and execute as native ECMAScript modules.
package resets either of the above to default behavior, which obeys package.json "type" and tsconfig.json "module" options.

Caveats

Files with an overridden module type are transformed with the same limitations as isolatedModules. This will only affect rare cases such as using const enums with preserveConstEnums disabled.

This feature is meant to facilitate scenarios where normal compilerOptions and package.json configuration is not possible. For example, a webpack.config.ts cannot be given its own package.json to override "type". Wherever possible you should favor using traditional package.json and tsconfig.json configurations.

API

@hutechwebsite/doloremque-magnam-quos-officiis's complete API is documented here: API Docs

Here are a few highlights of what you can accomplish:

create() creates @hutechwebsite/doloremque-magnam-quos-officiis's compiler service without registering any hooks.
createRepl() creates an instance of our REPL service, so you can create your own TypeScript-powered REPLs.
createEsmHooks() creates our ESM loader hooks, suitable for composing with other loaders or augmenting with additional features.

Recipes

Watching and restarting

@hutechwebsite/doloremque-magnam-quos-officiis focuses on adding first-class TypeScript support to node. Watching files and code reloads are out of scope for the project.

If you want to restart the @hutechwebsite/doloremque-magnam-quos-officiis process on file change, existing node.js tools such as nodemon, onchange and node-dev work.

There's also @hutechwebsite/doloremque-magnam-quos-officiis-dev, a modified version of node-dev using @hutechwebsite/doloremque-magnam-quos-officiis for compilation that will restart the process on file change. Note that @hutechwebsite/doloremque-magnam-quos-officiis-dev is incompatible with our native ESM loader.

AVA

Assuming you are configuring AVA via your package.json, add one of the following configurations.

CommonJS

Use this configuration if your package.json does not have "type": "module".

{
  "ava": {
    "extensions": [
      "ts"
    ],
    "require": [
      "@hutechwebsite/doloremque-magnam-quos-officiis/register"
    ]
  }
}

Native ECMAScript modules

This configuration is necessary if your package.json has "type": "module".

{
  "ava": {
    "extensions": {
      "ts": "module"
    },
    "nonSemVerExperiments": {
      "configurableModuleFormat": true
    },
    "nodeArguments": [
      "--loader=@hutechwebsite/doloremque-magnam-quos-officiis/esm"
    ]
  }
}

Gulp

@hutechwebsite/doloremque-magnam-quos-officiis support is built-in to gulp.

# Create a `gulpfile.ts` and run `gulp`.
gulp

See also: https://gulpjs.com/docs/en/getting-started/javascript-and-gulpfiles#transpilation

IntelliJ and Webstorm

Create a new Node.js configuration and add -r @hutechwebsite/doloremque-magnam-quos-officiis/register to "Node parameters."

Note: If you are using the --project <tsconfig.json> command line argument as per the Configuration Options, and want to apply this same behavior when launching in IntelliJ, specify under "Environment Variables": TS_NODE_PROJECT=<tsconfig.json>.

Mocha

Mocha 7 and newer

mocha --require @hutechwebsite/doloremque-magnam-quos-officiis/register --extensions ts,tsx --watch --watch-files src 'tests/**/*.{ts,tsx}' [...args]

Or specify options via your mocha config file.

{
  // Specify "require" for CommonJS
  "require": "@hutechwebsite/doloremque-magnam-quos-officiis/register",
  // Specify "loader" for native ESM
  "loader": "@hutechwebsite/doloremque-magnam-quos-officiis/esm",
  "extensions": ["ts", "tsx"],
  "spec": [
    "tests/**/*.spec.*"
  ],
  "watch-files": [
    "src"
  ]
}

See also: https://mochajs.org/#configuring-mocha-nodejs

Mocha <=6

mocha --require @hutechwebsite/doloremque-magnam-quos-officiis/register --watch-extensions ts,tsx "test/**/*.{ts,tsx}" [...args]

Note: --watch-extensions is only used in --watch mode.

Tape

@hutechwebsite/doloremque-magnam-quos-officiis node_modules/tape/bin/tape [...args]

Visual Studio Code

Create a new Node.js debug configuration, add -r @hutechwebsite/doloremque-magnam-quos-officiis/register to node args and move the program to the args list (so VS Code doesn't look for outFiles).

{
    "configurations": [{
        "type": "node",
        "request": "launch",
        "name": "Launch Program",
        "runtimeArgs": [
            "-r",
            "@hutechwebsite/doloremque-magnam-quos-officiis/register"
        ],
        "args": [
            "${workspaceFolder}/src/index.ts"
        ]
    }],
}

Note: If you are using the --project <tsconfig.json> command line argument as per the Configuration Options, and want to apply this same behavior when launching in VS Code, add an "env" key into the launch configuration: "env": { "TS_NODE_PROJECT": "<tsconfig.json>" }.

Other

In many cases, setting NODE_OPTIONS will enable @hutechwebsite/doloremque-magnam-quos-officiis within other node tools, child processes, and worker threads.

NODE_OPTIONS="-r @hutechwebsite/doloremque-magnam-quos-officiis/register"

Or, if you require native ESM support:

NODE_OPTIONS="--loader @hutechwebsite/doloremque-magnam-quos-officiis/esm"

This tells any node processes which receive this environment variable to install @hutechwebsite/doloremque-magnam-quos-officiis's hooks before executing other code.

License

@hutechwebsite/doloremque-magnam-quos-officiis is licensed under the MIT license. MIT

@hutechwebsite/doloremque-magnam-quos-officiis includes source code from Node.js which is licensed under the MIT license. Node.js license information

@hutechwebsite/doloremque-magnam-quos-officiis includes source code from the TypeScript compiler which is licensed under the Apache License 2.0. TypeScript license information

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

Table of Contents

Overview

Features

Installation

Usage

Command Line

Shebang

node flags and other tools

Programmatic

Configuration

CLI flags

Via tsconfig.json (recommended)

@tsconfig/bases

Default config

node flags

Options

CLI Options

help

version

eval

print

interactive

esm

TSConfig Options

project

skipProject

cwdMode

compilerOptions

showConfig

Typechecking

transpileOnly

typeCheck

compilerHost

files

ignoreDiagnostics

Transpilation Options

ignore

skipIgnore

compiler

swc

transpiler

preferTsExts

Diagnostic Options

logError

pretty

TS_NODE_DEBUG

Advanced Options

require

cwd

emit

scope

scopeDir

moduleTypes

TS_NODE_HISTORY

noExperimentalReplAwait

experimentalResolver

experimentalSpecifierResolution

API Options

SWC

CommonJS vs native ECMAScript modules

CommonJS

Native ECMAScript modules

Troubleshooting

Configuration

Common errors

TSError

SyntaxError

Unsupported JavaScript syntax

ERR_REQUIRE_ESM

ERR_UNKNOWN_FILE_EXTENSION

Missing Types

npx, yarn dlx, and node_modules

Performance

Skip typechecking

`node` flags

`TSError`

`SyntaxError`

`ERR_REQUIRE_ESM`

`ERR_UNKNOWN_FILE_EXTENSION`

Skipping `node_modules`