From c53ed0084638f97755757fe219d292e9d5652dab Mon Sep 17 00:00:00 2001 From: Augustin Mauroy Date: Sun, 28 Jul 2024 21:06:56 +0200 Subject: [PATCH 1/9] content(learn): update ressources about typescript --- apps/site/i18n/locales/en.json | 9 + apps/site/navigation.json | 21 ++ .../getting-started/nodejs-with-typescript.md | 185 ------------------ .../pages/en/learn/typescript/introduction.md | 50 +++++ .../pages/en/learn/typescript/run-natively.md | 54 +++++ apps/site/pages/en/learn/typescript/run.md | 49 +++++ .../pages/en/learn/typescript/transpile.md | 124 ++++++++++++ apps/site/redirects.json | 4 + apps/site/site.json | 10 +- 9 files changed, 316 insertions(+), 190 deletions(-) delete mode 100644 apps/site/pages/en/learn/getting-started/nodejs-with-typescript.md create mode 100644 apps/site/pages/en/learn/typescript/introduction.md create mode 100644 apps/site/pages/en/learn/typescript/run-natively.md create mode 100644 apps/site/pages/en/learn/typescript/run.md create mode 100644 apps/site/pages/en/learn/typescript/transpile.md diff --git a/apps/site/i18n/locales/en.json b/apps/site/i18n/locales/en.json index b2f9ef45f86e..69e56c51f8eb 100644 --- a/apps/site/i18n/locales/en.json +++ b/apps/site/i18n/locales/en.json @@ -42,6 +42,15 @@ "securityBestPractices": "Security Best Practices" } }, + "typescript": { + "links": { + "typescript": "TypeScript", + "introduction": "Introduction to TypeScript", + "transpile": "Running TypeScript code using transpilation", + "run": "Running TypeScript with a runner", + "runNatively": "Running TypeScript with a Node.js Itself" + } + }, "asynchronousWork": { "links": { "asynchronousWork": "Asynchronous Work", diff --git a/apps/site/navigation.json b/apps/site/navigation.json index ea4468a46f6f..e6122e95e48a 100644 --- a/apps/site/navigation.json +++ b/apps/site/navigation.json @@ -185,6 +185,27 @@ } } }, + "typescript": { + "label": "components.navigation.learn.typescript.links.typescript", + "items": { + "introduction": { + "link": "/learn/typescript/introduction", + "label": "components.navigation.learn.typescript.links.introduction" + }, + "transpile": { + "link": "/learn/typescript/transpile", + "label": "components.navigation.learn.typescript.links.transpile" + }, + "run": { + "link": "/learn/typescript/run", + "label": "components.navigation.learn.typescript.links.run" + }, + "runNatively": { + "link": "/learn/typescript/run-natively", + "label": "components.navigation.learn.typescript.links.runNatively" + } + } + }, "asynchronousWork": { "label": "components.navigation.learn.asynchronousWork.links.asynchronousWork", "items": { diff --git a/apps/site/pages/en/learn/getting-started/nodejs-with-typescript.md b/apps/site/pages/en/learn/getting-started/nodejs-with-typescript.md deleted file mode 100644 index a254dca66906..000000000000 --- a/apps/site/pages/en/learn/getting-started/nodejs-with-typescript.md +++ /dev/null @@ -1,185 +0,0 @@ ---- -title: Node.js with TypeScript -layout: learn -authors: sbielenica, ovflowd, vaishnav-mk, AugustinMauroy ---- - -# Node.js with TypeScript - -## What is TypeScript - -**[TypeScript](https://www.typescriptlang.org)** is an open-source language maintained and developed by Microsoft. It's loved and used by a lot of software developers around the world. - -Basically, it's a superset of JavaScript that adds new capabilities to the language. The most notable addition is static type definitions, something that is not present in plain JavaScript. Thanks to types, it's possible, for example, to declare what kind of arguments we are expecting and what is returned exactly in our functions or what's the exact shape of the object that we are creating. TypeScript is a really powerful tool and opens a new world of possibilities in JavaScript projects. It makes our code more secure and robust by preventing many bugs before the code is even shipped - it catches problems during code development and integrates wonderfully with code editors like Visual Studio Code. - -We can talk about other TypeScript benefits later, let's see some examples now! - -### Examples - -Take a look at this code snippet and then we can unpack it together: - -```ts -type User = { - name: string; - age: number; -}; - -function isAdult(user: User): boolean { - return user.age >= 18; -} - -const justine: User = { - name: 'Justine', - age: 23, -}; - -const isJustineAnAdult: boolean = isAdult(justine); -``` - -The first part (with the `type` keyword) is responsible for declaring our custom object type representing users. Later we utilize this newly created type to create function `isAdult` that accepts one argument of type `User` and returns `boolean`. After this, we create `justine`, our example data that can be used for calling the previously defined function. Finally, we create a new variable with information on whether `justine` is an adult. - -There are additional things about this example that you should know. Firstly, if we would not comply with declared types, TypeScript would alarm us that something is wrong and prevent misuse. Secondly, not everything must be typed explicitly - TypeScript is very smart and can deduce types for us. For example, variable `isJustineAnAdult` would be of type `boolean` even if we didn't type it explicitly or `justine` would be valid argument for our function even if we didn't declare this variable as of `User` type. - -Okay, so we have some TypeScript code. Now how do we run it? - -**First thing to do is to install TypeScript in our project:** - -```bash -npm i -D typescript -``` - -Now we can compile it to JavaScript using `tsc` command in the terminal. Let's do it! - -**Assuming that our file is named `example.ts`, the command would look like:** - -```bash -npx tsc example.ts -``` - -> [npx](https://www.npmjs.com/package/npx) here stands for Node Package Execute. This tool allows us to run TypeScript's compiler without installing it globally. - -`tsc` is the TypeScript compiler which will take our TypeScript code and compile it to JavaScript. -This command will result in a new file named `example.js` that we can run using Node.js. -Now when we know how to compile and run TypeScript code let's see TypeScript bug-preventing capabilities in action! - -**This is how we will modify our code:** - -```ts -type User = { - name: string; - age: number; -}; - -function isAdult(user: User): boolean { - return user.age >= 18; -} - -const justine: User = { - name: 'Justine', - age: 'Secret!', -}; - -const isJustineAnAdult: string = isAdult(justine, "I shouldn't be here!"); -``` - -**And this is what TypeScript has to say about this:** - -```console -example.ts:12:5 - error TS2322: Type 'string' is not assignable to type 'number'. - -12 age: 'Secret!', - ~~~ - - example.ts:3:5 - 3 age: number; - ~~~ - The expected type comes from property 'age' which is declared here on type 'User' - -example.ts:15:7 - error TS2322: Type 'boolean' is not assignable to type 'string'. - -15 const isJustineAnAdult: string = isAdult(justine, "I shouldn't be here!"); - ~~~~~~~~~~~~~~~~ - -example.ts:15:51 - error TS2554: Expected 1 arguments, but got 2. - -15 const isJustineAnAdult: string = isAdult(justine, "I shouldn't be here!"); - ~~~~~~~~~~~~~~~~~~~~~~ - - -Found 3 errors in the same file, starting at: example.ts:12 -``` - -As you can see TypeScript successfully prevents us from shipping code that could work unexpectedly. That's wonderful! - -## More about TypeScript - -TypeScript offers a whole lot of other great mechanisms like interfaces, classes, utility types and so on. Also, on bigger projects you can declare your TypeScript compiler configuration in a separate file and granularly adjust how it works, how strict it is and where it stores compiled files for example. You can read more about all this awesome stuff in [the official TypeScript docs](https://www.typescriptlang.org/docs). - -Some of the other benefits of TypeScript that are worth mentioning are that it can be adopted progressively, it helps making code more readable and understandable and it allows developers to use modern language features while shipping code for older Node.js versions. - -## Running TypeScript Code in Node.js - -Node.js cannot run TypeScript natively. You cannot call `node example.ts` from the command line directly. But there are three solutions to this problem: - -### Compiling TypeScript to JavaScript - -If you want to run TypeScript code in Node.js, you need to compile it to JavaScript first. You can do this using the TypeScript compiler `tsc` as shown earlier. - -Here's a small example: - -```bash -npx tsc example.ts -node example.js -``` - -### Running TypeScript Code with `ts-node` - -You can use [ts-node](https://typestrong.org/ts-node/) to run TypeScript code directly in Node.js without the need to compile it first. But it's not typechecking your code. So we recommend to type check your code first with `tsc` and then run it with `ts-node` before shipping it. - -To use `ts-node`, you need to install it first: - -```bash -npm i -D ts-node -``` - -Then you can run your TypeScript code like this: - -```bash -npx ts-node example.ts -``` - -### Running TypeScript Code with `tsx` - -You can use [tsx](https://tsx.is/) to run TypeScript code directly in Node.js without the need to compile it first. But it's not typechecking your code. So we recommend to type check your code first with `tsc` and then run it with `tsx` before shipping it. - -To use `tsx`, you need to install it first: - -```bash -npm i -D tsx -``` - -Then you can run your TypeScript code like this: - -```bash -npx tsx example.ts -``` - -If you want to use `tsx` via `node`, you can register `tsx` via `--import`: - -```bash -node --import=tsx example.ts -``` - -## TypeScript in the Node.js world - -TypeScript is well-established in the Node.js world and used by many companies, open-source projects, tools and frameworks. -Some of the notable examples of open-source projects using TypeScript are: - -- [NestJS](https://nestjs.com/) - robust and fully-featured framework that makes creating scalable and well-architected systems easy and pleasant -- [TypeORM](https://typeorm.io/#/) - great ORM influenced by other well-known tools from other languages like Hibernate, Doctrine or Entity Framework -- [Prisma](https://prisma.io/) - next-generation ORM featuring a declarative data model, generated migrations and fully type-safe database queries -- [RxJS](https://rxjs.dev/) - widely used library for reactive programming -- [AdonisJS](https://adonisjs.com) - A fully featured web framework with Node.js -- [FoalTs](https://foalts.org/) - The Elegant Nodejs Framework - -And many, many more great projects... Maybe even your next one! diff --git a/apps/site/pages/en/learn/typescript/introduction.md b/apps/site/pages/en/learn/typescript/introduction.md new file mode 100644 index 000000000000..60ce4e2f25d9 --- /dev/null +++ b/apps/site/pages/en/learn/typescript/introduction.md @@ -0,0 +1,50 @@ +--- +title: Introduction to TypeScript +layout: learn +authors: sbielenica, ovflowd, vaishnav-mk, AugustinMauroy +--- + +# Introduction to TypeScript + +## What is TypeScript + +**[TypeScript](https://www.typescriptlang.org)** is an open-source language maintained and developed by Microsoft. It's loved and used by a lot of software developers around the world. + +Basically, it's a superset of JavaScript that adds new capabilities to the language. The most notable addition is static type definitions, something that is not present in plain JavaScript. Thanks to types, it's possible, for example, to declare what kind of arguments we are expecting and what is returned exactly in our functions or what's the exact shape of the object that we are creating. TypeScript is a really powerful tool and opens a new world of possibilities in JavaScript projects. It makes our code more secure and robust by preventing many bugs before the code is even shipped - it catches problems during code development and integrates wonderfully with code editors like Visual Studio Code. + +We can talk about other TypeScript benefits later, let's see some examples now! + +## First TypeScript code + +Take a look at this code snippet and then we can unpack it together: + + + +```ts +type User = { + name: string; + age: number; +}; + +function isAdult(user: User): boolean { + return user.age >= 18; +} + +const justine: User = { + name: 'Justine', + age: 23, +}; + +const isJustineAnAdult: boolean = isAdult(justine); +``` + +The first part (with the `type` keyword) is responsible for declaring our custom object type representing users. Later we utilize this newly created type to create function `isAdult` that accepts one argument of type `User` and returns `boolean`. After this, we create `justine`, our example data that can be used for calling the previously defined function. Finally, we create a new variable with information on whether `justine` is an adult. + +There are additional things about this example that you should know. Firstly, if we would not comply with declared types, TypeScript would alarm us that something is wrong and prevent misuse. Secondly, not everything must be typed explicitly - TypeScript is very smart and can deduce types for us. For example, variable `isJustineAnAdult` would be of type `boolean` even if we didn't type it explicitly or `justine` would be valid argument for our function even if we didn't declare this variable as of `User` type. + +## How to run TypeScript code + +Okay, so we have some TypeScript code. Now how do we run it? +There are few possible ways to run TypeScript code, we will cover all of them in the next articles. diff --git a/apps/site/pages/en/learn/typescript/run-natively.md b/apps/site/pages/en/learn/typescript/run-natively.md new file mode 100644 index 000000000000..98ad855bb7df --- /dev/null +++ b/apps/site/pages/en/learn/typescript/run-natively.md @@ -0,0 +1,54 @@ +--- +title: Running TypeScript with a Node.js Itself +layout: learn +authors: AugustinMauroy +--- + +> **⚠️WARNING:** All content in this article uses Node.js experimental features. Please make sure you are using a version of Node.js that supports the features mentioned in this article. And remember that experimental features can change on future versions of Node.js. + +# Running TypeScript with a Node.js Itself + +In the previous articles, we learned how to run TypeScript code using transpilation and with a runner. In this article, we will learn how to run TypeScript code using Node.js itself. + +## Running TypeScript code with Node.js + +Node.js has experimental support for TypeScript. You can run TypeScript code directly in Node.js without the need to compile it first. + +So how do you run TypeScript code with Node.js? + +First, you need to install a nightly version of Node.js. You can download it from the [official Node.js website](https://nodejs.org/download/nightly/). + +Then, you can run your TypeScript code like this: + +```bash +node --experimental-strip-types example.ts +``` + +The `--experimental-strip-types` flag tells Node.js to strip the type annotations from the TypeScript code before running it. + +And that's it! You can now run TypeScript code directly in Node.js without the need to compile it first. +In the future we all hope that this feature will be stable and available in the LTS version of Node.js, so that we can all enjoy it without any additional steps. + +## Limitations + +At the time of writing, the experimental support for TypeScript in Node.js has some limitations. To allow typescript to run in node.js, our collaborators have chosen to only strip types from the code. + + + +Since Node.js is only removing inline types, any TypeScript features that +involve _replacing_ TypeScript syntax with new JavaScript syntax will error. +This is by design. To run TypeScript with such features, see +[Full TypeScript support][]. + +The most prominent unsupported features that require transformation are: + +- `Enum` +- `experimentalDecorators` +- `namespaces` +- parameter properties + +In addition, Node.js does not read `tsconfig.json` files and does not support +features that depend on settings within `tsconfig.json`, such as paths or +converting newer JavaScript syntax into older standards. diff --git a/apps/site/pages/en/learn/typescript/run.md b/apps/site/pages/en/learn/typescript/run.md new file mode 100644 index 000000000000..ca85adceacbb --- /dev/null +++ b/apps/site/pages/en/learn/typescript/run.md @@ -0,0 +1,49 @@ +--- +title: Running TypeScript with a runner +layout: learn +authors: AugustinMauroy +--- + +# Running TypeScript with a runner + +In the previous article, we learned how to run TypeScript code using transpilation. In this article, we will learn how to run TypeScript code using a runner. + +## Running TypeScript code with `ts-node` + +[ts-node](https://typestrong.org/ts-node/) is a TypeScript execution environment for node.js. It allows you to run TypeScript code directly in node.js without the need to compile it first. But it's not typechecking your code. So we recommend to type check your code first with `tsc` and then run it with `ts-node` before shipping it. + +To use `ts-node`, you need to install it first: + +```bash +npm i -D ts-node +``` + +Then you can run your TypeScript code like this: + +```bash +npx ts-node example.ts +``` + +## Running TypeScript code with `tsx` + +[tsx](https://tsx.is/) is another TypeScript execution environment for node.js. It allows you to run TypeScript code directly in node.js without the need to compile it first. But it's not typechecking your code. So we recommend to type check your code first with `tsc` and then run it with `tsx` before shipping it. + +To use `tsx`, you need to install it first: + +```bash +npm i -D tsx +``` + +Then you can run your TypeScript code like this: + +```bash +npx tsx example.ts +``` + +### Registering `tsx` via `node` + +If you want to use `tsx` via `node`, you can register `tsx` via `--import`: + +```bash +node --import=tsx example.ts +``` diff --git a/apps/site/pages/en/learn/typescript/transpile.md b/apps/site/pages/en/learn/typescript/transpile.md new file mode 100644 index 000000000000..0b629a2ec5a1 --- /dev/null +++ b/apps/site/pages/en/learn/typescript/transpile.md @@ -0,0 +1,124 @@ +--- +title: Running TypeScript code using transpilation +layout: learn +authors: AugustinMauroy +--- + +# Running TypeScript code using transpilation + +Transpilation is the process of converting source code from one language to another. In the case of TypeScript, it's the process of converting TypeScript code to JavaScript code. This is necessary because browsers and Node.js can't run TypeScript code directly. + +## Compiling TypeScript to JavaScript + +The most common way to run TypeScript code is to compile it to JavaScript first. You can do this using the TypeScript compiler `tsc`. + +**Step 1:** Write your TypeScript code in a file, for example `example.ts`. + + + +```ts +type User = { + name: string; + age: number; +}; + +function isAdult(user: User): boolean { + return user.age >= 18; +} + +const justine: User = { + name: 'Justine', + age: 23, +}; + +const isJustineAnAdult: boolean = isAdult(justine); +``` + +**Step 2:** Install TypeScript globally using npm: + +If you want to discover npm, you can check our [our introduction to the npm package manager](/learn/getting-started/an-introduction-to-the-npm-package-manager) + +There are two ways to install TypeScript, globally or locally. We recommend installing it globally for the sake of simplicity. + +```bash displayName="Install TypeScript globally" +npm i -g typescript # -g is a shorthand for --global +``` + +```bash displayName="Install TypeScript locally" +npm i -D typescript # -D is a shorthand for --save-dev +``` + +**Step 3:** Compile your TypeScript code to JavaScript using the `tsc` command: + +```bash +tsc example.ts +``` + +> **NOTE:** You can also use `npx tsc example.ts` if you don't want to install TypeScript globally. [npx](https://www.npmjs.com/package/npx) is a tool that allows you to run Node.js packages without installing them globally. + +`tsc` is the TypeScript compiler which will take our TypeScript code and compile it to JavaScript. +This command will result in a new file named `example.js` that we can run using Node.js. +Now when we know how to compile and run TypeScript code let's see TypeScript bug-preventing capabilities in action! + +**Step 4:** Run your JavaScript code using Node.js: + +```bash +node example.js +``` + +You should see the output of your TypeScript code in the terminal + +## If there are type errors + +If you have type errors in your TypeScript code, the TypeScript compiler will catch them and prevent you from running the code. For example, if you change the `age` property of `justine` to a string, TypeScript will throw an error: + +We will modify our code like this, to voluntarily introduce a type error: + +```ts +type User = { + name: string; + age: number; +}; + +function isAdult(user: User): boolean { + return user.age >= 18; +} + +const justine: User = { + name: 'Justine', + age: 'Secret!', +}; + +const isJustineAnAdult: string = isAdult(justine, "I shouldn't be here!"); +``` + +And this is what TypeScript has to say about this: + +```console +example.ts:12:5 - error TS2322: Type 'string' is not assignable to type 'number'. + +12 age: 'Secret!', + ~~~ + + example.ts:3:5 + 3 age: number; + ~~~ + The expected type comes from property 'age' which is declared here on type 'User' + +example.ts:15:7 - error TS2322: Type 'boolean' is not assignable to type 'string'. + +15 const isJustineAnAdult: string = isAdult(justine, "I shouldn't be here!"); + ~~~~~~~~~~~~~~~~ + +example.ts:15:51 - error TS2554: Expected 1 arguments, but got 2. + +15 const isJustineAnAdult: string = isAdult(justine, "I shouldn't be here!"); + ~~~~~~~~~~~~~~~~~~~~~~ + + +Found 3 errors in the same file, starting at: example.ts:12 +``` + +As you can see, TypeScript is very helpful in catching bugs before they even happen. This is one of the reasons why TypeScript is so popular among developers. diff --git a/apps/site/redirects.json b/apps/site/redirects.json index 8889da2b0973..3330d180f8e7 100644 --- a/apps/site/redirects.json +++ b/apps/site/redirects.json @@ -283,6 +283,10 @@ { "source": "/:locale/download/current", "destination": "/:locale/download/package-manager/current" + }, + { + "source": "/:locale/learn/getting-started/nodejs-with-typescript", + "destination": "/:locale/learn/typescript/introduction" } ], "internal": [] diff --git a/apps/site/site.json b/apps/site/site.json index 3ed40c4e5e87..64057bd08d18 100644 --- a/apps/site/site.json +++ b/apps/site/site.json @@ -37,12 +37,12 @@ }, "websiteBadges": { "index": { - "startDate": "2024-04-24T00:00:00.000Z", - "endDate": "2024-05-24T00:00:00.000Z", + "startDate": "2024-07-01T00:00:00.000Z", + "endDate": "2024-08-01T00:00:00.000Z", "kind": "default", - "title": "Survey", - "text": "Help us shape the next 10 years of Node.js", - "link": "https://linuxfoundation.surveymonkey.com/r/nodenext10survey24" + "title": "Discover", + "text": "TypeScript in Node.js", + "link": "https://nodejs.org/en/learn/typescript/introduction/" } } } From dfe4e40faf2c5af50d1437e936e9a566fb0eb3a6 Mon Sep 17 00:00:00 2001 From: Augustin Mauroy Date: Sun, 28 Jul 2024 21:14:55 +0200 Subject: [PATCH 2/9] adding important note --- apps/site/pages/en/learn/typescript/run-natively.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/apps/site/pages/en/learn/typescript/run-natively.md b/apps/site/pages/en/learn/typescript/run-natively.md index 98ad855bb7df..876218a4cafe 100644 --- a/apps/site/pages/en/learn/typescript/run-natively.md +++ b/apps/site/pages/en/learn/typescript/run-natively.md @@ -52,3 +52,9 @@ The most prominent unsupported features that require transformation are: In addition, Node.js does not read `tsconfig.json` files and does not support features that depend on settings within `tsconfig.json`, such as paths or converting newer JavaScript syntax into older standards. + +## Important notes + +Thanks to all the contributors who have made this feature possible. We hope that this feature will be stable and available in the LTS version of Node.js soon. + +We can understand that this feature is experimental and has some limitations, and this may disappoint you. So please be patient and wait for the stable version of this feature. And **NEVER** spam us. If you are happy, you can share these articles on social media and tell your friends about this feature. From 215a5c75330911b7eb75ad2e96c1463929044e30 Mon Sep 17 00:00:00 2001 From: Augustin Mauroy Date: Tue, 30 Jul 2024 10:47:50 +0200 Subject: [PATCH 3/9] content(learn): update from feedback Co-Authored-By: Antoine du Hamel --- apps/site/pages/en/learn/typescript/introduction.md | 8 ++++---- apps/site/pages/en/learn/typescript/run-natively.md | 10 +++++----- apps/site/pages/en/learn/typescript/transpile.md | 6 +++--- 3 files changed, 12 insertions(+), 12 deletions(-) diff --git a/apps/site/pages/en/learn/typescript/introduction.md b/apps/site/pages/en/learn/typescript/introduction.md index 60ce4e2f25d9..0b469d774af1 100644 --- a/apps/site/pages/en/learn/typescript/introduction.md +++ b/apps/site/pages/en/learn/typescript/introduction.md @@ -32,17 +32,17 @@ function isAdult(user: User): boolean { return user.age >= 18; } -const justine: User = { +const justine = { name: 'Justine', age: 23, -}; +} satisfies User; -const isJustineAnAdult: boolean = isAdult(justine); +const isJustineAnAdult = isAdult(justine); ``` The first part (with the `type` keyword) is responsible for declaring our custom object type representing users. Later we utilize this newly created type to create function `isAdult` that accepts one argument of type `User` and returns `boolean`. After this, we create `justine`, our example data that can be used for calling the previously defined function. Finally, we create a new variable with information on whether `justine` is an adult. -There are additional things about this example that you should know. Firstly, if we would not comply with declared types, TypeScript would alarm us that something is wrong and prevent misuse. Secondly, not everything must be typed explicitly - TypeScript is very smart and can deduce types for us. For example, variable `isJustineAnAdult` would be of type `boolean` even if we didn't type it explicitly or `justine` would be valid argument for our function even if we didn't declare this variable as of `User` type. +There are additional things about this example that you should know. Firstly, if we would not comply with declared types, TypeScript would alarm us that something is wrong and prevent misuse. Secondly, not everything must be typed explicitly - TypeScript is very smart and can infer types for us. For example, variable `isJustineAnAdult` is of type `boolean` even if we didn't type it explicitly or `justine` would be valid argument for our function even though we didn't declare this variable as of `User` type. ## How to run TypeScript code diff --git a/apps/site/pages/en/learn/typescript/run-natively.md b/apps/site/pages/en/learn/typescript/run-natively.md index 876218a4cafe..8c9c776138c6 100644 --- a/apps/site/pages/en/learn/typescript/run-natively.md +++ b/apps/site/pages/en/learn/typescript/run-natively.md @@ -12,13 +12,13 @@ In the previous articles, we learned how to run TypeScript code using transpilat ## Running TypeScript code with Node.js -Node.js has experimental support for TypeScript. You can run TypeScript code directly in Node.js without the need to compile it first. +Node.js has experimental support for some TypeScript syntax. You can write code that's valid TypeScript directly in Node.js without the need to transpile it first. -So how do you run TypeScript code with Node.js? +So how do you run typed JavaScript code with Node.js? First, you need to install a nightly version of Node.js. You can download it from the [official Node.js website](https://nodejs.org/download/nightly/). -Then, you can run your TypeScript code like this: +Then, you can run your file like this: ```bash node --experimental-strip-types example.ts @@ -26,7 +26,7 @@ node --experimental-strip-types example.ts The `--experimental-strip-types` flag tells Node.js to strip the type annotations from the TypeScript code before running it. -And that's it! You can now run TypeScript code directly in Node.js without the need to compile it first. +And that's it! You can now run typed JavaScript code directly in Node.js without the need to transpile it first, and use TypeScript to catch type-related errors. In the future we all hope that this feature will be stable and available in the LTS version of Node.js, so that we can all enjoy it without any additional steps. ## Limitations @@ -57,4 +57,4 @@ converting newer JavaScript syntax into older standards. Thanks to all the contributors who have made this feature possible. We hope that this feature will be stable and available in the LTS version of Node.js soon. -We can understand that this feature is experimental and has some limitations, and this may disappoint you. So please be patient and wait for the stable version of this feature. And **NEVER** spam us. If you are happy, you can share these articles on social media and tell your friends about this feature. +We can understand that this feature is experimental and has some limitations; if that doesn't suit your usecase, please use something else, or contribute a fix. Bug reports are also welcome, please keep in mind the project is run by volunteers, without warranty of any kind, so please be patient if you can't contribute the fix yourself. diff --git a/apps/site/pages/en/learn/typescript/transpile.md b/apps/site/pages/en/learn/typescript/transpile.md index 0b629a2ec5a1..3452fb5de0a3 100644 --- a/apps/site/pages/en/learn/typescript/transpile.md +++ b/apps/site/pages/en/learn/typescript/transpile.md @@ -36,11 +36,11 @@ const justine: User = { const isJustineAnAdult: boolean = isAdult(justine); ``` -**Step 2:** Install TypeScript globally using npm: +**Step 2:** Install TypeScript globally using a package manager: -If you want to discover npm, you can check our [our introduction to the npm package manager](/learn/getting-started/an-introduction-to-the-npm-package-manager) +In this example we're going to use npm, you can check our [our introduction to the npm package manager](/learn/getting-started/an-introduction-to-the-npm-package-manager) for more information. -There are two ways to install TypeScript, globally or locally. We recommend installing it globally for the sake of simplicity. +There are two ways to install TypeScript, globally or locally. We do not recommend installing it globally for the sake of everyone working with you. ```bash displayName="Install TypeScript globally" npm i -g typescript # -g is a shorthand for --global From 96bd205cc188c6906c366446cdc69d8168b7ff99 Mon Sep 17 00:00:00 2001 From: Augustin Mauroy Date: Tue, 30 Jul 2024 11:00:20 +0200 Subject: [PATCH 4/9] content(learn): remove global install of tsc --- .../pages/en/learn/typescript/transpile.md | 24 +++++++++---------- 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/apps/site/pages/en/learn/typescript/transpile.md b/apps/site/pages/en/learn/typescript/transpile.md index 3452fb5de0a3..d1101f9931d1 100644 --- a/apps/site/pages/en/learn/typescript/transpile.md +++ b/apps/site/pages/en/learn/typescript/transpile.md @@ -1,3 +1,4 @@ +````md --- title: Running TypeScript code using transpilation layout: learn @@ -28,24 +29,19 @@ function isAdult(user: User): boolean { return user.age >= 18; } -const justine: User = { +const justine = { name: 'Justine', age: 23, -}; +} satisfies User; -const isJustineAnAdult: boolean = isAdult(justine); +const isJustineAnAdult = isAdult(justine); ``` +```` -**Step 2:** Install TypeScript globally using a package manager: +**Step 2:** Install TypeScript locally using a package manager: In this example we're going to use npm, you can check our [our introduction to the npm package manager](/learn/getting-started/an-introduction-to-the-npm-package-manager) for more information. -There are two ways to install TypeScript, globally or locally. We do not recommend installing it globally for the sake of everyone working with you. - -```bash displayName="Install TypeScript globally" -npm i -g typescript # -g is a shorthand for --global -``` - ```bash displayName="Install TypeScript locally" npm i -D typescript # -D is a shorthand for --save-dev ``` @@ -53,10 +49,10 @@ npm i -D typescript # -D is a shorthand for --save-dev **Step 3:** Compile your TypeScript code to JavaScript using the `tsc` command: ```bash -tsc example.ts +npx tsc example.ts ``` -> **NOTE:** You can also use `npx tsc example.ts` if you don't want to install TypeScript globally. [npx](https://www.npmjs.com/package/npx) is a tool that allows you to run Node.js packages without installing them globally. +> **NOTE:** `npx` is a tool that allows you to run Node.js packages without installing them globally. `tsc` is the TypeScript compiler which will take our TypeScript code and compile it to JavaScript. This command will result in a new file named `example.js` that we can run using Node.js. @@ -122,3 +118,7 @@ Found 3 errors in the same file, starting at: example.ts:12 ``` As you can see, TypeScript is very helpful in catching bugs before they even happen. This is one of the reasons why TypeScript is so popular among developers. + +``` + +``` From 3a90cdba796506913e3743da7fc3fef3711c1b8a Mon Sep 17 00:00:00 2001 From: Augustin Mauroy Date: Tue, 30 Jul 2024 11:16:41 +0200 Subject: [PATCH 5/9] fix fails from github copilot fix fails from github copilot --- apps/site/pages/en/learn/typescript/transpile.md | 6 ------ 1 file changed, 6 deletions(-) diff --git a/apps/site/pages/en/learn/typescript/transpile.md b/apps/site/pages/en/learn/typescript/transpile.md index d1101f9931d1..62c042d4e902 100644 --- a/apps/site/pages/en/learn/typescript/transpile.md +++ b/apps/site/pages/en/learn/typescript/transpile.md @@ -1,4 +1,3 @@ -````md --- title: Running TypeScript code using transpilation layout: learn @@ -36,7 +35,6 @@ const justine = { const isJustineAnAdult = isAdult(justine); ``` -```` **Step 2:** Install TypeScript locally using a package manager: @@ -118,7 +116,3 @@ Found 3 errors in the same file, starting at: example.ts:12 ``` As you can see, TypeScript is very helpful in catching bugs before they even happen. This is one of the reasons why TypeScript is so popular among developers. - -``` - -``` From 9e74f30d185a6e96cc99e1f09e1478c395482c07 Mon Sep 17 00:00:00 2001 From: Augustin Mauroy Date: Tue, 30 Jul 2024 11:32:26 +0200 Subject: [PATCH 6/9] fix: remove old stuff from navigation --- apps/site/i18n/locales/en.json | 1 - apps/site/navigation.json | 4 ---- 2 files changed, 5 deletions(-) diff --git a/apps/site/i18n/locales/en.json b/apps/site/i18n/locales/en.json index 69e56c51f8eb..10247d8accc8 100644 --- a/apps/site/i18n/locales/en.json +++ b/apps/site/i18n/locales/en.json @@ -35,7 +35,6 @@ "anIntroductionToTheNpmPackageManager": "An introduction to the npm package manager", "ecmascript2015Es6AndBeyond": "ECMAScript 2015 (ES6) and beyond", "nodejsTheDifferenceBetweenDevelopmentAndProduction": "Node.js, the difference between development and production", - "nodejsWithTypescript": "Node.js with TypeScript", "nodejsWithWebassembly": "Node.js with WebAssembly", "debugging": "Debugging Node.js", "profiling": "Profiling Node.js Applications", diff --git a/apps/site/navigation.json b/apps/site/navigation.json index e6122e95e48a..167dade56903 100644 --- a/apps/site/navigation.json +++ b/apps/site/navigation.json @@ -163,10 +163,6 @@ "link": "/learn/getting-started/nodejs-the-difference-between-development-and-production", "label": "components.navigation.learn.gettingStarted.links.nodejsTheDifferenceBetweenDevelopmentAndProduction" }, - "nodejsWithTypescript": { - "link": "/learn/getting-started/nodejs-with-typescript", - "label": "components.navigation.learn.gettingStarted.links.nodejsWithTypescript" - }, "nodejsWithWebassembly": { "link": "/learn/getting-started/nodejs-with-webassembly", "label": "components.navigation.learn.gettingStarted.links.nodejsWithWebassembly" From b6bcd4038280ae11bf30033fb9e9b94a74f1520d Mon Sep 17 00:00:00 2001 From: Augustin Mauroy Date: Fri, 9 Aug 2024 11:36:55 +0200 Subject: [PATCH 7/9] update --- .../pages/en/learn/typescript/run-natively.md | 30 +++---------------- apps/site/site.json | 4 +-- 2 files changed, 6 insertions(+), 28 deletions(-) diff --git a/apps/site/pages/en/learn/typescript/run-natively.md b/apps/site/pages/en/learn/typescript/run-natively.md index 8c9c776138c6..580d4d8ca9b7 100644 --- a/apps/site/pages/en/learn/typescript/run-natively.md +++ b/apps/site/pages/en/learn/typescript/run-natively.md @@ -4,7 +4,7 @@ layout: learn authors: AugustinMauroy --- -> **⚠️WARNING:** All content in this article uses Node.js experimental features. Please make sure you are using a version of Node.js that supports the features mentioned in this article. And remember that experimental features can change on future versions of Node.js. +> **⚠️WARNING⚠️:** All content in this article uses Node.js experimental features. Please make sure you are using a version of Node.js that supports the features mentioned in this article. And remember that experimental features can change on future versions of Node.js. # Running TypeScript with a Node.js Itself @@ -12,14 +12,10 @@ In the previous articles, we learned how to run TypeScript code using transpilat ## Running TypeScript code with Node.js -Node.js has experimental support for some TypeScript syntax. You can write code that's valid TypeScript directly in Node.js without the need to transpile it first. +Since V22.6.0, Node.js has experimental support for some TypeScript syntax. You can write code that's valid TypeScript directly in Node.js without the need to transpile it first. So how do you run typed JavaScript code with Node.js? -First, you need to install a nightly version of Node.js. You can download it from the [official Node.js website](https://nodejs.org/download/nightly/). - -Then, you can run your file like this: - ```bash node --experimental-strip-types example.ts ``` @@ -33,28 +29,10 @@ In the future we all hope that this feature will be stable and available in the At the time of writing, the experimental support for TypeScript in Node.js has some limitations. To allow typescript to run in node.js, our collaborators have chosen to only strip types from the code. - - -Since Node.js is only removing inline types, any TypeScript features that -involve _replacing_ TypeScript syntax with new JavaScript syntax will error. -This is by design. To run TypeScript with such features, see -[Full TypeScript support][]. - -The most prominent unsupported features that require transformation are: - -- `Enum` -- `experimentalDecorators` -- `namespaces` -- parameter properties - -In addition, Node.js does not read `tsconfig.json` files and does not support -features that depend on settings within `tsconfig.json`, such as paths or -converting newer JavaScript syntax into older standards. +You can get more information on the [api docs](https://nodejs.org/docs/latest/api/typescript.html#unsupported-typescript-features) ## Important notes Thanks to all the contributors who have made this feature possible. We hope that this feature will be stable and available in the LTS version of Node.js soon. -We can understand that this feature is experimental and has some limitations; if that doesn't suit your usecase, please use something else, or contribute a fix. Bug reports are also welcome, please keep in mind the project is run by volunteers, without warranty of any kind, so please be patient if you can't contribute the fix yourself. +We can understand that this feature is experimental and has some limitations; if that doesn't suit your use-case, please use something else, or contribute a fix. Bug reports are also welcome, please keep in mind the project is run by volunteers, without warranty of any kind, so please be patient if you can't contribute the fix yourself. diff --git a/apps/site/site.json b/apps/site/site.json index 64057bd08d18..25e65f13da35 100644 --- a/apps/site/site.json +++ b/apps/site/site.json @@ -37,8 +37,8 @@ }, "websiteBadges": { "index": { - "startDate": "2024-07-01T00:00:00.000Z", - "endDate": "2024-08-01T00:00:00.000Z", + "startDate": "2024-08-01T00:00:00.000Z", + "endDate": "2024-09-01T00:00:00.000Z", "kind": "default", "title": "Discover", "text": "TypeScript in Node.js", From 461bbd51792bed5d2b39ce5b71d0335a572b7eec Mon Sep 17 00:00:00 2001 From: Augustin Mauroy <97875033+AugustinMauroy@users.noreply.github.com> Date: Thu, 12 Sep 2024 14:28:08 +0200 Subject: [PATCH 8/9] update --- apps/site/i18n/locales/en.json | 2 +- apps/site/pages/en/learn/typescript/introduction.md | 2 +- apps/site/pages/en/learn/typescript/run-natively.md | 4 ++-- apps/site/site.json | 4 ++-- 4 files changed, 6 insertions(+), 6 deletions(-) diff --git a/apps/site/i18n/locales/en.json b/apps/site/i18n/locales/en.json index 10247d8accc8..d5e45cac7052 100644 --- a/apps/site/i18n/locales/en.json +++ b/apps/site/i18n/locales/en.json @@ -47,7 +47,7 @@ "introduction": "Introduction to TypeScript", "transpile": "Running TypeScript code using transpilation", "run": "Running TypeScript with a runner", - "runNatively": "Running TypeScript with a Node.js Itself" + "runNatively": "Running TypeScript Natively" } }, "asynchronousWork": { diff --git a/apps/site/pages/en/learn/typescript/introduction.md b/apps/site/pages/en/learn/typescript/introduction.md index 0b469d774af1..9fc76ce3d519 100644 --- a/apps/site/pages/en/learn/typescript/introduction.md +++ b/apps/site/pages/en/learn/typescript/introduction.md @@ -10,7 +10,7 @@ authors: sbielenica, ovflowd, vaishnav-mk, AugustinMauroy **[TypeScript](https://www.typescriptlang.org)** is an open-source language maintained and developed by Microsoft. It's loved and used by a lot of software developers around the world. -Basically, it's a superset of JavaScript that adds new capabilities to the language. The most notable addition is static type definitions, something that is not present in plain JavaScript. Thanks to types, it's possible, for example, to declare what kind of arguments we are expecting and what is returned exactly in our functions or what's the exact shape of the object that we are creating. TypeScript is a really powerful tool and opens a new world of possibilities in JavaScript projects. It makes our code more secure and robust by preventing many bugs before the code is even shipped - it catches problems during code development and integrates wonderfully with code editors like Visual Studio Code. +Basically, TypeScript add adds additional syntax to JavaScript to support a tighter integration with your editor. Catch errors early in your editor or in your CI/CD pipeline, and write more maintainable code. We can talk about other TypeScript benefits later, let's see some examples now! diff --git a/apps/site/pages/en/learn/typescript/run-natively.md b/apps/site/pages/en/learn/typescript/run-natively.md index 580d4d8ca9b7..7b0cffba56a4 100644 --- a/apps/site/pages/en/learn/typescript/run-natively.md +++ b/apps/site/pages/en/learn/typescript/run-natively.md @@ -1,12 +1,12 @@ --- -title: Running TypeScript with a Node.js Itself +title: Running TypeScript Natively layout: learn authors: AugustinMauroy --- > **⚠️WARNING⚠️:** All content in this article uses Node.js experimental features. Please make sure you are using a version of Node.js that supports the features mentioned in this article. And remember that experimental features can change on future versions of Node.js. -# Running TypeScript with a Node.js Itself +# Running TypeScript Natively In the previous articles, we learned how to run TypeScript code using transpilation and with a runner. In this article, we will learn how to run TypeScript code using Node.js itself. diff --git a/apps/site/site.json b/apps/site/site.json index 25e65f13da35..375fb3598ed9 100644 --- a/apps/site/site.json +++ b/apps/site/site.json @@ -37,8 +37,8 @@ }, "websiteBadges": { "index": { - "startDate": "2024-08-01T00:00:00.000Z", - "endDate": "2024-09-01T00:00:00.000Z", + "startDate": "2024-09-01T00:00:00.000Z", + "endDate": "2024-10-01T00:00:00.000Z", "kind": "default", "title": "Discover", "text": "TypeScript in Node.js", From 43f5c59038c88b87d738c6776fc426e862fc5fc3 Mon Sep 17 00:00:00 2001 From: Augustin Mauroy Date: Sat, 14 Sep 2024 14:58:21 +0200 Subject: [PATCH 9/9] Update from feedback Co-Authored-By: Brian Muenzenmeyer --- apps/site/pages/en/learn/typescript/introduction.md | 6 +++--- apps/site/pages/en/learn/typescript/run-natively.md | 12 ++++++------ apps/site/pages/en/learn/typescript/run.md | 4 ++-- 3 files changed, 11 insertions(+), 11 deletions(-) diff --git a/apps/site/pages/en/learn/typescript/introduction.md b/apps/site/pages/en/learn/typescript/introduction.md index 9fc76ce3d519..4cd976f2fb58 100644 --- a/apps/site/pages/en/learn/typescript/introduction.md +++ b/apps/site/pages/en/learn/typescript/introduction.md @@ -8,9 +8,9 @@ authors: sbielenica, ovflowd, vaishnav-mk, AugustinMauroy ## What is TypeScript -**[TypeScript](https://www.typescriptlang.org)** is an open-source language maintained and developed by Microsoft. It's loved and used by a lot of software developers around the world. +**[TypeScript](https://www.typescriptlang.org)** is an open-source language maintained and developed by Microsoft. -Basically, TypeScript add adds additional syntax to JavaScript to support a tighter integration with your editor. Catch errors early in your editor or in your CI/CD pipeline, and write more maintainable code. +Basically, TypeScript adds additional syntax to JavaScript to support a tighter integration with your editor. Catch errors early in your editor or in your CI/CD pipeline, and write more maintainable code. We can talk about other TypeScript benefits later, let's see some examples now! @@ -42,7 +42,7 @@ const isJustineAnAdult = isAdult(justine); The first part (with the `type` keyword) is responsible for declaring our custom object type representing users. Later we utilize this newly created type to create function `isAdult` that accepts one argument of type `User` and returns `boolean`. After this, we create `justine`, our example data that can be used for calling the previously defined function. Finally, we create a new variable with information on whether `justine` is an adult. -There are additional things about this example that you should know. Firstly, if we would not comply with declared types, TypeScript would alarm us that something is wrong and prevent misuse. Secondly, not everything must be typed explicitly - TypeScript is very smart and can infer types for us. For example, variable `isJustineAnAdult` is of type `boolean` even if we didn't type it explicitly or `justine` would be valid argument for our function even though we didn't declare this variable as of `User` type. +There are additional things about this example that you should know. Firstly, if we do not comply with the declared types, TypeScript will inform us that something is wrong and prevent misuse. Secondly, not everything must be typed explicitly—TypeScript infers types for us. For example, the variable `isJustineAnAdult` is of type `boolean` even if we didn't type it explicitly, and `justine` would be a valid argument for our function even though we didn't declare this variable as of `User` type. ## How to run TypeScript code diff --git a/apps/site/pages/en/learn/typescript/run-natively.md b/apps/site/pages/en/learn/typescript/run-natively.md index 7b0cffba56a4..6a101ad17601 100644 --- a/apps/site/pages/en/learn/typescript/run-natively.md +++ b/apps/site/pages/en/learn/typescript/run-natively.md @@ -4,7 +4,7 @@ layout: learn authors: AugustinMauroy --- -> **⚠️WARNING⚠️:** All content in this article uses Node.js experimental features. Please make sure you are using a version of Node.js that supports the features mentioned in this article. And remember that experimental features can change on future versions of Node.js. +> **⚠️WARNING⚠️:** All content in this article uses Node.js experimental features. Please make sure you are using a version of Node.js that supports the features mentioned in this article. And remember that experimental features can change in future versions of Node.js. # Running TypeScript Natively @@ -14,7 +14,7 @@ In the previous articles, we learned how to run TypeScript code using transpilat Since V22.6.0, Node.js has experimental support for some TypeScript syntax. You can write code that's valid TypeScript directly in Node.js without the need to transpile it first. -So how do you run typed JavaScript code with Node.js? +So how do you run TypeScript code with Node.js? ```bash node --experimental-strip-types example.ts @@ -22,14 +22,14 @@ node --experimental-strip-types example.ts The `--experimental-strip-types` flag tells Node.js to strip the type annotations from the TypeScript code before running it. -And that's it! You can now run typed JavaScript code directly in Node.js without the need to transpile it first, and use TypeScript to catch type-related errors. -In the future we all hope that this feature will be stable and available in the LTS version of Node.js, so that we can all enjoy it without any additional steps. +And that's it! You can now run TypeScript code directly in Node.js without the need to transpile it first, and use TypeScript to catch type-related errors. +Future versions of Node.js will include support for TypeScript without the need for a command line flag. ## Limitations -At the time of writing, the experimental support for TypeScript in Node.js has some limitations. To allow typescript to run in node.js, our collaborators have chosen to only strip types from the code. +At the time of writing, the experimental support for TypeScript in Node.js has some limitations. To allow TypeScript to run in node.js, our collaborators have chosen to only strip types from the code. -You can get more information on the [api docs](https://nodejs.org/docs/latest/api/typescript.html#unsupported-typescript-features) +You can get more information on the [API docs](https://nodejs.org/docs/latest/api/typescript.html#unsupported-typescript-features) ## Important notes diff --git a/apps/site/pages/en/learn/typescript/run.md b/apps/site/pages/en/learn/typescript/run.md index ca85adceacbb..b3404b1c4556 100644 --- a/apps/site/pages/en/learn/typescript/run.md +++ b/apps/site/pages/en/learn/typescript/run.md @@ -10,7 +10,7 @@ In the previous article, we learned how to run TypeScript code using transpilati ## Running TypeScript code with `ts-node` -[ts-node](https://typestrong.org/ts-node/) is a TypeScript execution environment for node.js. It allows you to run TypeScript code directly in node.js without the need to compile it first. But it's not typechecking your code. So we recommend to type check your code first with `tsc` and then run it with `ts-node` before shipping it. +[ts-node](https://typestrong.org/ts-node/) is a TypeScript execution environment for Node.js. It allows you to run TypeScript code directly in Node.js without the need to compile it first. Note, however, that it does not type check your code. So we recommend to type check your code first with `tsc` and then run it with `ts-node` before shipping it. To use `ts-node`, you need to install it first: @@ -26,7 +26,7 @@ npx ts-node example.ts ## Running TypeScript code with `tsx` -[tsx](https://tsx.is/) is another TypeScript execution environment for node.js. It allows you to run TypeScript code directly in node.js without the need to compile it first. But it's not typechecking your code. So we recommend to type check your code first with `tsc` and then run it with `tsx` before shipping it. +[tsx](https://tsx.is/) is another TypeScript execution environment for Node.js. It allows you to run TypeScript code directly in Node.js without the need to compile it first. Note, however, that it does not type check your code. So we recommend to type check your code first with `tsc` and then run it with `tsx` before shipping it. To use `tsx`, you need to install it first: