Merge pull request #26 from total-typescript/matt/added-section-on-import-type-and-added-cjs-context-to-module-nodenext

Added section on import type and added CJS context to module NodeNext

Author: tayiorbeii

book-content/chapters/14-configuring-typescript.md

@@ -72,10 +72,11 @@ Based on your answers to the above questions, here's how the complete `tsconfig.
     "strict": true,
     "noUncheckedIndexedAccess": true,
 
-    /* If transpiling with TypeScript: */
+    /* If transpiling with tsc: */
     "module": "NodeNext",
     "outDir": "dist",
     "sourceMap": true,
+    "verbatimModuleSyntax": true,
 
     /* AND if you're building for a library: */
     "declaration": true,
@@ -84,7 +85,7 @@ Based on your answers to the above questions, here's how the complete `tsconfig.
     "composite": true,
     "declarationMap": true,
 
-    /* If NOT transpiling with TypeScript: */
+    /* If NOT transpiling with tsc: */
     "module": "Preserve",
     "noEmit": true,
 
@@ -363,6 +364,216 @@ This is because the bundler will take care of resolving the file paths and exten
 
 This means that if you're using an external bundler or transpiler, you should use `module: "Preserve"` in your `tsconfig.json` file. This is also true if you're using a frontend framework like Next.js, Remix, Vite, or SvelteKit - it will handle the bundling for you.
 
