CODEWITHSUNDEEP
typescript
bennyl
bennyl

Reputation: 2946

TypeScript recommended project structure with modules

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?

Upvotes: 7

Views: 6060

Answers (2)

johanmynhardt
johanmynhardt

Reputation: 300

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 :-)

Upvotes: 0

thoughtrepo
thoughtrepo

Reputation: 8383

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

Upvotes: 3

Related Questions