Commit 5978eb1
doc: add TypeScript execution requirements
Add section with high level approach/requirements for
enabling TypeScript execution as discussed in the Next-10
[TypeScript mini-summit](nodejs/next-10#150)
Signed-off-by: Michael Dawson <mdawson@devrus.com>
PR-URL: #44030
Reviewed-By: Geoffrey Booth <webadmin@geoffreybooth.com>
Reviewed-By: Matteo Collina <matteo.collina@gmail.com>1 parent b186684 commit 5978eb1
1 file changed
Lines changed: 59 additions & 1 deletion
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
@@ -6,7 +6,7 @@ code of their JavaScript projects. While many people don't annotate their code, | |||
| 6 | 6 | or make use of annotations at all, there are enough who do that the project has | |
| 7 | 7 | agreed it's important to work towards having [suitable types for end-users][]. | |
| 8 | 8 | ||
| 9 | - ## High level approach | ||
| 9 | + ## High level approach - maintaining types | ||
| 10 | 10 | ||
| 11 | 11 | There are a number of ways that types could be maintained for Node.js ranging | |
| 12 | 12 | from shipping them with the Node.js runtime to having them be externally | |
@@ -28,6 +28,64 @@ The agreement was that the ideal flow would be as follows: | |||
| 28 | 28 | * Automation within external type projects consumes the JSON and automatically | |
| 29 | 29 | generates a PR to add the API. | |
| 30 | 30 | ||
| 31 | + ## High level approach - development workflow | ||
| 32 | + | ||
| 33 | + The number of people using TypeScript with Node.js is significant enough | ||
| 34 | + that providing a good developer experience is important. While TypeScript | ||
| 35 | + is identified specifically, a secondary goal is that what we provide to improve | ||
| 36 | + development experience with TypeScript would apply to other type | ||
| 37 | + systems and transpiled languages as well. | ||
| 38 | + | ||
| 39 | + We have agreed that the approach will **NOT** include bundling TypeScript | ||
| 40 | + tools with Node.js but instead improve the developer experience for how | ||
| 41 | + those tools are installed/configured to work with Node.js. | ||
| 42 | + | ||
| 43 | + The high level developer experience we are working towards was captured in the | ||
| 44 | + [next-10 TypeScript mini-summit](https://github.com/nodejs/next-10/pull/150) | ||
| 45 | + and is as follows: | ||
| 46 | + | ||
| 47 | + 1. When Node.js is started with an entry point that is not a file type that | ||
| 48 | + Node.js recognizes, for example `node script.ts`, an informative error | ||
| 49 | + message is printed that directs users to a webpage where they can | ||
| 50 | + learn how to configure Node.js to support that file type. | ||
| 51 | + * If the file was a TypeScript file, a TypeScript specific message with a | ||
| 52 | + reference to a link on Nodejs.org specific on learning how to | ||
| 53 | + configure TypeScript will be provided. | ||
| 54 | + * For other file types a generic message and shared webpage will be | ||
| 55 | + used. | ||
| 56 | + 2. Node.js gains support for loading configuration from a file. Most, if not | ||
| 57 | + all, of the configuration supported by `NODE_OPTIONS` would be | ||
| 58 | + supported in this file (which might be the `package.json` that lives | ||
| 59 | + near the entry point file). The webpage with instructions would tell | ||
| 60 | + users what configuration to put in this file to get Node.js to support | ||
| 61 | + their file type. | ||
| 62 | + 3. When Node.js is run with the correct configuration, either in a file or | ||
| 63 | + `NODE_OPTIONS` or flags, the unknown file type is executed as expected. | ||
| 64 | + | ||
| 65 | + Some additional specifics around the current approach include: | ||
| 66 | + | ||
| 67 | + * Loaders already provide a number of the components needed to | ||
| 68 | + satisfy the requirements above. They already provide the Node.js | ||
| 69 | + options that are needed to achieve many of the requirements above. | ||
| 70 | + * `package.json` as the location for the config is potentially a good | ||
| 71 | + choice as Node.js already looks for it as part of startup. | ||
| 72 | + * The implementation chosen should allow for different configuration | ||
| 73 | + in/for different environments/conditions such as production | ||
| 74 | + versus development, or different types of hosted environments | ||
| 75 | + such as serverless vs traditional, etc.; Node.js would not make | ||
| 76 | + any recommendations or have any expectations as to what the | ||
| 77 | + separate configuration blocks should be named or what their | ||
| 78 | + purposes should be, just that a configuration file should have | ||
| 79 | + the ability to provide different configurations for user-defined | ||
| 80 | + conditions. | ||
| 81 | + * There is no plan to define a default tsconfig.json for all Node.js users | ||
| 82 | + * We don't have consensus on provding an opinionated default but | ||
| 83 | + that should be explored after the initial steps are complete. | ||
| 84 | + * It will be important that as part of the messaging around this | ||
| 85 | + functionality that we avoid confusion that could lead people to ship | ||
| 86 | + TypeScript files (e.g. `script.ts`) instead of the processed files | ||
| 87 | + (e.g. `script.js`). | ||
| 88 | + | ||
| 31 | 89 | ## Generation/Consumption of machine readable JSON files | |
| 32 | 90 | ||
| 33 | 91 | When you run `make doc` the canonical markdown files used to | |
0 commit comments