{"id":13178,"library":"fastify-tsconfig","title":"Fastify TypeScript Configuration Preset","description":"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.","status":"active","version":"3.0.0","language":"javascript","source_language":"en","source_url":"https://github.com/fastify/tsconfig","tags":["javascript","tsconfig","typescript","ts","config","configuration","fastify"],"install":[{"cmd":"npm install fastify-tsconfig","lang":"bash","label":"npm"},{"cmd":"yarn add fastify-tsconfig","lang":"bash","label":"yarn"},{"cmd":"pnpm add fastify-tsconfig","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"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.","wrong":"import { someConfig } from 'fastify-tsconfig';","symbol":"tsconfig.json extends","correct":"{\n  \"extends\": \"fastify-tsconfig\",\n  \"compilerOptions\": {\n    \"outDir\": \"dist\"\n  },\n  \"include\": [\n    \"src/**/*.ts\"\n  ]\n}"},{"note":"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.","wrong":"const fastifyConfig = require('fastify-tsconfig');","symbol":"Configuration file","correct":"{ \"extends\": \"fastify-tsconfig\" }"},{"note":"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.","wrong":"{ \"extends\": \"./node_modules/fastify-tsconfig\" }","symbol":"tsconfig preset path","correct":"{ \"extends\": \"fastify-tsconfig/tsconfig.json\" }"}],"quickstart":{"code":"{\n  \"name\": \"my-fastify-app\",\n  \"version\": \"1.0.0\",\n  \"type\": \"module\",\n  \"main\": \"dist/index.js\",\n  \"scripts\": {\n    \"build\": \"tsc\",\n    \"start\": \"node dist/index.js\"\n  },\n  \"devDependencies\": {\n    \"fastify-tsconfig\": \"^3.0.0\",\n    \"typescript\": \"^5.0.0\"\n  }\n}\n// file: tsconfig.json\n{\n  \"extends\": \"fastify-tsconfig\",\n  \"compilerOptions\": {\n    \"outDir\": \"dist\",\n    \"sourceMap\": true,\n    \"declaration\": true\n  },\n  \"include\": [\n    \"src/**/*.ts\"\n  ],\n  \"exclude\": [\n    \"node_modules\"\n  ]\n}\n// file: src/index.ts\nimport Fastify from 'fastify';\n\nconst fastify = Fastify({ logger: true });\n\nfastify.get('/', async (request, reply) => {\n  return { hello: 'world' };\n});\n\nconst start = async () => {\n  try {\n    await fastify.listen({ port: 3000 });\n  } catch (err) {\n    fastify.log.error(err);\n    process.exit(1);\n  }\n};\n\nstart();","lang":"typescript","description":"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`."},"warnings":[{"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`.","message":"Version 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`.","severity":"breaking","affected_versions":">=3.0.0"},{"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.","message":"Version 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.","severity":"breaking","affected_versions":">=2.0.0 <3.0.0"},{"fix":"Always include `\"compilerOptions\": { \"outDir\": \"./dist\" }` (or your preferred output directory) in your project's `tsconfig.json`.","message":"By 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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"The 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.","severity":"gotcha","affected_versions":">=2.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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).","cause":"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.","error":"SyntaxError: Cannot use import statement outside a module"},{"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.","cause":"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.","error":"TS1202: An 'import' declaration can only be used in a .ts file or an ES module."},{"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.","cause":"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.","error":"TS2307: Cannot find module 'my-local-module' or its corresponding type declarations."}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":""}