TypeScript baselining (and various things)

[ScreamZ]

Foreword

Hi Moddable team,
this is my first contribution to this awesome project so I want first to thank you for your awesome work! The tool you made so far is really awesome and I'm pretty sure this could be an industry game changer like React Native did on it's own. Projects are really similar in terms of concepts and I'm pretty sure we can take inspiration for various things for Expo https://expo.dev/ in terms on how they work for the developer experience and things.

Damn this is soooo cool to write JavaScript to program my MCU, I was dying with C/C++ restriction as a 10 years+ JS developer.

That being said, I'm working in conjunction with @HipsterBrown on xs-dev to try to improve the developer experience and the onboarding on the moddable SDK. The technology is awesome and the big brake on adoption is the learning curve and documentation that is very split on many side and not always up-to-date.

State of art

Currently I'm working on having a minimal full-typescript example with multiple module management that work on the stack. I've identified some issues and things that are being tracked here HipsterBrown/xs-dev#186.

I wanted to open this topic so we can discuss about current issues on the TypeScript typings and how we could improve that, so let's start.

Here are so postulates:

• Most of the tools/library exposed by Moddable SDK are provided as what I would call « Build Injection », meaning they are injected on build time based on the manifest.json.
• The ideal goal would be to add them as library managed by the package manager, as I said earlier you can take a look at expo components, but I agree this would be a lot of work, so for the first draft we can keep the first postulate that they remain injected on build. If so, each package would expose its own typings, like regular package using the types property of its package.json
• Typings are provided as an independent package, not hosted on https://github.com/DefinitelyTyped/DefinitelyTyped

So what could be expected?

Starting my prototyping, it was clear that typings once installed with any package manager (in my case pnpm but could be any) are not loaded by default. This is because Typescript only resolve package-free typings from a node_modules/@types folder. And this is the folder for dependencies managed by https://github.com/DefinitelyTyped/DefinitelyTyped.

A first proposal could be to host those typings here. But we can work around.

The second proposal and the correct way to manage this could be to use the typesRoot property of the tsconfig.json file just like so:

{
  "compilerOptions": {
    "typeRoots": ["./node_modules/@moddable/typings", "./node_modules/@types"],
  }
}

But sadly, with the current state of art, the ts compiler yield an error

Therefore the only way to proceed at the moment is doing so (with an example from my repo)

{
  "compilerOptions": {
    "incremental": true,
    "outDir": "dist",
    "lib": ["es2022"],
    "module": "es2022",
    "sourceMap": true,
    "target": "ES2022",
    "types": [
      "./node_modules/@moddable/typings/xs",
      "./node_modules/@moddable/typings/mcpack",
      "./node_modules/@moddable/typings/websocket",
      "./node_modules/@moddable/typings/wifi",
      "./node_modules/@moddable/typings/global",
      "./node_modules/@moddable/typings/embedded_provider/builtin",
      "./node_modules/@moddable/typings/embedded_io/digital"
    ]
  },
  "include": ["src/**/*.ts", "src/main.ts"]
}

The issue is that you need to specify all files manually, and then all deps of required file, example for the global typings, i had to add embedded_provider/builtin and embedded_io/digital.

This get a bit cumbersome.

What's next

I just wanted to land this topic, and discuss about you if you're planning anything already in the pipe about this, or if we can help on improving the workflow about that.

Thanks,
Andréas

[ScreamZ]

Created a https://github.com/ScreamZ/xs-dev-Typescript-template

[ScreamZ]

Added documentation HipsterBrown/xs-dev#187

[phoddie]

Hey, welcome!

Glad you have having fun getting started. Real, modern JavaScript is definitely a great way to work on embedded. Doing everything in C / C++ is just unnecessarily arduous. And your feedback is much appreciated.

We're big fans of xs-dev. It does a wonderful job of streaming-lining common development tasks. We've been supporting @HipsterBrown from early on.

It seems like you want to use npm packages. Our mccpack tool is for precisely that. It is basically a front-end to mcconfig that builds the manifest for you from the relevant packages.

Supporting TypeScript is easy and hard. Because we support full, standard, modern JavaScript TypeScript "just works". Even debugging "just works" thanks to source map support in our tool chain, including the debugger. The hard part is that there are so many ways that developers work with TypeScript -- there is no single way to integrate TypeScript into a build that works for everyone. We don't want to take an opinion on the "right way" to use TypeScript but rather we want to support the way developers want to work with TypeScript. We've very open to input there.

Regarding typings, we publish typings for the Moddable SDK to NPM for every release so you can npm install them from @moddable/typings.

[ScreamZ]

Supporting TypeScript is easy and hard. Because we support full, standard, modern JavaScript TypeScript "just works". Even debugging "just works" thanks to source map support in our tool chain, including the debugger. The hard part is that there are so many ways that developers work with TypeScript -- there is no single way to integrate TypeScript into a build that works for everyone. We don't want to take an opinion on the "right way" to use TypeScript but rather we want to support the way developers want to work with TypeScript. We've very open to input there.

Regarding typings, we publish typings for the Moddable SDK to NPM for every release so you can npm install them from @moddable/typings.

Thanks for your answer.

I understand you don't want to be opinionated, and I agree there are many way. But coming from a web background it's sometimes complex to use your tool, which reduces adoption possibilities. I guess we could at least opinionate on the xs-dev side, so it's easy for web developers to bridge to IoT.

As a simple example, the way to include TypeScript typings by having to add specific file for specific modules each time is really cumbersome. It requires to search and apply.

If package were published on https://github.com/DefinitelyTyped/DefinitelyTyped they would have been automatically loaded, this has no overhead in terms of performance as it is not bundled. It's only IDE-based.
They can also be added by hand with the following syntax:

{
  "compilerOptions": {
    "typeRoots": [
"./node_modules/@moddable/typings", // Types from moddable SDK
"./node_modules/@types" // TS default 
],
  }
}

But the way they are designed currently prevent this from happening. As I mentioned in the above post. Maybe we could work on fixing that.