TypeScript Partially supported out-of-the-box

[ScreamZ]

This is the first milestone to improve TypeScript usage of xs-dev.

State of art

Currently you can run a new Ts project using xs-dev init <project_name> --typescript. This gives two thing

1. main.ts: a file with some example code
2. manifest.json: application manifest

Details

{
  "include": [
    "$(MODDABLE)/examples/manifest_base.json",
    "$(MODDABLE)/examples/manifest_typings.json"
  ],
  "modules": {
    "*": "./main"
  }
}

debugger;

let message = "Hello, world - sample";
trace(message);

At this point you can run xs-dev run inside the project folder and this will run, but there are few issues.

Issues & Questions

Not sure about

 "modules": {
    "*": "./main"
  }

What does it do exactly? Means all require inside the js file will point to ./main (only js ext ? or also .ts ?)

Once you add a package.json simple as this one

{
  "name": "my-typed-project",
  "private": true,
  "version": "1.0.0",
  "main": "main.ts",
  "author": "Andréas 'ScreamZ' HANSS",
  "license": "ISC"
}

The CLI command doesn't work anymore yielding

@HipsterBrown Poke still a punycode issue here ahah

Therefore not sure how to proceed. Currently I'm going to use my bundling toolchain with a packager. The pro is that I can easily generate a single file with all deps and eventually minify code, which is great.

But for the quick prototype this could be nice to no need to do this.

Therefore i suggest two pattern:

• Go fully on magic with xs-dev run, but this way we should choose a packager and allow use to hook on it, just like NextJS is doing with webpack/TurboPack
• Provide an example setup with Vite, Bun.build, rollup or any other packager and give an initial setup. If so @HipsterBrown I can work on a minimal sample project on Github repo.

Note

Edit : I made it : https://github.com/ScreamZ/xs-dev-Typescript-template

Tasks

• Should work with a package.json file, therefore we can include typescript typings.
• Should ship by default with Typings on the latest version. For usage
• Improve documentation for TypeScript usage (Add TypeScript usage example #187)

Related topics

Things related like PullRequest or Other issues.

• TypeScript baselining (and various things) Moddable-OpenSource/moddable#1434

[HipsterBrown]

Thanks for creating this tracking issue @ScreamZ 👍 I also appreciate the template project to help folks get started. We could add passing a URL to the xs-dev init command to create new projects from a remote git repo, which make it even easier to integrate that way of working.

Poke still a punycode issue here
This should be fixed in v0.33.1 of xs-dev, so make sure you're using the latest release. I'm not seeing it in my local usage of Node 22.11.0 anymore

As for the out-of-the-box TypeScript support, I figured out why adding the package.json caused it to not work as expected. When xs-dev detects a package.json file in the project directory during any of the commands that call mcconfig (typically build and run), it will prepend the mcpack utility to include node_modules and other modern config into the build process before compiling for the target device. mcpack does some checks while resolving the package dependencies, including verifying the project is using ESM by looking at the file type or type field in the package.json. The former check doesn't include any variation of TypeScript files (.ts, .mts, etc), so the error you've shown above occurs.

The fix should probably be implemented in mcpack rather than have xs-dev do some magic on the fly to make that work. Then the first task should be taken care of.

---

For the second task, what should ship by default with typings? xs-dev? or the typescript project template?

---

For the third task, I totally agree with improving the documentation for TypeScript usage. It would be a nice guide on the xs-dev docs if you're up for submitting a PR. 😄

[ScreamZ]

As for the out-of-the-box TypeScript support, I figured out why adding the package.json caused it to not work as expected. When xs-dev detects a package.json file in the project directory during any of the commands that call mcconfig (typically build and run), it will prepend the mcpack utility to include node_modules and other modern config into the build process before compiling for the target device. mcpack does some checks while resolving the package dependencies, including verifying the project is using ESM by looking at the file type or type field in the package.json. The former check doesn't include any variation of TypeScript files (.ts, .mts, etc), so the error you've shown above occurs.

Wasn't aware of mcpack and not sure how it could fill with the setup I'm designing here with the bundler. I should report the topic to the moddable team. (That's where a discord server between them and us could be a nice idea :D)

For the second task, what should ship by default with typings? xs-dev? or the typescript project template?

I don't have a closed opinion on the subject, but currently, the template file from the xs-dev CLI is only creating two files, and there are no typescript types included.
It looks hard to me to implement more from template string generation and a good solution would be to pass a github URL to the init, this is the most flexible way to deal with this point i guess.

For the third task, I totally agree with improving the documentation for TypeScript usage. It would be a nice guide on the xs-dev docs if you're up for submitting a PR. 😄

I'll work on it.