From 5c3e830d074339ea499972566fe5af5deed298e2 Mon Sep 17 00:00:00 2001 From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com> Date: Mon, 10 Feb 2025 23:41:15 +0000 Subject: [PATCH 1/3] Bump the github-actions group with 2 updates (#3329) Signed-off-by: dependabot[bot] Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> --- .github/workflows/CI.yml | 4 ++-- .github/workflows/codeql.yml | 6 +++--- .github/workflows/deploy-prod-static.yml | 2 +- .github/workflows/publish-packages.yml | 2 +- .github/workflows/weekly-stats.yml | 2 +- 5 files changed, 8 insertions(+), 8 deletions(-) diff --git a/.github/workflows/CI.yml b/.github/workflows/CI.yml index 2ce637e4..94f7db6a 100644 --- a/.github/workflows/CI.yml +++ b/.github/workflows/CI.yml @@ -27,7 +27,7 @@ jobs: - uses: actions/setup-node@1d0ff469b7ec7b3cb9d8673fde0c81c44821de2a # v4.2.0 with: node-version: "18.x" - - uses: pnpm/action-setup@fe02b34f77f8bc703788d5817da081398fad5dd2 # v4.0.0 + - uses: pnpm/action-setup@a7487c7e89a18df4991f7f222e4898a00d66ddda # v4.1.0 - run: pnpm install @@ -86,7 +86,7 @@ jobs: - uses: actions/setup-node@1d0ff469b7ec7b3cb9d8673fde0c81c44821de2a # v4.2.0 with: node-version: 'lts/*' - - uses: pnpm/action-setup@fe02b34f77f8bc703788d5817da081398fad5dd2 # v4.0.0 + - uses: pnpm/action-setup@a7487c7e89a18df4991f7f222e4898a00d66ddda # v4.1.0 - run: pnpm install diff --git a/.github/workflows/codeql.yml b/.github/workflows/codeql.yml index 636291b4..21251963 100644 --- a/.github/workflows/codeql.yml +++ b/.github/workflows/codeql.yml @@ -44,7 +44,7 @@ jobs: # Initializes the CodeQL tools for scanning. - name: Initialize CodeQL - uses: github/codeql-action/init@dd746615b3b9d728a6a37ca2045b68ca76d4841a # v3.28.8 + uses: github/codeql-action/init@9e8d0789d4a0fa9ceb6b1738f7e269594bdd67f0 # v3.28.9 with: config-file: ./.github/codeql/codeql-configuration.yml # Override language selection by uncommenting this and choosing your languages @@ -54,7 +54,7 @@ jobs: # Autobuild attempts to build any compiled languages (C/C++, C#, or Java). # If this step fails, then you should remove it and run the build manually (see below). - name: Autobuild - uses: github/codeql-action/autobuild@dd746615b3b9d728a6a37ca2045b68ca76d4841a # v3.28.8 + uses: github/codeql-action/autobuild@9e8d0789d4a0fa9ceb6b1738f7e269594bdd67f0 # v3.28.9 # ℹ️ Command-line programs to run using the OS shell. # 📚 See https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idstepsrun @@ -68,4 +68,4 @@ jobs: # make release - name: Perform CodeQL Analysis - uses: github/codeql-action/analyze@dd746615b3b9d728a6a37ca2045b68ca76d4841a # v3.28.8 + uses: github/codeql-action/analyze@9e8d0789d4a0fa9ceb6b1738f7e269594bdd67f0 # v3.28.9 diff --git a/.github/workflows/deploy-prod-static.yml b/.github/workflows/deploy-prod-static.yml index f901a6ae..3ba369a6 100644 --- a/.github/workflows/deploy-prod-static.yml +++ b/.github/workflows/deploy-prod-static.yml @@ -34,7 +34,7 @@ jobs: with: node-version: "18.x" - - uses: pnpm/action-setup@fe02b34f77f8bc703788d5817da081398fad5dd2 # v4.0.0 + - uses: pnpm/action-setup@a7487c7e89a18df4991f7f222e4898a00d66ddda # v4.1.0 # Builds the modules, and boostraps the other modules - name: Build website diff --git a/.github/workflows/publish-packages.yml b/.github/workflows/publish-packages.yml index 40be7bfd..3ba45438 100644 --- a/.github/workflows/publish-packages.yml +++ b/.github/workflows/publish-packages.yml @@ -25,7 +25,7 @@ jobs: with: node-version: "18.x" registry-url: "https://registry.npmjs.org/" - - uses: pnpm/action-setup@fe02b34f77f8bc703788d5817da081398fad5dd2 # v4.0.0 + - uses: pnpm/action-setup@a7487c7e89a18df4991f7f222e4898a00d66ddda # v4.1.0 - name: Prepare website v2 run: | diff --git a/.github/workflows/weekly-stats.yml b/.github/workflows/weekly-stats.yml index 5a977094..b7911482 100644 --- a/.github/workflows/weekly-stats.yml +++ b/.github/workflows/weekly-stats.yml @@ -19,7 +19,7 @@ jobs: with: node-version: "18.x" - - uses: pnpm/action-setup@fe02b34f77f8bc703788d5817da081398fad5dd2 # v4.0.0 + - uses: pnpm/action-setup@a7487c7e89a18df4991f7f222e4898a00d66ddda # v4.1.0 - run: pnpm install From 76866547ecdc7bdef3f8c67798099447202eb1c8 Mon Sep 17 00:00:00 2001 From: Andrew Branch Date: Tue, 11 Feb 2025 15:36:54 -0800 Subject: [PATCH 2/3] Recommend rootDir and outDir in modules compiler option guide (#3330) --- .../en/modules-reference/guides/Choosing Compiler Options.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/packages/documentation/copy/en/modules-reference/guides/Choosing Compiler Options.md b/packages/documentation/copy/en/modules-reference/guides/Choosing Compiler Options.md index 4bda263e..6ff6a3c8 100644 --- a/packages/documentation/copy/en/modules-reference/guides/Choosing Compiler Options.md +++ b/packages/documentation/copy/en/modules-reference/guides/Choosing Compiler Options.md @@ -142,7 +142,9 @@ Choosing compilation settings as a library author is a fundamentally different p "verbatimModuleSyntax": true, "declaration": true, "sourceMap": true, - "declarationMap": true + "declarationMap": true, + "rootDir": "src", + "outDir": "dist" } } ``` @@ -185,6 +187,7 @@ Let’s examine why we picked each of these settings: - **`verbatimModuleSyntax: true`**. This setting protects against a few module-related pitfalls that can cause problems for library consumers. First, it prevents writing any import statements that could be interpreted ambiguously based on the user’s value of `esModuleInterop` or `allowSyntheticDefaultImports`. Previously, it was often suggested that libraries compile without `esModuleInterop`, since its use in libraries could force users to adopt it too. However, it’s also possible to write imports that only work _without_ `esModuleInterop`, so neither value for the setting guarantees portability for libraries. `verbatimModuleSyntax` does provide such a guarantee.[^1] Second, it prevents the use of `export default` in modules that will be emitted as CommonJS, which can require bundler users and Node.js ESM users to consume the module differently. See the appendix on [ESM/CJS Interop](/docs/handbook/modules/appendices/esm-cjs-interop.html#library-code-needs-special-considerations) for more details. - **`declaration: true`** emits type declaration files alongside the output JavaScript. This is needed for consumers of the library to have any type information. - **`sourceMap: true`** and **`declarationMap: true`** emit source maps for the output JavaScript and type declaration files, respectively. These are only useful if the library also ships its source (`.ts`) files. By shipping source maps and source files, consumers of the library will be able to debug the library code somewhat more easily. By shipping declaration maps and source files, consumers will be able to see the original TypeScript sources when they run Go To Definition on imports from the libraries. Both of these represent a tradeoff between developer experience and library size, so it’s up to you whether to include them. +- **`rootDir: true` and `outDir: true`**. Using a separate output directory is always a good idea, but it’s _necessary_ for libraries that publish their input files. Otherwise, [extension substitution](/docs/handbook/modules/reference.html#file-extension-substitution) will cause the library’s consumers to load the library’s `.ts` files instead of `.d.ts` files, causing type errors and performance problems. ### Considerations for bundling libraries From 3173c39c72e3405c9c7f313fad2c7ab2f07e5bb8 Mon Sep 17 00:00:00 2001 From: Tom Mrazauskas Date: Wed, 12 Feb 2025 09:02:29 +0200 Subject: [PATCH 3/3] Update Choosing Compiler Options.md (#3331) --- .../en/modules-reference/guides/Choosing Compiler Options.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/packages/documentation/copy/en/modules-reference/guides/Choosing Compiler Options.md b/packages/documentation/copy/en/modules-reference/guides/Choosing Compiler Options.md index 6ff6a3c8..6b1f0cdc 100644 --- a/packages/documentation/copy/en/modules-reference/guides/Choosing Compiler Options.md +++ b/packages/documentation/copy/en/modules-reference/guides/Choosing Compiler Options.md @@ -187,7 +187,7 @@ Let’s examine why we picked each of these settings: - **`verbatimModuleSyntax: true`**. This setting protects against a few module-related pitfalls that can cause problems for library consumers. First, it prevents writing any import statements that could be interpreted ambiguously based on the user’s value of `esModuleInterop` or `allowSyntheticDefaultImports`. Previously, it was often suggested that libraries compile without `esModuleInterop`, since its use in libraries could force users to adopt it too. However, it’s also possible to write imports that only work _without_ `esModuleInterop`, so neither value for the setting guarantees portability for libraries. `verbatimModuleSyntax` does provide such a guarantee.[^1] Second, it prevents the use of `export default` in modules that will be emitted as CommonJS, which can require bundler users and Node.js ESM users to consume the module differently. See the appendix on [ESM/CJS Interop](/docs/handbook/modules/appendices/esm-cjs-interop.html#library-code-needs-special-considerations) for more details. - **`declaration: true`** emits type declaration files alongside the output JavaScript. This is needed for consumers of the library to have any type information. - **`sourceMap: true`** and **`declarationMap: true`** emit source maps for the output JavaScript and type declaration files, respectively. These are only useful if the library also ships its source (`.ts`) files. By shipping source maps and source files, consumers of the library will be able to debug the library code somewhat more easily. By shipping declaration maps and source files, consumers will be able to see the original TypeScript sources when they run Go To Definition on imports from the libraries. Both of these represent a tradeoff between developer experience and library size, so it’s up to you whether to include them. -- **`rootDir: true` and `outDir: true`**. Using a separate output directory is always a good idea, but it’s _necessary_ for libraries that publish their input files. Otherwise, [extension substitution](/docs/handbook/modules/reference.html#file-extension-substitution) will cause the library’s consumers to load the library’s `.ts` files instead of `.d.ts` files, causing type errors and performance problems. +- **`rootDir: "src"`** and **`outDir: "dist"`**. Using a separate output directory is always a good idea, but it’s _necessary_ for libraries that publish their input files. Otherwise, [extension substitution](/docs/handbook/modules/reference.html#file-extension-substitution) will cause the library’s consumers to load the library’s `.ts` files instead of `.d.ts` files, causing type errors and performance problems. ### Considerations for bundling libraries @@ -208,4 +208,4 @@ If you’re using a bundler to emit your library, then all your (non-externalize A single TypeScript compilation (whether emitting or just type checking) assumes that each input file will only produce one output file. Even if `tsc` isn’t emitting anything, the type checking it performs on imported names rely on knowledge about how the output file will behave at runtime, based on the module- and emit-related options set in the tsconfig.json. While third-party emitters are generally safe to use in combination with `tsc` type checking as long as `tsc` can be configured to understand what the other emitter will emit, any solution that emits two different sets of outputs with different module formats while only type checking once leaves (at least) one of the outputs unchecked. Because external dependencies may expose different APIs to CommonJS and ESM consumers, there’s no configuration you can use to guarantee in a single compilation that both outputs will be type-safe. In practice, most dependencies follow best practices and dual-emit outputs work. Running tests and [static analysis](https://npmjs.com/package/@arethetypeswrong/cli) against all output bundles before publishing significantly reduces the chance of a serious problem going unnoticed. -[^1]: `verbatimModuleSyntax` can only work when the JS emitter emits the same module kind as `tsc` would given the tsconfig.json, source file extension, and package.json `"type"`. The option works by enforcing that the `import`/`require` written is identical to the `import`/`require` emitted. Any configuration that produces both an ESM and a CJS output from the same source file is fundamentally incompatible with `verbatimModuleSyntax`, since its whole purpose is to prevent you from writing `import` anywhere that a `require` would be emitted. `verbatimModuleSyntax` can also be defeated by configuring a third-party emitter to emit a different module kind than `tsc` would—for example, by setting `"module": "esnext"` in tsconfig.json while configuring Babel to emit CommonJS. \ No newline at end of file +[^1]: `verbatimModuleSyntax` can only work when the JS emitter emits the same module kind as `tsc` would given the tsconfig.json, source file extension, and package.json `"type"`. The option works by enforcing that the `import`/`require` written is identical to the `import`/`require` emitted. Any configuration that produces both an ESM and a CJS output from the same source file is fundamentally incompatible with `verbatimModuleSyntax`, since its whole purpose is to prevent you from writing `import` anywhere that a `require` would be emitted. `verbatimModuleSyntax` can also be defeated by configuring a third-party emitter to emit a different module kind than `tsc` would—for example, by setting `"module": "esnext"` in tsconfig.json while configuring Babel to emit CommonJS.