TypeScript recommended project structure with modules

Question

I am a TypeScript beginner, but I have development experience in Java, and I'm wondering what is the recommended file structure for writing in TypeScript - especially when it comes to modules.

Let's say that I have several modules: ui.dashboard, ui.models, util.events, and util.common.

Each of these modules may contain several classes. In Java I would have the following file structure (where <base> is a base package for the project e.g., com.my.app):

src/<base>/ui/dashboard/<file per class>
src/<base>/ui/models/<file per class>
src/<base>/util/events/<file per class> 
src/<base>/util/common/<file per class>`

On the other hand, in TypeScript I see two main ways to accomplish the same thing:

Flat design:

src/ui.dashboard.js
src/ui.models.js
src/util.events.js
src/util.common.js

Here each file contains a module definition with all the relevant classes. This is OK, but then the files become huge and harder to manage.

Hierarchical design

In this design I would organize the files just like in Java, but since TypeScript (to the best of my knowledge) does not support declaring modules across files, I will have to write a gulp/grunt task that will combine the files into modules in build time.

As a Java programmer, this looks much more elegant, but then I lose some tooling support since the modules are not actually defined until build time, and therefore are not visible to the editor/IDE.

What is the recommended way to work?

thoughtrepo · Accepted Answer · 2015-09-10 17:36:55Z

3

Use both :) ES6 supports both named exports and default exports so both designs can be used as necessary.

The overall structure of the project should use the hierarchical design for the reasons you stated, but flat modules should also be used as necessary. Especially for packages that will be incorporated into other codebases.

For example:

src/ui/dashboard/Class1.ts
src/ui/dashboard/Class2.ts
src/ui.dashboard.ts

The src/ui/dashboard/Class1.ts file would look like:

export class Class1 {}

The src/ui.dashboard.ts file would look like:

import {Class1} from './ui/dashboard/Class1';
import {Class2} from './ui/dashboard/Class2';

export default {
    Class1: Class1,
    Class2: Class2,
    randomFunction: () => {},
}

However, when in doubt fallback to default exports.

ECMAScript 6 favors the single/default export style, and gives the sweetest syntax to importing the default. Importing named exports can and even should be slightly less concise. https://esdiscuss.org/topic/moduleimport#content-0

edited Sep 10, 2015 at 17:36

answered Sep 10, 2015 at 16:06

thoughtrepo

8,4132 gold badges30 silver badges21 bronze badges

Sign up to request clarification or add additional context in comments.

2 Comments

JobaDiniz Over a year ago

Can you elaborate on "fallback to default exports"? Give an example if possible

JobaDiniz Over a year ago

also, export default does not work for interfaces

johanmynhardt · Accepted Answer · 2024-11-20 20:01:35Z

I've just been through (actually still busy on) a journey to reactor a rather challenging codebase and along the way I've started putting some rules or guides in place:

flat file structures are not too great - plan for the future and consider what the experience would be if your code blows up to over 200 files, the mental modal becomes painful to maintain
keep logical parts together (there's no right or wrong way, it depends on your project)
look at conventions by established bodies, like Google
don't use default exports, for the love of code! It opens the door to unintentional code duplication, or rather, when using named exports it will alert you when something of the same name already exists
use barrel files to help organising files that belong together
use .js extensions in imports - ugly, I know, but it's a standard. Look at TypeScript's own codebase. This helps greatly when you're trying to get rid of CommonJS code and running on Node.js and you wish to use ESM. (That's a story for another day)

There's likely more, but I'm still busy with this process and was actually looking for more guidance when I reached this post :-)

Collectives™ on Stack Overflow

TypeScript recommended project structure with modules

Flat design:

Hierarchical design

2 Answers 2

2 Comments

Comments

Your Answer

Hot Network Questions

Collectives™ on Stack Overflow

Flat design:

Hierarchical design

2 Answers 2

2 Comments

Comments

Your Answer

Sign up or log in

Post as a guest

Related