Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Add typescript support and migrate function example #782

Open
wants to merge 1 commit into
base: master
Choose a base branch
from
Open

Add typescript support and migrate function example #782

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
44 changes: 44 additions & 0 deletions docs/decisions/0009-introducing-typescript.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,44 @@
# Introducing TypeScript

## Status

Accepted

## Context

TypeScript is a strongly-typed superset of JavaScript that adds optional static type checking, class-based object-oriented programming, and other features to JavaScript.

As we start to expand the scope of the data that Learner Portal uses, the limitations of plain Javascript are coming more into focus. In order to support a changing landscape of course data, we would like to introduce TypeScript into the code base to facilitate the documentation and refactoring process.

Here are some of the advantages of TypeScript over JavaScript:

### Type safety
TypeScript helps catch errors at compile-time instead of runtime by adding type annotations to variables, functions, and classes. This can help prevent errors that might occur when dealing with large codebases.

### Better tooling support
TypeScript has better tooling support than JavaScript, with features like code navigation, auto-completion, and refactoring tools in popular code editors like Visual Studio Code.

### Improved code organization
TypeScript's class-based object-oriented programming model allows developers to organize code in a more structured and maintainable way.

### Easy adoption
TypeScript is a superset of JavaScript, which means that any valid JavaScript code is also valid TypeScript code. This makes it easy for developers to adopt TypeScript gradually, without needing to rewrite their entire codebase.

### Community support
TypeScript has a growing community of developers who contribute to its development, create libraries and tools, and provide support to other developers. This makes it easier for developers to learn and adopt TypeScript.

## Decision

We will prioritize using TypeScript in the following places:
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Two thoughts:

We already have support for typescript in frontend-build; I don't see a corresponding ADR there. I like the idea of moving this ADR into frontend-build to explain why we added typescript after advocating against it for a number of years. We've already made the choice to go for it more systemically, adding typescript to this repo may not even be ADR worthy unless there are some specific reasons we want to be early adopters for this repo.

Related to this specific "Decision" section - My feedback here is that I've found the most utility in using typescript in data/API/state layers, and it feels less useful in React components because it tends to get really complain-y and requires you to annotate all the internals of React for very little benefit. I assume most of our react components are already using PropTypes, too, which gives us some level of safety/checking there. If it were me I might write some of that nuance into this ADR.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Created ADR in openedx/frontend-build#412

* New code files
* Existing API endpoints (and their payloads)
* Components or Functions take a lot of parameters, or use parameters that are themselves complex objects

## Consequences

* Code that requires heavy contracts, whether that's functions/components with lots or parameters, or complex objects returned from backend API's, will become much more comprehensible and easier to work with in a modern programming IDE
* Because TypeScript is a superset of Javascript, the code does not need to be migrated all at once, but can be updated to TypeScript during the course of regular feature work.

## References

* https://www.typescriptlang.org/
Loading