Ultra Simple JS & TS Development Philosophy

This is a collection of concepts for writing readable, maintainable, frindly Node JS-based projects. This includes frontend JS projects, TypeScript projects, Node JS backend projects, anything with a package.json.

JavaScript is a very wide domain, the possibilities of coding styles and tooling are quite vast. There is no “Ruby on Rails of JS”, and therefore the ecosystem is quite literally lacking “rails” — a guiding set of constraints that make things predictable and master-able.

The goal here is to outline some philosophy that applies across these types of projects.

The overall philosophy: use constraints to make things predictable, avoid shiny things, keep things as simple as possible.

1. Simple scripts

In your package.json, just use simple predictable values in the scripts section.

Use npm start and npm build. That’s enough.

No npm run dev or npm run start-dev npm generate && npm build-dev.

If your codebase gets big, and/or has a lot of scripts, you can put arbitrary JS files into the scripts folder.

Above all, make sure that:

  • npm start starts your application.
  • npm run build builds your application.
  • npm run test runs your test suite.


There’s no need for a dev:true flag on your library. Use process.env.NODE_ENV = 'development'.

There’s no need for process.env.NODE_ENV to be anything besides development or production.

3. Don’t use weird language features

Build tools and bundlers are helpful. But JS compilers like babel often come hand-in-hand with bundlers. This creates a problem: babel allows us to use whatever language features we want, even, perhaps, language features which are not yet part of the language.

This is bad.

babel will eventually dissapear, as JS transpilation becomes less necessary.

Aim for your code to work in both Node JS runtime and browser runtime.

Avoid special language features which are not officially part of the Ecmascript 262 specification.

4. Typescript = JavaScript with types

Building on item 3, the same goes for any TypeScript code you write. This means, for example no TS decorators.

Think of TypeScript as JavaScript with types. It’s not JavaScript with types and special language features. Stick to the spec to avoid future headaches.

You don’t want a teammate somewhere in the world or in the future feeling 😞 after trying for 6 hours to get your code to compile or run in an environment somewhere outside of your particular TS build chain of what was hot in November of 2019.

5. Avoid source-to-source compile


© 2021