Modules vs. Namespaces: What is the correct way to organize a large typescript project?

Solution 1:

tl;dr: Do not choose the past. Choose the future: Modules.

In early drafts of the ES6 modules specification, there was an inline modules notion, which then has been eliminated in September 2013. However, this notion was already implemented by the TypeScript team, in 2012, with the first beta versions of the language: it was internal modules. Then, the final specification for ES6 modules has been released in July 2014 without inline modules. A year later, in July 2015, with the version 1.5 of TypeScript, internal modules has been renamed to namespaces in order to avoid confusion with the standard.

Namespaces are a legacy feature. It won't be a part of the language ECMAScript. And the TypeScript team will continue to follow the standard. There has been no improvement regarding TS namespaces since the release of the ECMAScript modules standard in July 2014.

Cons [of ES6 modules]

• Very tedious if every class is a different file, you will have to type the same import statements over and over.
• Renaming files will break your code (bad).
• Refactoring class names won't propagate through to your imports (very bad - might depend on your IDE though, I'm using vs-code)

We can hope some improvements on these issues with future IDEs. The first one is already resolved by WebStorm.