Skip to content

Commit

Permalink
doc: add TypeScript execution requirements
Browse files Browse the repository at this point in the history
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>
  • Loading branch information
mhdawson committed Jul 28, 2022
1 parent a3e1108 commit 5ab69c3
Showing 1 changed file with 49 additions and 1 deletion.
50 changes: 49 additions & 1 deletion doc/contributing/maintaining-types-for-nodejs.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ code of their JavaScript projects. While many people don't annotate their code,
or make use of annotations at all, there are enough who do that the project has
agreed it's important to work towards having [suitable types for end-users][].

## High level approach
## High level approach - maintaining types

There are a number of ways that types could be maintained for Node.js ranging
from shipping them with the Node.js runtime to having them be externally
Expand All @@ -28,6 +28,54 @@ The agreement was that the ideal flow would be as follows:
* Automation within external type projects consumes the JSON and automatically
generates a PR to add the API.

## High level approach - development workflow

The number of people using TypeScript with Node.js is significant enough
that providing a good developer experience is important. While TypeScript
is identified specifically, a secondary goal is that what we provide to improve
development experience with TypeScrtipt would apply to other type
systems as well.

We have agreed that the approach will `NOT` include bundling TypeScript
tools with Node.js but instead improve the developer experience for how
those tools are installed/configured to work with Node.js.

The high level developer experience we are working towards was captured in the
[next-10 TypeScript mini-summit](https://github.com/nodejs/next-10/pull/150)
and is as follows:

1. Users can ask Node.js to execute a file which is not one of the types it
can execute by default (.js, .mjs, etc.). For example `node script.ts`.
2. On startup Node.js will look for a config which is in the scope of the
file being executed.
3. If no config is found, Node.js will echo either:
* If the file was a TypeScript file, a TypeScript specific message with a
reference to a link on Nodejs.org on how to install required components
for TypeScript and how to add the associated config.
* If the file was not a TypeScript file, a generic message
4. If a config is found, Node.js will extract the Node.js options for
that config and apply them as if they had been provided on the command
line.
5. Assuming the options associated with the config add support for the
type of file being loaded, Node.js will execute the file as if it was one
of the file types it can execute by default.

Some additional specifics around the current thinking include:

* loaders already provide a number of the components needed to
satisfy the requirements above. They already provide the Node.js
options that are needed to achieve many of the requirements above.
* package.json as the location for the config is potentially a good
choice as Node.js already looks for it as part of startup.
* The implementation chosen should allow for difference configuration in
for different enronments/conditions like prod,dev, etc.
* We don't have consensus on provding an opinionated default but
that should be explored after the initial steps are complete.
* It will be important that as part of the messaging around this
functionality that we avoid confusion that could lead people to ship
TypeScript files (ex `script.ts`) instead of the processed files
(ex `script.js`).

## Generation/Consumption of machine readable JSON files

When you run `make doc` the canonical markdown files used to
Expand Down

0 comments on commit 5ab69c3

Please sign in to comment.