Support TypeScript executable without extension when flag is set

[niedzielski]

What is the problem this feature will solve?

When I write an executable utility like build-game, I have to expose the implementation detail of the language it's written in, like build-game.ts.

#!/usr/bin/env node
// This file is named `build-game` not `build-game.ts`. Only plain JavaScript is allowed.

const foo: number = 1 // Error: TypeScript encountered.
console.log(foo)

/home/user/bin/build-game:3
const foo: number = 1
      ^^^

SyntaxError: Missing initializer in const declaration
    at wrapSafe (node:internal/modules/cjs/loader:1624:18)
    at Module._compile (node:internal/modules/cjs/loader:1666:20)
    at Object..js (node:internal/modules/cjs/loader:1824:10)
    at Module.load (node:internal/modules/cjs/loader:1427:32)
    at Module._load (node:internal/modules/cjs/loader:1250:12)
    at TracingChannel.traceSync (node:diagnostics_channel:322:14)
    at wrapModuleLoad (node:internal/modules/cjs/loader:235:24)
    at Module.executeUserEntryPoint [as runMain] (node:internal/modules/run_main:152:5)
    at node:internal/main/run_main_module:33:47

Node.js v24.4.1

What is the feature you are proposing to solve the problem?

When --experimental-strip-types is set (or add a new flag), force TypeScript evaluation. This will allow a script to encapsulate all interpreter detail.

#!/usr/bin/env -S node --experimental-strip-types
// This file is named `build-game` not `build-game.ts`. TypeScript is allowed
// because the `--experimental-strip-types` flag was passed.

const foo: number = 1
console.log(foo)

What alternatives have you considered?

If the executable is in an NPM package, I can just alias it in the package.json. If the executable is in my ~/bin, I can just shell alias it. However, these are both limited and really prevent me from sharing scripts with nice names that work everywhere.

[milesguicent]

I am not sure what you are asking for exactly.

When I copy both of your pieces of code in a file, do a chmod +x test.ts and run it with ./test.ts, the script works.

$ ./test.ts
1
(node:84155) ExperimentalWarning: Type Stripping is an experimental feature and might change at any time
(Use `node --trace-warnings ...` to show where the warning was created)

I can even suppress the warning with #!/usr/bin/env -S node --experimental-strip-types --disable-warning=ExperimentalWarning.

I tested this with node v24 like you.

If the executable is in an NPM package, I can just alias it in the package.json

I'm not sure you want to distribute typescript files as packages just yet, type stripping is a rather new feature so any user not using the latest node will not be able to run this file. You should probably built it and distribute than as .js files.

[marco-ippolito]

That's odd, it should not emit an experimental warning, investigsting 🕵🏼
you are probably using an old version of Node v24. Using latest:

#!/usr/bin/env node

const foo: string = "Hello, World!";
console.log(foo);

marcoippolito@Mac test % node -v   
v24.6.0
marcoippolito@Mac test % ./test.ts 
Hello, World!

So just update your node version and it should be working fine

[milesguicent]

So just update your node version and it should be working fine

Indeed this was due to me using an older version.

But maybe I wouldn't close this issue until @niedzielski actually clarify what they were trying to do ?

[niedzielski]

Sorry, I did a terrible job explaining. The examples above were all on a file called foo (no extension), not foo.ts. The intent of the ticket was to ask for a flag that would allow overriding how a file was interpreted using command line flags. Kind of similar to how --input-type can control the module for string input, I want the ability to explicitly specify the language of file input. I'll try to clarify in the ticket and ask that it be reopened for consideration.

[marco-ippolito]

@niedzielski thanks for clarifying, currently when extentionless, the file is always evaluated as initially commonjs (and then goes through detection) as specified by https://nodejs.org/api/cli.html#program-entry-point.
It will switch to typescript only if the file has .ts extension https://github.com/nodejs/node/blob/main/lib/internal/modules/cjs/loader.js#L1852

Adding ts detection is possible but would introduce some overhead and it's not reliable since an example like:

fetch<Object>('example.org')

has different runtime value if evaluated as js or as ts (currently evaluated as js)

[niedzielski]

Adding ts detection

@marco-ippolito, automatic detection would be amazing! However, for this ticket I just was hoping for the ability to manually override the language with a flag. I speculate there's some precedence with the way there's a couple module flags for specifying how the file is treated as ESM or CJS. Since there's already the --experimental-strip-types flag, it seems like a good fit to explicitly force TypeScript interpretation but a new flag would be fine too.

[marco-ippolito]

A flag imho is the only feasible way since automatic detection or typescript priority changes the runtime value.
Or we could use --input-type?

[niedzielski]

My understanding of --input-type is that it's only for programs supplied as a string, not within a file. For example, node --input-type=module --eval='import fs from "node:fs"'.

[marco-ippolito]

Something like this could work:

diff --git a/lib/internal/modules/cjs/loader.js b/lib/internal/modules/cjs/loader.js
index 3b16099848a..d948fa0c635 100644
--- a/lib/internal/modules/cjs/loader.js
+++ b/lib/internal/modules/cjs/loader.js
@@ -1849,7 +1849,7 @@ Module._extensions['.js'] = function(module, filename) {
     format = 'module-typescript';
   } else if (StringPrototypeEndsWith(filename, '.cts') && tsEnabled) {
     format = 'commonjs-typescript';
-  } else if (StringPrototypeEndsWith(filename, '.ts') && tsEnabled) {
+  } else if ((StringPrototypeEndsWith(filename, '.ts') || (getOptionValue('--experimental-force-ts-entrypoint') && module[kIsMainSymbol])) && tsEnabled) {
     pkg = packageJsonReader.getNearestParentPackageJSON(filename);
     const typeFromPjson = pkg?.data.type;
     if (typeFromPjson === 'module') {
diff --git a/src/node_options.cc b/src/node_options.cc
index 5cf7a9cbf58..4924b61d186 100644
--- a/src/node_options.cc
+++ b/src/node_options.cc
@@ -1060,6 +1060,11 @@ EnvironmentOptionsParser::EnvironmentOptionsParser() {
             &EnvironmentOptions::experimental_strip_types,
             kAllowedInEnvvar,
             false);
+  AddOption("--experimental-force-ts-entrypoint",
+            "Experimental support for TypeScript entrypoints.",
+            &EnvironmentOptions::experimental_force_ts_entrypoint,
+            kAllowedInEnvvar,
+            true);
   AddOption("--experimental-transform-types",
             "enable transformation of TypeScript-only"
             "syntax into JavaScript code",
diff --git a/src/node_options.h b/src/node_options.h
index d56a2c536f7..99eb2c72eb5 100644
--- a/src/node_options.h
+++ b/src/node_options.h
@@ -258,6 +258,7 @@ class EnvironmentOptions : public Options {
   std::vector<std::string> preload_esm_modules;
 
   bool experimental_strip_types = true;
+  bool experimental_force_ts_entrypoint = false;
   bool experimental_transform_types = false;
 
   std::vector<std::string> user_argv;

And then in your script:

#!/usr/bin/env node --experimental-force-ts-entrypoint

const foo: number = 1
console.log(foo)

@nodejs/loaders do you think its a good idea before I open a PR?

[aduh95]

We could bring back --experimental-default-type since it already deals with extensionless files, although it's not exactly fitting. If we're going with a new flag, a more accurate name would be --experimental-strip-types-in-extensionless-entrypoint if I understand the suggested diff correctly.