A Node, TypeScript, TS-Node and ESM experience that works

The current ESM experience makes it seem like decision-makers in the node.js project were wilfully oblivious to how large the TypeScript community was and how it was being used in node modules and projects. It really does feel like the maintainers focus was on JS and harmony with TypeScript&#x27;s evolution was low on the priority list.<p>Meanwhile anyone using an intersection of TypeScript with jest and any of sindresorhus&#x27; libraries when he flipped to ESM for his bajillion libraries immediately felt the downside and moved hard away from ESM.<p>Imagine the mind-boggling hours lost just to get these export&#x2F;import formats to glue.

Many people in this thread are rightly complaining that this does not answer the &quot;why does this work&quot;. Having a working example is a good start for that though as at least you have a known target and as you change things (and break things), you can see what those options did.<p>One problem with this guide that makes that trickier is that the tsconfig.json itself imports <a href="https:&#x2F;&#x2F;github.com&#x2F;sindresorhus&#x2F;tsconfig&#x2F;blob&#x2F;5c87dc118e057dc16fe1e62c990645000dbfaac7&#x2F;tsconfig.json">https:&#x2F;&#x2F;github.com&#x2F;sindresorhus&#x2F;tsconfig&#x2F;blob&#x2F;5c87dc118e057d...</a> and overrides a bunch of values.<p>So if you really want to understand what it&#x27;s doing, you need to get rid of that dependency and inline &#x2F; merge that config file. That would also add stability to your project as it&#x27;s one less upstream dependency out of your control (and a big one at that as it controls how you entire project is built!).<p>For example the imported tsconfig.json changes these:<p><pre><code> &quot;compilerOptions&quot;: { &#x2F;&#x2F; ... &quot;module&quot;: &quot;node16&quot;, &quot;moduleResolution&quot;: &quot;node16&quot;, &quot;moduleDetection&quot;: &quot;force&quot;, &#x2F;&#x2F; ... &quot;allowSyntheticDefaultImports&quot;: true, &#x2F;&#x2F; To provide backwards compatibility, Node.js allows you to import most CommonJS packages with a default import. This flag tells TypeScript that it&#x27;s okay to use import on CommonJS modules. &quot;jsx&quot;: &quot;react&quot;, &#x2F;&#x2F; ... } </code></pre> But you wouldn&#x27;t notice that if you just look at the gist. It&#x27;d just be a magic that you can write React code in a .tsx file. Clearly that has to be enabled <i>somewhere</i>.

I see (and have participated in) a lot of this &quot;just copy this thing, trust me it works&quot; type of content related to Node and TypeScript.<p>It makes me wonder why Deno [1] still seems to be such a niche choice. Most of these headaches just go away.<p>Does anyone here prefer Deno for new projects? And if not, why?<p>[1] And Bun, although that&#x27;s much newer.

I’ve found TSX to be a better alternative to ts-node. It seems to have more sensible defaults in 2023. <a href="https:&#x2F;&#x2F;github.com&#x2F;privatenumber&#x2F;tsx">https:&#x2F;&#x2F;github.com&#x2F;privatenumber&#x2F;tsx</a>

I just got started with a Next.js project coming from React with JS and…. another JS&#x2F;TS rant incoming…..<p>For an ecosystem that purports to be ready for professional use it absolutely boggles my mind that the tooling is stuck at this very amateurish level.<p>Why isn’t there a ready preset for me to use ESM syntax with Next.js &#x2F; Typescript?<p>What’s wrong with the culture around Node&#x2F;TS&#x2F;JS tooling in general that it’s so consistently broken all the time? What the hell.

This is not a guide, it&#x27;s three config files

Having tried to wrangle all of this both professionally and for a side project, the link is an over-simplification. No, it won&#x27;t &quot;just work&quot;.<p>Part of the problem is the fact that web browsers, Node.js, and other JS runtimes have slightly different needs and expectations. Part of the problem arises when you&#x27;re trying to mix and match web code, Node.js code, and other JS runtime code in the same monorepo. There&#x27;s no single magic-bullet configuration.

Add eslint and jest to pull your hairs of you head. I managed to get it right last week, but I&#x27;m pretty confident that next upgrade I&#x27;ll have to revise most of it.

&gt; Just add the following files and run npm run dev. You&#x27;ll be good to go!<p>This attitude just doesn&#x27;t work for js ecosystem. I have some shell scripts, vim config files, etc. that I don&#x27;t remember what they do, but I just copy over and they work.<p>Coding projects are different; they break all the time. Especially with how fast the js&#x2F;ts ecosystem works. One day, a crucial library just decides that it&#x27;s changed something that doesn&#x27;t work with the build process because there&#x27;s so many variations of them that they can&#x27;t possibly all be tested against.

