Typescript: run with watch, SFlight sample

node.js/typescript.md

@@ -29,52 +29,78 @@ Follow these steps to add TypeScript support:
     You can modify this configuration file to match your project setup. See the [official TypeScript documentation](https://www.typescriptlang.org/docs/handbook/tsconfig-json.html) for more details.
     Note that adding the `typescript` facet, [`cds-typer`](../tools/cds-typer) is also automatically added to your project.
 
+## Writing TypeScript Files
 
+Once you've setup everything correctly, you can start writing TypeScript files
+instead of JavaScript files. This applies for service handlers, as well as a custom _server.ts_ file, or database _init.ts_ seeding files.
+
+## Samples
+
+For a full TypeScript application, check out the [SFlight application](https://github.com/SAP-samples/cap-sflight).
+It features both [CAP service handlers](https://github.com/SAP-samples/cap-sflight/tree/206faf29801ca25b8601d75a23284da07d2ebf4a/srv) and [client-side code for SAP Fiori Elements](https://github.com/SAP-samples/cap-sflight/tree/206faf29801ca25b8601d75a23284da07d2ebf4a/app/travel_processor/webapp/ext/controller) written in TypeScript.
 
-## Developing with `cds-tsx` <Since version="8.2.0" of="@sap/cds-dk" /> { #cds-tsx}
 
-Use the `cds-tsx` CLI command instead of `cds` to avoid having to precompile TypeScript files to JavaScript each time and speed up development:
+## Developing TypeScript Projects
+
+### Using `cds watch` <Since version="8.6.0" of="@sap/cds-dk" /> { #cds-watch}
+
+Preferably use `cds watch` in a TypeScript project as if it was a Javascript project.
+It will detect TypeScript mode based on a `tsconfig.json` and run [`cds-tsx`](#cds-tsx) under the hood.
 
 ```sh
+cap/sflight $ cds watch
+
+Detected tsconfig.json. Running with tsx.
+...
+[cds] serving TravelService { impl: 'srv/travel-service.ts', path: '/processor' }
+...
+```
+
+The same applies to `cds serve`.
+
+
+### Using `cds-tsx` <Since version="8.2.0" of="@sap/cds-dk" /> { #cds-tsx}
+
+Alternatively, you can use the `cds-tsx` CLI command instead of `cds` for automatic TypeScript transpilation:
+
+::: code-group
+```sh [watch]
 cds-tsx watch
 ```
 
-```sh
-cds-tsx serve world.cds
+```sh [serve]
+cds-tsx serve
 ```
+:::
 
-When using the binary `cds-tsx`, the [tsx](https://tsx.is/) engine is used to start the project instead of the default node engine.
-You can install it globally with:
+Under the hood, the [tsx](https://tsx.is/) engine is used to run the files instead of the default `node` engine.
+Install it globally with:
 ```sh
 npm i -g tsx
 ```
 
 ::: warning Not for production
-`cds-tsx` / `tsx` should be used for development only. **For productive usage always precompile TypeScript code** to JavaScript for best performance and use `cds-serve` as usual.
+Both `cds-watch` and `cds-tsx` / `tsx` should be used for development only. **For productive usage always precompile TypeScript code** to JavaScript for best performance and use `cds-serve` as usual.
 :::
 
-### Writing TypeScript Files
-
-Once you've setup everything correctly, you can start writing TypeScript files
-instead of JavaScript files. This applies for service handlers, as well as a custom _server.ts_ file or database _init.ts_ seeding files.
-
-### Samples
-
-You can also download the [*Hello World!* TypeScript sample](https://github.com/SAP-samples/cloud-cap-samples/tree/master/hello) or try out the [Full Stack TypeScript App](https://github.com/SAP-samples/btp-full-stack-typescript-app).
-
-### Developing with `cds-ts` { #cds-ts}
+### Using `cds-ts` { #cds-ts}
 
 Much like `cds-tsx`, you can also use the `cds-ts` CLI command:
 
-```sh
+::: code-group
+```sh [watch]
 cds-ts watch
-cds-ts serve world.cds
 ```
 
+```sh [serve]
+cds-ts serve
+```
+:::
+
 It uses the [ts-node](https://github.com/TypeStrong/ts-node) engine under the hood.
 
-::: tip _cds-tsx_ or _cds-ts_?
-In general, `cds-tsx` seems to be the better choice as `tsx` is much faster than `ts-node` because it does not perform type checks.
+::: tip _tsx_ or _ts-node_?
+In general, `tsx` is the better choice, as `tsx` is much faster than `ts-node` because it does not perform type checks.
 See a closer [comparison](https://tsx.is/faq#how-does-tsx-compare-to-ts-node) between the two of them.
 :::