diff --git a/README.md b/README.md index 42557d5..9d19fac 100644 --- a/README.md +++ b/README.md @@ -12,50 +12,117 @@ $ npm install --save-dev fastify-tsconfig Create your own `tsconfig.json` in the projects' root folder and extend it from `fastify-tsconfig`, overriding or adding the desired settings. By default, no `outDir` is set (because of [this issue](https://github.com/Microsoft/TypeScript/issues/29172)), so be sure to add one. +### Configuration module and moduleResolution + +This configuration sets `"module"` and `"moduleResolution"` to [`NodeNext`](https://www.typescriptlang.org/docs/handbook/esm-node.html). This means that TypeScript will read the nearest `package.json` file in the scope and search for the `"type"` field or the absence of it. + +If `type` is not set or is `"type": "commonjs"` the emitted code will be CommonJS, with `.js` extension. Moreover, `tsc` will complain if ESM-only properties/features are used in source files. If you want to emit `.mjs` files, use the `.mts` extension. +On the other hand, if `"type": "module"` is set, the sources will be compiled to the ESM with the `.js` extension. In this case, if you want to emit `.cjs` files, use the `.cts` extension for the source file. + +The "following the Node.js rules" goes also for the `package.json` `exports` field. If `type` is set, regardless of the value, TypeScript will check the `exports` field to know where the compiled code and the types are located. If the `type` field is not set, it will check for the `main` and `types` fields. + +#### CommonJS example +`package.json` +```jsonc +{ + "name": "my-package", + "type": "commonjs", + "main": "dist/index.js", // this is for older Node.js versions + "types": "dist/index.d.ts", // this is optional and can be omitted + "exports": { + "import": "./dist/index.js", + "require": "./dist/index.js", + "types": "./dist/index.d.ts" // this is optional and can be omitted + } +} +``` +`tsconfig.json` +```jsonc +{ + "extends": "fastify-tsconfig", + "compilerOptions": { + "outDir": "dist", + "sourceMap": true + }, + "include": [ + "src/**/*.ts" + ] +} +``` +#### ESM example +`package.json` +```jsonc +{ + "name": "my-package", + "type": "module", + "main": "dist/index.js", // this is for older Node.js versions + "types": "dist/index.d.ts", // this is optional and can be omitted + "exports": { + "import": "./dist/index.js", + "require": "./dist/index.js", + "types": "./dist/index.d.ts" // this is optional and can be omitted + } +} +``` +`tsconfig.json` +```jsonc +{ + "extends": "fastify-tsconfig", + "compilerOptions": { + "outDir": "dist", + "sourceMap": true + }, + "include": [ + "src/**/*.ts" + ] +} +``` +### Extending this configuration + Depending on the type of the project, you should add the following settings. -### Application +#### Application `tsconfig.json` ```json { "extends": "fastify-tsconfig", "compilerOptions": { - "outDir": "dist", - "sourceMap": true + "outDir": "dist", + "sourceMap": true }, "include": [ - "src/**/*.ts" + "src/**/*.ts" ] } ``` -### Package +#### NPM Package `tsconfig.json` ```json { "extends": "fastify-tsconfig", "compilerOptions": { - "outDir": "dist", - "declaration": true + "outDir": "dist", + "declaration": true }, "include": [ - "src/**/*.ts" + "src/**/*.ts" ] } ``` -### Monorepo Package +#### Monorepo Package `tsconfig.json` ```json { "extends": "fastify-tsconfig", "compilerOptions": { - "outDir": "dist", - "declarationMap": true, - "composite": true + "outDir": "dist", + "declarationMap": true, + "composite": true }, "include": [ - "src/**/*.ts" + "src/**/*.ts" ] } ``` diff --git a/package.json b/package.json index f0d3f5a..5708f4d 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "fastify-tsconfig", - "version": "2.0.0", + "version": "1.0.1", "description": "Shared TypeScript configuration", "license": "MIT", "repository": { @@ -14,7 +14,7 @@ }, "main": "tsconfig.json", "engines": { - "node": ">=16.13.2" + "node": ">=18.0.0" }, "files": [ "tsconfig.json"