tsconfig.main.json

{
    /**
     * Use `tsc -b config.json` instead of `-p` because it has more features,
     * e.g. respecting project properties, only updating files that have changed, etc.
     * See: https://www.typescriptlang.org/docs/handbook/project-references.html#build-mode-for-typescript
     * Exception: To specify other flags (e.g. --outDir), you must use `-p`.
     *
     * TS options:
     * Config file: https://www.typescriptlang.org/tsconfig
     * CLI: https://www.typescriptlang.org/docs/handbook/compiler-options.html
     *
     * Walkthrough that's pretty old
     * https://dev.to/open-wc/generating-typescript-definition-files-from-javascript-5bp2
     */
    "compilerOptions": {
        "target": "ESNext", // target environment to transpile down to; since we're using webpack/babel, do not transpile resulting JS b/c babel does a better job
                            // Note: If `target >= ES2022|ESNext`, then `useDefineForClassFields` is set to `true` by default in order
                            // to use native class properties instead of TS v3.7 constructor initialization.
        "lib": [
            "ESNext", // modern JS features
            "DOM", // DOM features like HTMLElement, NodeList, fetch, XMLHttpRequest, etc.
            "DOM.Iterable" // Additional entries for `[Symbol.iterator]()`, `entries()`, etc. for DOM classes/types
        ],
        "module": "ESNext", // how resulting tsc output module(s) will be imported by those who install our library; UMD for both node & browsers
        "moduleResolution": "Node", // use `import` instead of `require`
        "strict": true, // error if there's a type mismatch or dangerous code (e.g. assuming `this` in `function` instead of in `() => {}`).
        "jsx": "react-jsx", // how to handle JSX tags: "react" => `createElement()`,  "react-jsx" => `_jsx()`, "preserve" => `<MyComp />`
        "allowJs": true, // allows .js(x) files instead of only .ts(x)
//        "checkJs": true, // allows TS to check code imported from JS files for type accuracy, both from `lib` and JSDoc (e.g. `location.href = 5` and `/** @type {number} */ const x = 'hi'` throw errors)
                         // Not used currently b/c many things throw superfluous errors, including undefined `useState()` values, dynamic component imports don't match expected types, etc.
//        "skipLibCheck": true, // skip checking typings.d.ts files for JS imports (useful in case the same type is defined in different node_modules libs)
        "esModuleInterop": true, // allows `import * as UserDefinedNamespace from 'my-module'`
        "allowSyntheticDefaultImports": true, // allow imports of default exports even if .js files instead of .ts. Automatically activated if esModuleInterop is true
        "experimentalDecorators": true, // allows use of `@decorator` syntax
        "emitDecoratorMetadata": true, // adds useful additional information to decorators (see: https://stackoverflow.com/questions/1007981/how-to-get-function-parameter-names-values-dynamically/64169429#64169429)
        "resolveJsonModule": true, // allow importing json files
        "forceConsistentCasingInFileNames": true, // Ensure file names and references maintain the same casing scheme (e.g. `import './myFile'` fails if file name is `MyFile.ts`)
        "newLine": "lf", // Ensure emitted files (.d.ts and .js) use LF for newlines
        "preserveSymlinks": false, // Makes symlinks resolve to the actual file instead of the symlink itself (Note: Might cause issues with `npm link`). See: https://www.typescriptlang.org/tsconfig#preserveSymlinks and https://webpack.js.org/configuration/resolve/#resolvesymlinks
        "incremental": true, // Saves info from each build to a file in the output dir to allow for faster subsequent builds (e.g. don't rebuild this file if it hasn't changed)
        "isolatedModules": true, // make compatible with other typescript-processing plugins, e.g. babel, webpack, etc.
        "outDir": "dist", // Output dir of running `npx tsc`; don't use if using webpack/ts-loader, or override it manually in ts-loader options
        "declaration": true, // Generates typings.d.ts files
        "declarationDir": "dist/types", // Output dir for types
//        "removeComments": true, // Removes comments from output
//        "emitDeclarationOnly": true, // Only output `.d.ts` files
//        "noEmit": true, // don't emit outputs
//        "listFiles": true, // Prints all files imported by your code as well as your code. "listEmittedFiles" only shows output files.
//        "rootDir": ".", // Parent directory from which all transpiled code will be relative when outputted within `outDir`.
                          // e.g. If transpiling `<root>/src/*` with `outDir: dist`, then:
                          //    `rootDir: .`  =>  dist/src/*
                          //    `rootDir: undefined`  =>  dist/*
                          // Not usually needed since the `rootDir` is interpreted by the `include`, `exclude`, and `files` entries.
                          // Doesn't impact other path-resolution configs, like `include`, `exclude`, `files`, etc.
        "baseUrl": ".", // sets the base dir of source code import path prefixes (typescript's equivalent of NODE_PATH); doesn't affect tsconfig's paths
        "paths": {
            "@/*": [ "src/*" ],
            "~/*": [ "*" ]
        }
    },
    "include": [
        "./src/**/*"
    ],
    "exclude": [
        "./node_modules",
        "dist"
    ],

    /**
     * Configuring `ts-node` for running TypeScript files
     * --------------------------------------------------
     * - Website: https://typestrong.org/ts-node/docs/configuration
     * - Usage: https://github.com/TypeStrong/ts-node#api
     * - Options: https://github.com/TypeStrong/ts-node#options
     *
     * Most of the description is in the .npmrc, but the gist is that this allows running TypeScript files without
     * having to compile them to JavaScript first, i.e. no more `tsc && node output.js`!
     *
     * It does so by using a custom NodeJS module loader, so we can't use `--experimental-specifier-resolution=node`.
     * Since the project doesn't use `type: module` but does use `.mjs` files, we must override the base tsconfig's
     * `module` field - which is set to `ESNext` for source code - to be CJS. This can be reverted when package.json
     * is changed to `type: module`. See the .npmrc for more details.
     *
     *
     * Regarding `paths` import aliases
     * --------------------------------
     * Other than avoiding unnecessary disk writes to run TypeScript files, ts-node is particularly
     * helpful because without it, `paths` import aliases aren't respected in the local environment, even if
     * they're defined in tsconfig. `tsconfig-paths` fixes this without having to duplicate the definitions in
     * package.json like you would if you used `module-alias` (https://www.npmjs.com/package/module-alias).
     * To use it, we must require `tsconfig-paths/register` so it's loaded before the `node` process starts
     * running ts-node. This also helps with the lack of alias translation when building with `tsc` (especially
     * if `target` is ES >= 2019 where aliases are supported).
     * This is needed for ts-node regardless of how it's called (see .npmrc for a list of ways to call ts-node).
     * Alternatively, we could add `-r tsconfig-paths/register` in the command line, but putting it here
     * ensures it works all the time, making npm scripts more DRY.
     */
    // TODO Use swc: https://typestrong.org/ts-node/docs/transpilers#bundled-swc-integration
    "ts-node": {
        "require": [
            "tsconfig-paths/register"
        ],
        // Other ts-node configs that could be helpful with multiple tsconfig files.
        // Not necessary for our usage since the root tsconfig.json already includes all directories.
        // TODO Request that TS_NODE_OPTIONS be added as a config or environment variable so we can set configs only to be activated when running ts-node, e.g. TS_NODE_OPTIONS='--loader ts-node/esm'
//        "cwd": ".", // Or from env var/in .npmrc: TS_NODE_CWD=.
//        "projectSearchDir": ".",
//        "project": "./tsconfig.json", // Or from env var/in .npmrc: TS_NODE_PROJECT=./tsconfig.json
        "preferTsExts": true,
        "experimentalReplAwait": true,

        /**
         * Makes ts-node run faster by skipping type checking (see: https://github.com/TypeStrong/ts-node/discussions/1276).
         * Ironically, in multiple places (website, GitHub issues, etc.), the ts-node team recommends disabling
         * type checking (even though it's active by default) because type checking, building, and other "formal"
         * app operations should use `tsc` instead.
         */
        "transpileOnly": true,
        "moduleTypes": { // Activate this to override file types to be
//            "**/*.json": "esm",
//            "**/*.ts": "esm",
//            "**/*.js": "esm",
//            "**/*": "esm",
//            "**/*.mjs": "esm",
            "**/*.cjs": "cjs"
        },
        "compilerOptions": {
            "module": "NodeNext",
            "moduleResolution": "NodeNext",
            // Remove isolatedModules since ts-node scripts aren't being parsed by Babel, Webpack, or another parser
            "isolatedModules": false
        },
        "include": [
            "./**/*"
        ]
    }
}