I&#x27;ve been trying to upgrade a couple of libraries we use internally at work to output CJS + ESM, from a typescript project, and have the output be 1-to-1 files (so, no bundling &#x2F; rollup &#x2F; whatever you want to call it).<p>What a frustrating experience it has been.<p>Using unbuild &quot;works&quot;, but<p>- For the life of me, I can&#x27;t get unbuild to generate `.d.mts` files when my source files don&#x27;t have `.mts` extensions. Luckily, when the library is used in a downstream project and a `.mjs` file is imported, TypeScript properly loads the `.d.ts` file anyways<p>- When it comes to a downstream project, TypeScript doesn&#x27;t seem to work with export maps. People say it does, but maybe because I don&#x27;t have `.d.mts` files TypeScript is saying it can&#x27;t find type information? It _does_ work with simple export maps, but if I say `&#x27;.&#x2F;<i>&#x27;: &#x27;.&#x2F;dist&#x2F;esm&#x2F;</i>&#x27;` so the downstream project doesn&#x27;t have to manually import from `dist&#x2F;esm` I see the issue<p>- Using the &quot;esm&quot; module &#x2F; moduleResolutions + converting my files to `.mts` + changing imports in the source to import the non-existant `.mjs` files results in a CJS bundle that tries to require a `.mjs` file, which unbuild has built with a `.js` extension, so it throws an error because it can&#x27;t find the file.<p>- For some reason unbuild mucks with the hashbang line in my _CJS_ `bin` script, the ESM one it doesn&#x27;t touch<p>Ugh.

One problem I encountered with ESM TypeScript development on the browser without bundling: many Node packages aren&#x27;t set up for that.<p>You might ask why without bundling?<p>Sometimes you just want to start something simple on the browser and compile to JavaScript on the fly.<p>I tried the dev server from Modern Web [0], and I liked it. I program in TypeScript and the browser reloads whenever I save a file. Of course I could set up a bundler and for a small program waiting times are negligible. But I hate bundlers. I know it&#x27;s irrational, but nowadays I program for fun so I think I should have the choice to reject bundlers.<p>This fails for many Node dependencies. There is a conflict between CommonJS and ESM. I am not 100% sure that what I want to achieve is impossible without forking dependencies and making a small change.<p>I even found a way to have a CommonJs and ESM polyglot, but this hack is extremely ugly. I named the hack modglot [1]. I don&#x27;t think this is a good idea and I don&#x27;t understand enough to propose something. I am somewhat dejected about the current state of TypeScript development for the browser and paused development.<p>Now I am programming in Rust again just for fun, but if I return to TypeScript, probably I will try out Deno.<p>[0]: <a href="https:&#x2F;&#x2F;modern-web.dev&#x2F;guides&#x2F;dev-server&#x2F;getting-started&#x2F;" rel="nofollow noreferrer">https:&#x2F;&#x2F;modern-web.dev&#x2F;guides&#x2F;dev-server&#x2F;getting-started&#x2F;</a><p>[1]: <a href="https:&#x2F;&#x2F;github.com&#x2F;nalply&#x2F;modglot">https:&#x2F;&#x2F;github.com&#x2F;nalply&#x2F;modglot</a>

I am pretty sure &quot;type&quot;: &quot;module&quot; doesn&#x27;t work with React Native&#x2F;Expo and jest (in 2022 last time I tried).<p>If you Google the error you will get stackoverflow posts with hundreds of upvotes.<p>And that&#x27;s the main problem with using ESM - 3rd party library support. It is trivial to do hello world in ESM with Node.js, but try that with 10 dependencies and quickly you will be hit errors.

Node.js, TypeScript (compiled script...), ESM modules, versions, and the dependencies tree hell... You guys are adopting the masochism, the problem is that you are dragging the rest of us into that hell.

A gist, the digital equivalent of scribblings on a stained cocktail napkin, lays bare the great mystery. The great dragon is slain! His precious treasure is of no value whatsoever.<p>Fellow scrounging raccoons, raise your chipped mugs and cracked cups! Let us toast to our fortune, we truly are the blessed ones.

Ah, I upgraded just yet, realized node 20 broke the way ts-node-esm loader works. Had to downgrade to 18, because there&#x27;s no functionality I really need from 20. Also Vite complained when I tried node 19, because it requires &lt;=18 &amp;&amp; &gt;=20 for some reason (probably good one).<p>I&#x27;m maintaining a few pristine example projects to keep track of these ways and test them periodically. This iteration probably had the shortest lifetime. I didn&#x27;t manage to develop even a single toy project before something got obsoleted again. Love this community. Looking forward to solve a handful of brand new issues with tsx.<p>I wish there was some IDEish starter pack which you could install and start writing code anytime, without investigating issues with running a damn interpreter.

