Registry / web-framework / fastify-tsconfig

fastify-tsconfig

library3.0.0jsnpmunverified

fastify-tsconfig is a shared TypeScript configuration preset designed for Fastify projects, streamlining the setup of `tsconfig.json` files. The current stable version is `3.0.0`. This package aims to provide a consistent and modern TypeScript experience across Fastify applications and libraries, with a focus on contemporary Node.js environments. It configures `module` and `moduleResolution` to `NodeNext`, aligning with Node.js's native ESM capabilities and supporting both CommonJS and ES Modules based on `package.json`'s `type` field. It targets `ES2023` by default, requiring Node.js 20 or newer, which is a key differentiator for modern Fastify development, enabling the use of recent language features without additional transpilation steps. The release cadence is generally aligned with updates to TypeScript itself or Fastify's core ecosystem needs, rather than a fixed schedule.

web-framework

npm install fastify-tsconfig

github ↗package ↗

INSTALL

IMPORT

SIG · FASTIFY-TSCONFIG

fastify-tsconfig

web-frameworkjavascriptv3.0.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

tsconfig.json extends

✓ { "extends": "fastify-tsconfig", "compilerOptions": { "outDir": "dist" }, "include": [ "src/**/*.ts" ] }

✗ import { someConfig } from 'fastify-tsconfig';

This package is a TypeScript configuration preset and is designed to be extended in your project's `tsconfig.json`. It does not export JavaScript/TypeScript symbols for runtime import.

Configuration file

✓ { "extends": "fastify-tsconfig" }

✗ const fastifyConfig = require('fastify-tsconfig');

Attempting to `require()` or `import` `fastify-tsconfig` as a CommonJS or ES module will result in a runtime error, as it is a JSON configuration file, not a runnable module.

tsconfig preset path

✓ { "extends": "fastify-tsconfig/tsconfig.json" }

✗ { "extends": "./node_modules/fastify-tsconfig" }

While `fastify-tsconfig` usually resolves correctly, explicitly specifying `fastify-tsconfig/tsconfig.json` can be clearer, though not strictly necessary in most setups. Do not reference `node_modules` directly.

Demonstrates how to install `fastify-tsconfig`, extend it in `tsconfig.json`, configure `package.json` for ESM, and set up a basic Fastify application that can be built with `tsc`.

{ "name": "my-fastify-app", "version": "1.0.0", "type": "module", "main": "dist/index.js", "scripts": { "build": "tsc", "start": "node dist/index.js" }, "devDependencies": { "fastify-tsconfig": "^3.0.0", "typescript": "^5.0.0" } } // file: tsconfig.json { "extends": "fastify-tsconfig", "compilerOptions": { "outDir": "dist", "sourceMap": true, "declaration": true }, "include": [ "src/**/*.ts" ], "exclude": [ "node_modules" ] } // file: src/index.ts import Fastify from 'fastify'; const fastify = Fastify({ logger: true }); fastify.get('/', async (request, reply) => { return { hello: 'world' }; }); const start = async () => { try { await fastify.listen({ port: 3000 }); } catch (err) { fastify.log.error(err); process.exit(1); } }; start();

Debug

Known issues

breakingVersion 3.0.0 updates the default TypeScript `target` to `ES2023`. This requires Node.js 20 or newer to run the compiled output. Projects targeting older Node.js versions will need to explicitly override the `target` in their `tsconfig.json`.

fix

If supporting Node.js versions older than 20, add `"compilerOptions": { "target": "ES2022" }` (for Node.js >= 16.11.0) or an earlier ES target to your `tsconfig.json`.

affects: >=3.0.0

breakingVersion 2.0.0 updated the default TypeScript `target` to `ES2022` and required Node.js > 16.11.0. This was a breaking change for projects targeting older runtimes.

fix

Ensure your Node.js version is at least 16.11.0. For older runtimes, downgrade to `fastify-tsconfig@1.x` or override the `target` compiler option.

affects: >=2.0.0 <3.0.0

gotchaBy default, `fastify-tsconfig` does not set the `outDir` compiler option. If you do not specify an `outDir` in your project's `tsconfig.json`, compiled JavaScript files (`.js`) and declaration files (`.d.ts`) will be output alongside their source (`.ts`) files, which is generally undesirable for project structure.

fix

Always include `"compilerOptions": { "outDir": "./dist" }` (or your preferred output directory) in your project's `tsconfig.json`.

affects: >=1.0.0

gotchaThe configuration sets `module` and `moduleResolution` to `NodeNext`. This tightly couples compilation behavior to Node.js's module resolution rules, requiring careful configuration of your `package.json` `"type"` field (e.g., `"type": "module"` for ESM, `"type": "commonjs"` for CJS) and potentially specific file extensions (`.mts`, `.cts`) for mixed module types.

fix

Review the 'Configuration module and moduleResolution' section in the README. Ensure your `package.json` `"type"` field is correctly set, and use `.mts` for ESM source files in CJS projects, or `.cts` for CJS source files in ESM projects, as needed.

affects: >=2.0.0

Errors

Common errors & fixes

SyntaxError: Cannot use import statement outside a module

Your project's `package.json` is configured for CommonJS (`"type": "commonjs"` or no `"type"` field), but you are using ESM `import` syntax in a file compiled by TypeScript with `NodeNext` module resolution.

fix

Set `"type": "module"` in your `package.json` to enable ESM, or ensure all files using `import` syntax are correctly designated as ES Modules (e.g., using `.mjs` or `.mts` extensions in a CJS project if configured for it).

TS1202: An 'import' declaration can only be used in a .ts file or an ES module.

TypeScript is attempting to compile a file as CommonJS, but it contains ESM `import` or `export` syntax. This typically happens when `"type": "commonjs"` is in `package.json` but a `.ts` file is implicitly treated as ESM by `NodeNext` or has ESM syntax.

fix

Ensure your `package.json` `"type"` field is correctly set. If `"type": "commonjs"`, ensure your source files use CommonJS syntax or are explicitly `.mts` if they need to be ESM. If `"type": "module"`, ensure all files are compatible ESM or use `.cts` for CommonJS files.

TS2307: Cannot find module 'my-local-module' or its corresponding type declarations.

When `moduleResolution` is `NodeNext`, TypeScript strictly follows Node.js resolution rules, including `package.json` `exports` and `imports` fields. Incorrectly configured `exports` in a local `package.json` for a referenced module can lead to this.

fix

Verify that your `package.json` `exports` field (for modules within your project/monorepo) is correctly configured to point to your compiled JavaScript and declaration files. Ensure paths are relative and correctly specify `import` and `require` conditions if applicable.

Upgrade

Version history

3.0.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

2 hits · last 30 days

node

Resources

githubhttps://github.com/fastify/tsconfig ↗

packagehttps://www.npmjs.com/package/fastify-tsconfig ↗