+## Importing Types With `import type`
+
+When you're importing types from other files, TypeScript has some choices to make. Let's say you're importing a type of `Album` from `album.ts`:
+
+```typescript
+// index.ts
+
+import { Album } from "./album";
+```
+
+What should the emitted JavaScript look like? We're only importing a type, which disappears at runtime. Should the import remain, but with the type removed?
+
+```javascript
+// index.js
+
+import {} from "./album";
+```
+
+Or should the import be removed entirely?
+
+These decisions matter, because modules can contain effects which run when they're first imported. For instance, `album.ts` might call a `console.log` statement:
+
+```typescript
+// album.ts
+
+export interface Album {
+  title: string;
+  artist: string;
+  year: number;
+}
+
+console.log("Imported album.ts");
+```
+
+Now, if TypeScript removes (or, as they say in the TypeScript docs, elides) the import, the `console.log` statement won't run. This can be surprising if you're not expecting it.
+
+The way TypeScript resolves this is with the `import type` syntax. If you're importing a type and you don't want the import to be emitted in the JavaScript, you can use `import type`:
+
+```typescript
+// index.ts
+
+import type { Album } from "./album";
+```
+
+Now, only the type information is imported, and the import is removed from the emitted JavaScript:
+
+```javascript
+// index.js
+
+// No import statement
+```
+
+### `import type { X }` vs `import { type X }`
+
+You can combine `import` and `type` in two ways. You can either mark the entire line as a type import:
+
+```typescript
+import type { Album } from "./album";
+```
+
+Or, if you want to combine runtime imports with type imports, you can mark the type itself as a type import:
+
+```typescript
+import { type Album, createAlbum } from "./album";
+```
+
+In this case, `createAlbum` will be imported as a runtime import, and `Album` will be imported as a type import.
+
+In both cases, it's clear what will be removed from the emitted JavaScript. The first line will remove the entire import, and the second line will remove only the type import.
+
+### `verbatimModuleSyntax` Enforces `import type`
+
+TypeScript has gone through various iterations of configuration options to support this behavior. `importsNotUsedAsValues` and `preserveValueImports` both tried to solve the problem. But since TypeScript 5.0, `verbatimModuleSyntax` is the recommended way to enforce `import type`.
+
+The behavior described above, where imports are elided if they're only used for types, is what happens when `verbatimModuleSyntax` is set to `true`.
+
+## ESM and CommonJS
+
+There are two ways to modularize your code in TypeScript: ECMAScript Modules (ESM) and CommonJS (CJS). These two module systems operate slightly differently, and they don't always work together cleanly.
+
+ES Modules use `import` and `export` statements:
+
+```typescript
+import { createAlbum } from "./album";
+
+export { createAlbum };
+```
+
+CommonJS uses `require` and `module.exports`:
+
+```typescript
+const { createAlbum } = require("./album");
+
+module.exports = { createAlbum };
+```
+
+Understanding the interoperability issues between ESM and CJS is a little beyond the scope of this book. Instead, we'll look at how to set up TypeScript to make working with both module systems as easy as possible.
+
+### How Does TypeScript Know What Module System To Emit?
+
+Imagine we have our `album.ts` file that exports a `createAlbum` function:
+
+```typescript
+// album.ts
+
+export function createAlbum(
+  title: string,
+  artist: string,
+  year: number,
+): Album {
+  return { title, artist, year };
+}
+```
+
+When this file is turned into JavaScript, should it emit `CJS` or `ESM` syntax?
+
+```javascript
+// ESM
+
+export function createAlbum(title, artist, year) {
+  return { title, artist, year };
+}
+```
+
+```javascript
+// CJS
+
+function createAlbum(title, artist, year) {
+  return { title, artist, year };
+}
+
+module.exports = {
+  createAlbum,
+};
+```
+
+The way this is decided is via `module`. You can hardcode this by choosing some older options. `module: CommonJS` will always emit CommonJS syntax, and `module: ESNext` will always emit ESM syntax.
+
+But if you're using TypeScript to transpile your code, I recommend using `module: NodeNext`. This has several complex rules built-in for understanding whether to emit CJS or ESM:
+
+The first way we can influence how TypeScript emits your modules with `module: NodeNext` is by using `.cts` and `.mts` extensions.
+
+If we change `album.ts` to `album.cts`, TypeScript will emit CommonJS syntax, and the emitted file extension will be `.cjs`.
+
+If we change `album.ts` to `album.mts`, TypeScript will emit ESM syntax, and the emitted file extension will be `.mjs`.
+
+If we keep `album.ts` the same, TypeScript will look up the directories for the closest `package.json` file. If the `type` field is set to `module`, TypeScript will emit ESM syntax. If it's set to `commonjs` (or unset, matching Node's behavior), TypeScript will emit CJS syntax.
+
+| File Extension | Emitted File Extension | Emitted Module System               |
+| -------------- | ---------------------- | ----------------------------------- |
+| `album.mts`    | `album.mjs`            | ESM                                 |
+| `album.cts`    | `album.cjs`            | CJS                                 |
+| `album.ts`     | `album.js`             | Depends on `type` in `package.json` |
+
+### `verbatimModuleSyntax` With ESM and CommonJS
+
+`verbatimModuleSyntax` can help you be more explicit about which module system you're using. If you set `verbatimModuleSyntax` to `true`, TypeScript will error if you try to use `require` in an ESM file, or `import` in a CJS file.
+
+For example, consider this file `hello.cts` that uses the `export default` syntax:
+
+```tsx
+// hello.cts
+const hello = () => {
+  console.log("Hello!");
+};
+
+export { hello }; // red squiggly line under export { hello }
+```
+
+When `verbatimModuleSyntax` is enabled, TypeScript will show an error under the `export default` line that tells us we're mixing the syntaxes together:
+
+```tsx
+// hovering over export { hello } shows:
+ESM syntax is not allowed in a CommonJS module when 'verbatimModuleSyntax' is enabled.
+```
+
+In order to fix the issue, we need to use the `export =` syntax instead:
+
+```tsx
+// hello.cts
+
+const hello = () => {
+  console.log("Hello!");
+};
+export = { hello };
+```
+
+This will compile down to `module.exports = { hello }` in the emitted JavaScript.
+
+The warnings will show when trying to use an ESM import as well:
+
+```tsx
+import { z } from "zod"; // rsl under import statement
+
+// hovering over the import shows:
+// ESM syntax is not allowed in a CommonJS module when 'verbatimModuleSyntax' is enabled.
+```
+
+Here, the fix is to use `require` instead of `import`:
+
+```tsx
+import zod = require("zod");
+
+const z = zod.z;
+```
+
+Note that this syntax combines `import` and `require` in a curious way - this is a TypeScript-specific syntax that gives you autocomplete in CommonJS modules.
+
+`verbatimModuleSyntax` is a great way to catch these issues early, and to make sure you're using the right module system in the correct files. It pairs very well with `module: NodeNext`.
+
 ## `noEmit`
 
 The `noEmit` option in `tsconfig.json` tells TypeScript not to emit any JavaScript files when transpiling your TypeScript code.