@codecompose/typescript-config 2.1.0-0 → 2.1.0

package/README.md

@@ -1,22 +1,17 @@
 # typescript-config
 
-Opinionated reusable Typescript configurations. Out-of-the-box we assume:
+Opinionated and reusable Typescript configurations, geared towards modern build tooling in both monorepos and single repositories.
 
-- You transpile using a bundler
-- You want strict rules
-- Use of `src` and `dist` directories
-- Use of `~/` as path alias for `src`
+- Only use Typescript for type-checking and incremental builds (but no emit).
+- Use your bundler to output code, source-maps and type declarations where needed.
+- Use strict settings, incl `noUncheckedIndexedAccess` and `erasableSyntaxOnly`.
+- Assume `src` and `dist` directories
+- Use of `~/` or `@/` as path alias for `src`
+- Leverages TS 5.5 feature `${configDir}` to remove all client configuration.
 
-Of course, you can still choose to override any of the defaults in your own
-config.
 
-## Structure
+To use this successfully, you would need a modern bundler like [tsdown](https://tsdown.dev/). You can check out the [mono-ts](https://github.com/0x80/mono-ts) boilerplate for a working example of a modern monorepo setup with tsdown.
 
-Configurations are organized based on their intended use:
-
-- **Root configurations**: For stand-alone projects or general use
-- **Monorepo configurations**: Under the `/monorepo` path for monorepo-specific
-  setups
 
 ## Install
 
@@ -30,38 +25,27 @@ Configurations are organized based on their intended use:
 }
 ```
 
-## Available Configurations
-
-### Base Configuration
-
-- `base` - Base configuration with common settings
+Often no other configuration is needed besides extends.
 
-### Stand-alone Configurations
-
-- `base` - For anything non-specific
-- `library` - For general libraries
-- `react-library` - For React component libraries
-- `nextjs` - For Next.js applications
-- `service` - For a backend service like and API server or cloud function
+## Available Configurations
 
-### Monorepo Configurations
+- `base` -  Anything non-specific
+- `library` - Standalone libraries (not part of a monorepo)
+- `shared-library` - Shared libraries in a monorepo
+- `react-library` - Standalone React component libraries (not part of a monorepo)
+- `shared-react-library` - Shared React component libraries in a monorepo
+- `nextjs` - Next.js applications
+- `service` - A backend service like and API server or cloud function
 
-When using a monorepo, the packages that other packages depend on should use the
-"shared" variant.
 
-- `shared-library` - For shared libraries in a monorepo
-- `shared-react-library` - For shared React component libraries in a monorepo
+For other project types, like a CLI or E2E app, you can use the `base` configuration.
 
-The `nextjs` and `service` configs are compatible with both monorepo and
-non-monorepo.
+## Assuming Bundler Output
 
-For other project types, like a CLI or E2E app, you can use the `base`
-configuration.
+Output like source maps, and type declarations is disabled, because it is assumed that your bundler will handle that.
 
-## Assumptions and Recommendations
 
-Source maps are not enabled, because we assume that your bundler will handle
-that.
+## Incremental Builds
 
 All configurations have `incremental` set to `true`. In my experience, it can
 happen that builds get stuck in limbo and you need to delete the
@@ -70,13 +54,25 @@ recommend adding the following script to your manifest based on `del-cli`:
 
 `"clean": "del-cli dist tsconfig.tsbuildinfo"`
 
-## Known Issues
+## Project References
+
+The shared-library and shared-react-library configurations have `composite` set to `true`. This is required for Typescript "project references" to work in a monorepo. They provide IDE go-to-definition, without having to emit the module output.
+
+In practice, this means that if you alter code in a shared package, the consuming app or library will pick up the changes, without requiring a watch task on the shared package to trigger a rebuild on every change.
+
+Without project references, the consuming code would only see the `dist` output of the shared package.
+
+If you prefer to work without project references, you should set your bundler to also [output declaration maps](https://tsdown.dev/options/dts#declaration-map), but not all bundlers can do this.
+
+## Publishing to NPM
+
+If you publish your package, it is recommended to include the Typescript source and type declaration maps. This allows the consumer to jump straight to the original source code, which is nice for readability and learning.
+
+To export source files next to your dist output, you define the `files` field in your package.json as `["src", "dist"]`.
+
+## Caveats
+
+Older tooling might not correctly interpret the use of `${configDir}` introduced in TS v5.5 that this package depends on.
 
-At the time of writing, not all tooling correctly interprets the use of
-`${configDir}` introduced in TS v5.5 that this package depends on.
+Next.js v15 seems to require you to explicitly define "includes". If you give it just "src" it will inject its own types on startup. I assume this will improve in the future.
 
-- Next.js will require you to explicitly defined "includes". Give it "src" and
-  it will inject its types on startup.
-- TSUP will not understand the tsconfig if you ask it to generate type
-  definitions. I use tsc to generate the types, as demonstrated in
-  [mono-ts](https://github.com/0x80/mono-ts).

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@codecompose/typescript-config",
   "description": "Opinionated reusable TypeScript configurations",
-  "version": "2.1.0-0",
+  "version": "2.1.0",
   "license": "MIT",
   "author": "Thijs Koerselman",
   "publishConfig": {
@@ -10,14 +10,14 @@
   "keywords": [
     "typescript",
     "config",
-    "configuration",
     "monorepo",
     "strict",
     "reusable",
     "nextjs",
     "react",
     "library",
-    "service"
+    "service",
+    "bundler"
   ],
   "files": [
     "src"

package/src/base.json

@@ -17,10 +17,8 @@
     "strict": true,
     "noUncheckedIndexedAccess": true,
     "noImplicitOverride": true,
+    "erasableSyntaxOnly": true,
 
-    /* Assuming bundler will output EVERYTHING. You'll need a modern bundler
-    like tsdown to output declarationMaps for shared monorepo libraries. */
-    "noEmit": true,
     /* Opinion */
     "incremental": true,
     "tsBuildInfoFile": "${configDir}/tsconfig.tsbuildinfo",

package/src/library.json

@@ -1,8 +1,9 @@
 {
   "$schema": "https://json.schemastore.org/tsconfig",
-  "display": "Standalone shared library",
+  "display": "Standalone library (not part of a monorepo)",
   "extends": "./base.json",
   "compilerOptions": {
-    /* Assuming your bundler will output declaration and declarationMap */
+     /* Assuming your bundler will output everything.  */
+    "noEmit": true,
   }
 }

package/src/nextjs.json

@@ -5,6 +5,7 @@
   "compilerOptions": {
     "jsx": "preserve", // next does its own jsx transformation
     "lib": ["dom", "dom.iterable", "esnext"],
+    "noEmit": true, // nextjs bundler will output everything
     "rootDir": "${configDir}", // nextjs targets files outside of src in root as well
     "plugins": [
       {

package/src/react-library.json

@@ -4,6 +4,8 @@
   "extends": "./base.json",
   "compilerOptions": {
     "lib": ["dom", "dom.iterable", "esnext"],
-    "jsx": "react-jsx"
+    "jsx": "react-jsx",
+    /* Assuming your bundler will output everything.  */
+    "noEmit": true
   }
 }

package/src/service.json

@@ -1,6 +1,9 @@
 {
   "$schema": "https://json.schemastore.org/tsconfig",
-  "display": "Backend service",
+  "display": "Backend service / app",
   "extends": "./base.json",
-  "compilerOptions": {}
+  "compilerOptions": {
+     /* Assuming your bundler will output everything.  */
+    "noEmit": true,
+  }
 }

package/src/shared-library.json

@@ -3,8 +3,10 @@
   "display": "Monorepo shared library",
   "extends": "./library.json",
   "compilerOptions": {
-    /* Required for project references, which provide go-to-definition in your IDE without first having to build the module, which is essential during development. */
+    /* Required for project references, which provide go-to-definition in your
+    IDE without first having to build the module, which is essential during development. */
     "composite": true
-    /* Assuming your bundler will output type declarations and declaration-maps */
+    /* Assuming your bundler will output everything, but we can not have noEmit
+    enabled because it is not compatible with composite  / project references */
   }
 }

package/src/shared-react-library.json

@@ -3,8 +3,10 @@
   "display": "Monorepo shared React component library",
   "extends": "./react-library.json",
   "compilerOptions": {
-    /* Required for project references, which provide go-to-definition in your IDE without first having to build the module, which is essential during development. */
+    /* Required for project references, which provide go-to-definition in your
+    IDE without first having to build the module, which is essential during development. */
     "composite": true
-    /* Assuming your bundler will output type declarations and declaration-maps */
+     /* Assuming your bundler will output everything, but we can not have noEmit
+    enabled because it is not compatible with composite  / project references */
   }
 }