DEV Community

Cover image for TypeScript in 2026: Install & Configure with Node.js 20+
Mahdi BEN RHOUMA
Mahdi BEN RHOUMA

Posted on Originally published at iloveblogs.blog

TypeScript in 2026: Install & Configure with Node.js 20+

#typescript #npm #nextjs

The search query "npm typescript latest version" usually ends with a broken build. You run npm install typescript@latest, and the next npm run build throws one of:

src/lib/supabase.ts:3:23 - error TS2307: Cannot find module '@types/node' or its corresponding type declarations.
Enter fullscreen mode Exit fullscreen mode

or, the moment you touch the Supabase client:

const { data, error } = await supabase.auth.getSession()
Enter fullscreen mode Exit fullscreen mode 
Property 'auth' does not exist on type 'SupabaseClient<Database, PublicSchemaName>'.
Enter fullscreen mode Exit fullscreen mode

It happens in npm run dev, npm run build, and in CI (Vercel/GitHub Actions) — especially in projects that started on Node.js 16 or 18, or where package.json has a stale engines field. The behavior is identical on macOS, Linux, and Windows.

The invariant that explains every symptom

TypeScript's type system is only as safe as the type definitions it reads. It erases all types at compile time and adds no runtime checks. So when a TypeScript upgrade breaks your build, the cause is always a compile-time definition mismatch — never a runtime enforcement change.

Three things must move together, or you get the errors above:

  1. The TypeScript version itself.
  2. @types/node — the type definitions for Node.js APIs (Buffer, process, etc.). TypeScript 5.x tightened module resolution, so projects that used to get these transitively now need them installed explicitly.
  3. @supabase/supabase-js — its type definitions are versioned separately from the runtime. An outdated client paired with a newer TS resolver produces Property 'auth' does not exist.

npm's engines field is a warning by default, not a hard block — so if you see install failures, look at a package.json engines mismatch or a peer-dependency conflict, not at Node.js itself.

The alignment fix 

# 1. Land on Node.js 20.x LTS
node -v
nvm install 20 && nvm use 20

# 2. Move TypeScript, the Node types, and the Supabase client forward together
npm install typescript@latest @types/node@latest @supabase/supabase-js@latest

# 3. Declare what you actually run
# in package.json:
#   "engines": { "node": ">=20.0.0" }
Enter fullscreen mode Exit fullscreen mode

Then make tsconfig.json match what Next.js's bundler expects. create-next-app ships these defaults; using NodeNext in a Next.js project breaks resolution because Next.js is not a Node.js ESM loader.

{
  "compilerOptions": {
    "target": "ES2022",
    "lib": ["ES2022", "DOM"],
    "module": "esnext",
    "moduleResolution": "bundler",
    "esModuleInterop": true,
    "skipLibCheck": true,
    "strict": true,
    "noEmit": true,
    "jsx": "preserve",
    "incremental": true,
    "paths": { "@/*": ["./src/*"] }
  },
  "include": ["next-env.d.ts", "**/*.ts", "**/*.tsx", ".next/types/**/*.ts"],
  "exclude": ["node_modules"]
}
Enter fullscreen mode Exit fullscreen mode

"module": "esnext" + "moduleResolution": "bundler" is the single change that resolves most "Cannot find module" errors after a TS bump, because it matches what webpack and Turbopack actually do.

Verify everything lines up 

node -v && npm -v && npx tsc --version
# v20.x.x
# 10.x.x
# Version 5.x.x

npx tsc --noEmit
# Found 0 errors.
Enter fullscreen mode Exit fullscreen mode

If Cannot find module '@types/node' persists:

npm install --save-dev @types/node@latest
Enter fullscreen mode Exit fullscreen mode

If Property 'auth' does not exist persists, the Supabase client is still stale:

npm ls @supabase/supabase-js
npm install @supabase/supabase-js@latest
Enter fullscreen mode Exit fullscreen mode

Two stubborn variants

npm ERR! peer optional dependency failed — @next/eslint-plugin-next has a peer range that does not yet cover the TypeScript you installed. Fix with npm install --save-dev @next/eslint-plugin-next@latest; npm 9+ auto-resolves compatible versions, no manual downgrade needed.

Jest: Cannot find module 'ts-jest' — ts-jest before v29 does not understand TypeScript 5.x. Update jest.config.js to preset: 'ts-jest' and install ts-jest@^29 @types/jest@^29.

Keep it from happening again

  • Declare "engines": { "node": ">=20.0.0" } in package.json so a mismatched runtime fails fast.
  • Use npm ci (not npm install) in CI to enforce the lockfile.
  • Run npm ls typescript @supabase/supabase-js @types/node before deploying to catch version drift.
  • In Next.js projects, keep "module": "esnext" and "moduleResolution": "bundler" — they are the create-next-app defaults and what the bundler expects.

Related

Originally published at https://www.iloveblogs.blog

Top comments (0)