.npmrc

###  npm configurations  ###
# Configs can be passed via CLI or set here
# Docs: https://docs.npmjs.com/cli/v7/using-npm/config


# Allow publishing to/installing from a private npm registry.
# Note that the private package must be scoped and that the original
# npm registry must be added so public packages are still installed from
# the original registry.
#
# If using Yarn v1, add this to your `.yarnrc` file: registry "https://registry.yarnpkg.com"
# and it will automatically pick up the details from both `.npmrc` and `.yarnrc`
#
# @d-pow:registry=https://npm.pkg.github.com/
# registry=https://registry.npmjs.org/


# Always colorize stdout
color=always
# Do so for plain `node` processes as well
# See:
#   - https://github.com/nodejs/node/issues/37404
FORCE_COLOR=1


# Don't allow `npm install` unless the NodeJS version complies
# with the `engines` field in package.json
# npm only blocks `install`, while yarn will block all scripts
engine-strict=true


# npm v7 made `(pre|post)?install` scripts in dependencies silent
# by default. `foreground-scripts=true` undoes that/makes them visible.
# See:
#   https://github.com/npm/cli/issues/1905#issuecomment-865356457
#   https://github.com/npm/cli/issues/1905#issuecomment-875999674
#
# However, it actually blocks parallelism in the process, so instead,
# `loglevel` should be used. As of now (with very few dependencies),
# the install times are cut in half - from 20s to 10s simply by
# removing `foreground-scripts`.
#
# Note: The more verbose log levels are more annoying than helpful
# so leave this option unset (default is `loglevel=notice`.
#
# Docs:
#   https://docs.npmjs.com/cli/v7/using-npm/config#loglevel
# foreground-scripts=true
# loglevel=timing


# Allows passing in options to the `node` command when
# running `npm`. This allows you to avoid having to
# use `node --option node_modules/.bin/executable`.
# Options only include those that are valid `NODE_OPTIONS`.
# See: https://nodejs.org/api/cli.html#cli_node_options_options
#
# Notable ones include:
#
# * --experimental-top-level-await
#   Allow top-level `await` calls so that webpack.config.mjs can await CJS imports.
#
#
# * --experimental-json-modules
#   Allow JSON files to be imported in .mjs files.
#
#
# * --experimental-import-meta-resolve
#   Allow the use of `import.meta.resolve` to use file paths to generate import-safe URLs (different from browser-safe URLs).
#
#
# * --experimental-specifier-resolution=node
#   Allow automatic extension resolution as well as importing index.js from directories like source code can
#       e.g. `import file from './file'` instead of './file.js', and `import Utils from './utils'` instead of './utils/index.js'.
#   Note: This will cause some `npx` commands to fail if the executables don't have a file extension on them (e.g. `npx tsc`).
#   Relatedly, if using a different script runner/node module loader, e.g. `ts-node` to run TypeScript files, then they will
#   sometimes fail as well b/c they'll either be shell scripts, will need their custom module loader (which won't work b/c we
#   overrode it with this flag), or their loaders depending on files being translated to CommonJS before being executed (likely in RAM
#   by their custom loader and/or NodeJS itself).
#   This can be fixed in your own code by making it executable and adding a shebang, e.g.
#       #!/usr/bin/env -S node
#       #!/usr/bin/env -S npx
#       #!/usr/bin/env -S npx ts-node
#   For example, to use `ts-node` (for running TypeScript files from the CLI without having to compile them into JavaScript first),
#   then they recommend running via either:
#       1. Using ts-node directly: `ts-node file.ts`
#       2. Using normal node command:  ESM: `node --loader ts-node/esm file.ts`  -  CJS: `node -r ts-node/register file.ts`
#       3. Just run the file directly: Use a shebang like above (See: https://github.com/TypeStrong/ts-node/issues/639)
#       4. Add `--loader ts-node/(register|esm)` to `node-options` here (forces all node commands to run with `ts-node`, even `npx`)
#       n. TL;DR - Check out this issue for a full analysis of way to run `ts-node`: https://github.com/TypeStrong/ts-node/issues/995
#   But since `ts-node` uses its own module loader, we cannot set `--experimental-specifier-resolution=node` in `node-options`
#   b/c it requires its own loader.
#   Finally, for `ts-node`, if package.json uses `type: module`, then `ts-node` must use `module: ESNext` as well.
#
#
# * --no-warnings / --redirect-warnings=<file>
#   Removes warnings from STDERR or redirects them to <file>.
#   If you want to use ts-node by default for all files, then this will be necessary to reduce console noise:
#   --loader=ts-node/register --no-warnings
node-options='--experimental-top-level-await --experimental-json-modules --experimental-import-meta-resolve'

# TODO Find out how to watch files for changes in ts-node - helpful when running back-end scripts, similar to Webpack's auto-reload or HMR.


# For some reason, `npm run` doesn't use the default shell,
# nor the one from the `$SHELL` env var.
# It also doesn't allow `/usr/bin/env bash`, `process.env.SHELL`,
# or `$0`, so it has to be set manually here.
#
# Note: Any env vars must be encapsulated in braces, i.e. `${SHELL}` instead of `$SHELL`.
#   See:
#       https://answers.netlify.com/t/support-guide-using-private-npm-modules-on-netlify/795/30?page=2
#
# Default to Bash since we have npm scripts that use job control and, even if SHELL is set in GitHub's CI/CD Yaml configs,
# that only applies for the first command. In our case, the first command is always an npm script, i.e. `npm <my-script>`,
# rather than a Bash command (using grep, sed, etc.).
# As such, the execution order goes `bash --> npm --> sh` for any npm script using shell commands.
# But we want `bash --> npm --> bash` which is only possible if we change npm's default shell from within npm's own configs.
script-shell=bash


# Format stdout with JSON rather than normal text.
# Useful for analyzing errors and such when necessary.
# Added just for transparency
#json=true