Some comments and suggestions:<p>- `importsNotUsedAsValues` is deprecated [0] since TypeScript 5.2, in favor of `verbatimModuleSyntax` [1].<p>- I could set `module` to `Node16`. This automatically set `esModuleInterop` to true.<p>- Also, to catch more issues, set `allowUnreachableCode` to false and set `strict`, `noImplicitReturns`, `noImplicitOverride`, `noFallthroughCasesInSwitch`, `exactOptionalPropertyTypes` to true.<p>- Set `types` to the empty array `[]` to avoid loading unwanted types.<p>- Enable `skipLibCheck` to avoid checking imported module types.<p>- Not sure that `declarationMap` is still useful nowadays. TypeScript is now able to match directly against source files.<p>- Enable `composite` that in turns enables `incremental` and `declaration` (declaration file emit). `composite` enables project references which is useful in a monorepo setting or to separate source and test files into two projects. See [2]<p>- Enable `checkJs` to type-check JavaScript files<p>To summarize:<p><pre><code> { &quot;$schema&quot;: &quot;https:&#x2F;&#x2F;json.schemastore.org&#x2F;tsconfig&quot;, &quot;compilerOptions&quot;: { &quot;lib&quot;: [&quot;ES2022&quot;], &quot;module&quot;: &quot;Node16&quot;, &quot;target&quot;: &quot;ES2022&quot;, &quot;outDir&quot;: &quot;.&#x2F;dist&quot;, &quot;composite&quot;: true, &quot;sourceMap&quot;: true, &quot;types&quot;: [], &quot;isolatedModules&quot;: true, &quot;resolveJsonModule&quot;: true, &quot;skipLibCheck&quot;: true, &quot;verbatimModuleSyntax&quot;: true, &quot;allowUnreachableCode&quot;: false, &quot;checkJs&quot;: true, &quot;exactOptionalPropertyTypes&quot;: true, &quot;noFallthroughCasesInSwitch&quot;: true, &quot;noImplicitOverride&quot;: true, &quot;noImplicitReturns&quot;: true, &quot;strict&quot;: true } &quot;include&quot;: [&quot;.&#x2F;src&#x2F;**&#x2F;*.ts&quot;], &quot;exclude&quot;: [&quot;.&#x2F;src&#x2F;specific-file.ts&quot;] } </code></pre> [0] <a href="https:&#x2F;&#x2F;www.typescriptlang.org&#x2F;tsconfig#importsNotUsedAsValues" rel="nofollow noreferrer">https:&#x2F;&#x2F;www.typescriptlang.org&#x2F;tsconfig#importsNotUsedAsValu...</a><p>[1] <a href="https:&#x2F;&#x2F;www.typescriptlang.org&#x2F;tsconfig#verbatimModuleSyntax" rel="nofollow noreferrer">https:&#x2F;&#x2F;www.typescriptlang.org&#x2F;tsconfig#verbatimModuleSyntax</a><p>[2] <a href="https:&#x2F;&#x2F;www.typescriptlang.org&#x2F;docs&#x2F;handbook&#x2F;project-references.html" rel="nofollow noreferrer">https:&#x2F;&#x2F;www.typescriptlang.org&#x2F;docs&#x2F;handbook&#x2F;project-referen...</a>

<a href="https:&#x2F;&#x2F;gist.github.com&#x2F;joepie91&#x2F;bca2fda868c1e8b2c2caf76af7dfcad3" rel="nofollow noreferrer">https:&#x2F;&#x2F;gist.github.com&#x2F;joepie91&#x2F;bca2fda868c1e8b2c2caf76af7d...</a>

This is why I use bun now! It just works, NodeJS is such a shit show right now, feels like the python 2-&gt;3 move.

Also see TSM: <a href="https:&#x2F;&#x2F;github.com&#x2F;lukeed&#x2F;tsm">https:&#x2F;&#x2F;github.com&#x2F;lukeed&#x2F;tsm</a>

this setup doesn’t work with node test runner.<p>I had to tsc then node --test the built files.<p>tsx also is missing the test runner <a href="https:&#x2F;&#x2F;github.com&#x2F;privatenumber&#x2F;tsx&#x2F;issues&#x2F;257">https:&#x2F;&#x2F;github.com&#x2F;privatenumber&#x2F;tsx&#x2F;issues&#x2F;257</a>

- Why include files, exports, and types in your package.json when you are just using ts-node to transpile on the fly?<p>- ts-node is much slower than something like esbuild&#x2F;tsx right? As long as you rely on your ide type checking or run type checking before deploying your app.

+1 to what one of the commenters is saying. You can skip all of this and just use `tsx`. I currently sponsor that project. That&#x27;s how impactful it was on all of my development.<p>I will say that it&#x27;s kind of sad that Node.js has devolved into this.

&gt; The experience of using Node.JS with TypeScript, ts-node, and ESM is horrible.<p>So true, I really wandering if there was a better alternative, they essentially broke a lot of packages and I don&#x27;t know how many dev hours will be put now to fix all of this, because so many tools are broken now. Additionally to that, they did some other not backwards compatible changes, like removing __direname in ESM, which is IMHO not the best decisions, why not for example just keep it as it is, but deprecate it and have a warning message.

Typescript is a huge improvement over JS, but I never use it. My rule of thumb is that if TS provides a tangible benefit, I have too much complexity on the frontend.

I did some experiments myself and settled on this template repository:<p><a href="https:&#x2F;&#x2F;github.com&#x2F;bhouston&#x2F;template-typescript-monorepo">https:&#x2F;&#x2F;github.com&#x2F;bhouston&#x2F;template-typescript-monorepo</a><p>This has a lot of features that work well together: - TypeScript - ESM - Node.JS Server + React + Cli - Monorepository - Fast Incremental Updates<p>Feedback welcome. I use this for about a dozen different projects now.

Main reason I even tried bun out. Honestly &#x27;just works&#x27;, I&#x27;ve only had one issue so far and it was with a unpopular compiled module.

Sharing <a href="https:&#x2F;&#x2F;github.com&#x2F;tommyguo&#x2F;node_monorepo">https:&#x2F;&#x2F;github.com&#x2F;tommyguo&#x2F;node_monorepo</a> if this helps folks. It&#x27;s a Typescript monorepo template with everything you need included.<p>I&#x27;m currently using this setup to run multiple services on AWS.

Here comes a question what many of the people reading the comments are thinking:<p>As of November 2023, what is the canonical way to set up a Node project with Typescript and hot reload?<p>Minimal setup with least amount of configs and tooling. I am not after any other tools like Bun.

I really detest this JS dx.<p>Ideally things are great — do ur frontend dev in js and backend in js. With TS added for better dx. Except 90% of the time ur fighting the configs of why its not importing&#x2F;requiring<p>U change from .js, .ts, .cjs, .mjs and nothing works

And if you publush it, imports are going to be from &#x27;pkg&#x2F;dist&#x2F;foo&#x27;..

I always found it easier to avoid `ts-node` as it introduced a bunch of small compat issues.<p>Since TS 4.5 and their support for `.mts`, I finally settled on just chaining `tsc --build &amp;&amp; node .&#x2F;build&#x2F;main.mjs`.

I&#x27;m going to keep hitting reload on this page until someone solves some of the worst problems of my work life right now; getting a npm monorepo with typescript, eslint and jest working smoothly. Thank you to whoever(s) that is. I&#x27;m trying to make a public project, but building&#x2F;developing with it is successive layers of sometimes-works voodoo that have nothing to do with the project goals. Somewhat compounded when members of nx (nee lerna) popped in to try to help, adding another layer of sometimes-works. As it is, DX depends on a fast computer to basically rebuild the whole thing each time, or running build &amp; test in a dozen workspaces, because I haven&#x27;t found any other reliable &quot;workflow.&quot;

Could someone succinctly describe the situation between node ts and esm?<p>I’m not very familiar with the ecosystem and trying to understand what pain ports people are describing here in the comments.

Does Node.js plan to transpile TS out-of-the-box soon? (Picking up a legacy project, can&#x27;t swap out for Deno or another runtime just yet)

<i>The experience of using Node.JS with TypeScript, ts-node, and ESM is horrible.</i><p>I completely disagree. This has always felt immediately straight forward to me. I suspect this struggle, a struggle I completely don’t understand, explains the complexity of hiring for these kinds of jobs. I really felt that to get hired for these jobs you had to be willing to play stupid games and abandon all reason to worship at the pulpit of giant frameworks and third party solutions. Fortunately, I have moved on to something else.

In order to be a guide, I feel like it would need to explain _why_ each thing is there and what it does.

I thought there were &quot;presets&quot; that NPM and Yarn knew about to do this kind of thing...

Hear me out: if you need to do this just to use a tool effectively, maybe it&#x27;s a bad tool.

&quot;...for a few months.&quot;<p>Until this github repo dries up the same way similar attempts at this have.

Why not using Node how it is designed, than ESM works great.<p>For type checking on development, you can do it with ESLint and JSDoc in Typescript modus. You have the same type checking like you have in ts files. You can even import types from typescript files, like .d.ts<p>Best of both worlds, no transformation of the code, and on development you have some help from Typescript.

Module resolution &quot;bundler&quot;.<p>ts-node --esm --swc<p>Haven&#x27;t really had any issues with this in a long time.

Now add eslint and prettier :)

Agree it is a little tricky to get startet. But once configured, it helps a lot