Use Typescript in Phaser

[michaeljota]

This repo is for Phaser 3 related issues only. If you've found an issue with Phaser 2 please see the Phaser CE (Community Edition) repo instead.

This should not be used for technical support. If you're struggling trying to use Phaser then post your question to the forum, Slack or Discord channels. GitHub Issues are for bugs and feature requests only.

API errors must include example code showing what happens, and why you don't believe this is the expected behavior. Issues posted without code take far longer to get resolved, if ever. Feel free to use a site such as jsBin or CodePen to demo the problem. If we can run it, and see the error, we can usually fix it.

If your Issue contains any form of hostility it will be instantly closed and you will be blocked from access to all our repos.

Be nice. We do this for free.

---

Hi! Let me say that I'm a real fan of Typescript, and I try to evangelize as much as I can in projects that I see that they will earn really value for this.

You have several issues related to the usage of Typescript outside the project (query). Because this does not expose a definition file for Typescript, is not easy as we as developers would like.

I understand that Typescript would add somewhat complexity to the development of the project, but is important to notice that Typescript is just JS with types, and other nice features too if you would like to use them.

You currently are using JSDocs for typing, and the development setup is being made with Webpack. Even when you are not using ES features, I think that the sole use of Webpack breaks the bottom line of complexity needed for Typescript usage.

I really think that declaring Types, and Interfaces with Typescript will help the development of the project, but will ultimately help developers using this library. This migration can happen progressively, and there is not need for breaking changes for the current code.

I'll try to write a module in Typescript, and make a PR to see what you think about it. Thanks.

[photonstorm]

Please don’t expend any effort on this as we have no intentions of moving the codebase to anything else this year.

[michaeljota]

I strongly suggest you to consider this decision. I just have work in a couple of files, and already found potential unintended behaviors. I won't say that all of them will be avoid by using Typescript, but I really think that the usage will help to spot them better.

[photonstorm]

It will take months to recode the API properly in TS and there is literally no point doing it if it’s not going to be done properly. That is time we simply don’t have. There are far, far more important things to do first.

To be clear, I’m not saying no. But definitely not this year.

[michaeljota]

I would very happy to do this properly.

[photonstorm]

I honestly think you’re vastly underestimating the scale of work involved here just to do it, never mind keep pace with the current speed of development. I would urge you again to not try and take this on. If you genuinely want to help the project there are far more important things to be done, that would actually benefit all end users, rather than just a handful of them.

[michaeljota]

I have worked porting JS projects to TS before, so, I don't think I underestimate this. I have the felling that you believes this would help just Typescript users, but that's actually a false statement. There are currently several IDE and text editors, with plugins or out the box, using Typescript definitions file to help the development of vanilla Javascript projects.

This honestly won't help a handful of users, but a lot of users, using or not Typescript, if they are using any IDE or text editor with Typescript Language Support (VSCode, Sublime, WebStorm, Vim, and really large etc...) they will.

[johanlindfors]

I am sorry to hear this. I recently started to support this project through Patreon, but if Typescript support will be cut or delayed so long into the future I honestly have to reconsider my funding. Don't get me wrong, I still appreciate the hard work you are doing, but the support for Typescript has simply been the reason I've chosen to build, learn and teach using Phaser.

[txiaocao]

see config tsconfig.json

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

copy phaser.d.ts to typings/phaser.d.ts
https://github.com/photonstorm/phaser3-docs/blob/master/typescript/phaser.d.ts
my project is all use typescript and phaser , it work better..

[photonstorm]

@johanlindfors I think you're misunderstanding what is being discussed in this thread. This isn't about Phaser working with TypeScript, which it does, we've been providing and enhancing the defs for months now, it's about recoding the whole of Phaser entirely IN TypeScript, which isn't something I ever agreed to and certainly won't entertain doing this year.

[johanlindfors]

Thanks for clearing this! I'm at this moment in the process of setting up my environment, once again a very happy supporter! You rock!!!

[photonstorm]

There are some really nice v3 + TS boilerplates out there that should help speed that up for you. The defs are in the docs repo at the moment, updated each time we release a new build, and will be merged into the main repo / typings once we've happy they are more stable (mostly when we've figured out the best way to document the events), but lots of people use them already. If you do find any bugs in them, open up an issue and we'll fix it in the jsdocs, so the parser corrects it on the next export.

[vegarringdal]

Been looking at the code, looks like it would take a looooong time to rewrite this to typescript (with correct types/interfaces)
Btw, Im no expert in js or ts, so ofc I could be wrong. (not trying to start a discussion here 😂 )

Typescript have also gotten very VERY good last 12 months including vscode (LOVE VSCODE 😄 )

Maybe when @photonstorm feel Phaser 3 is stable/mostly bugfree a slow move over to typescript would something, start by having not very strict rules on types/linting and just renaming to *.ts/add any.
then gradually make it stricter over time.
JS docs would help a lot, since it says types for most stuff, so anyone could help.

@photonstorm 👍 thx for making Phaser btw, looks awesome.
Been looking at this for a while, looks so much fun to learn/be able to use.
Maybe I should try and learn my kids this(11/12 years old).
Think they might like it

[photonstorm]

Yes I love VS Code. Use it for all dev now.

Once v3 has settled down I will definitely explore converting to either ES6 or TypeScript.

[vegarringdal]

@photonstorm

look at PR I made earlier :-)
made exploring more fun
maybe ts lint/typechecker can be user as a test checker in the future :-)

[cyberhck]

@vegarringdal , I also really like TypeScript, but I don't think you should be investing time and effort on a project which don't want to make a move yet. I had a look into codebase and it's pretty huge, not to mention there are some classes which aren't es6 classes, but different type of class initialized with new Class.

Yes, benefits would be huge, also help JS users, and Typings would always be in sync, how many times you update the js and forget to update typings.

If you really really want very strong typing (because so many times JS allows you doing things which isn't very type safe), I think you should also evaluate some other project written in TypeScript, even though you try to make JS project typesafe, there MIGHT be some place, where it's not possible to provide very type safe typings. But if codebase is already in typesafe, it's a breeze.

[vegarringdal]

@cyberhck

yes, I agree that its not worth doing before its stable.
Also transforming it to ES6 classes imports first, then gradually move over with //@ts-check etc

Played around for fun to see if I could transform it to ts with a script...
https://github.com/vegar-ringdal-forks/phaser/blob/master/buildToTs.js
Not perfect, would have worked better if it was es6 :-)

[photonstorm]

I'm not going to move to ES6 and then move to TS, that's just pointless. When the time comes I'll evaluate the tooling available for both, and pick one of them.

[vegarringdal]

👍

[michaeljota]

When the time comes I'll evaluate the tooling available for both, and pick one of them.

I don't want to be mean or rude or anything, but I have to say that the standard is called ES2015, and we are mid-2018. I think the time has come. 😅

[photonstorm]

Doesn't really matter what the standard is called, even today you still can't use it natively.

[michaeljota]

I'm sorry, but you sure can use ES2015 native in most browsers, that so-called evergreen browsers (Chrome, Firefox, Edge, Safari), so that's almost 95% of the browser usage.

[hilts-vaughan]

That browser usage does not represent the reality of some very large clientele some of us deal with.

Personally, I still have users on older versions of Internet Explorer and it will stay this way for a while. I'm not the only one.

[michaeljota]

This is a game development library, I don't see any large client that needs IE6 for an ActiveX script using this.

We need to target our users, and most of the final users of something like this will be regular users with modern browsers.

[hilts-vaughan]

Seriously? IE6 with ActiveX? I support lots of customers even on IE10 with Phaser. There is more than the public Internet and if you think that your use case and public consumer statistics represent the private industry as well I ask you to reconsider and reevaluate.

If we want to talk about maybe using Babel that's one thing but if Rich only wants native and no complex pipeline than this is a perfectly sane decision.

[photonstorm]

We work with a number of very large clients that have IE9 as their baseline, which is why it has always been the baseline of Phaser and remains to be so. You can't 'code natively in ES6' and target that without transpiling. So if you're going to transpile anyway (be it from ES6 or from TS) then it comes down to comparing the tooling and features of each approach more than anything.

[michaeljota]

@hilts-vaughan That's the fate of this business, I think. If you do have to support such older browsers with this, then I don't see the point. Thanks.

[cyberhck]

dude! just because ES6 isn't supported you want to stick with this style? How about using babel?

And even if browser did support ES6, you'd still not release ES6 code to npm, you'd always transpile.

Well, if author doesn't wanna do it, then I guess it's his choice, we can all complain about about it, but if he doesn't wanna do it yet, then too bad.

Although, I do wanna point out a few advantages on using TypeScript:

• TypeSafety
• Helping people develop faster without having to look at documentation (this INCLUDES users not using typescript because a lot of IDEs just use d.ts file to show them docs right on their editor)
• Documentation, a lot of classes, instead of writing jsdocs, you can just define the type, no need for runtime type checking validation.
• You can still transform it back to ES3, ES5 whatever, so not supported natively IS really a "moo" point.
• And it's easier for other people to contribute because when it's class based and code is relatively more easy to read. One can contribute, I was looking into some files, unless I have extra 20 mins of time, I don't think I can have a look and see what it does immediately.

And just because you have client with IE9 doesn't mean you've to stick with this, you can always transpile. Which would "solve" your issue with IE9.

[photonstorm]

Did you read any of the above comments at all? Or was it easier to just weigh-in and spout the obvious?

[michaeljota]

Which would "solve" your issue with IE9.

The issue is not with IE9, the issue is IE9. Anyway, there are lots of game frameworks that uses Typescript, I just to try this one for fun. Even when I want to develop a deeper understanding of JS, not having the option is a blocker for me. But I'll guess you don't care about me, or other two leaving, because you do have some clients that actually pay you, and you do need to support them.

[photonstorm]

None of the biggest or most popular frameworks are written in TypeScript.

Most of them offer defs files which have either been generated from source or hand created, just like Phaser does. None of them have been 100% error free.

Because there seems to be a real problem with reading in this thread let me be painfully clear. Again. Because I’ve nothing better to do with my time:

1. No-one in their right mind would write a framework in ES6 and then publish it bundled in that same format, without transpiling it, because adoption is 87% at the most optimistic, never mind what clients need. So tools HAVE to be involved. Those tools weren’t even a fraction as good as they are today when we started v3.

2. Rewriting the API in either es6 or ts is a massive, massive task. Literally months of work. There are far more important things to do first. Especially as there are no benefits for end users, and questionable benefits for most devs. The only real benefit of recoding in TS is that the defs will be perfect. This is not a strong enough reason to halt production on all the things we have planned. Type safety would be useful, but the vast majority of issues we face are unrelated to that. Mostly they’re logic or structural problems, which no language protects against.

3. When the time comes we will evaluate the tooling around both options, because we’ll bundle for ES5 no matter what. Until then the defs will continue to improve.

If someone is incapable of using a framework because it’s not written in TS, good luck with that. Don’t let the door hit you on the way out. For everyone else, keep on helping improve the defs please.

[vegarringdal]

@photonstorm
Sounds like a good plan, stable engine is the most important part.
Think the thread got a bit sidetracked last week, sorry if I started this :-)

[photonstorm]

Hah, no worries. It's just frustrating because I literally couldn't have been more clear on this issue, yet still it gets misread by some.

Yes, it will be rewritten in TS or ES6 at some point but it's absolutely not a priority because of the scale of the task involved vs. other things that need doing first.

[cyberhck]

First I'm sorry if I came across as someone who wants to make this priority or someone who is very irrational and won't understand what maintainers want, that wasn't totally my intention.

As far as I understood, this would be an issue one could tackle, or at least give a try to. It didn't even have to be anyone who's actively maintaining this project, say a random joe wants to come up with something which will ensure your client's app doesn't break, and keep your tests passing.

I thought this would be an issue which will be open for community, and if someone wanted to take a look and come up with something maintainers could take a look and decide.

It didn't have to be one big task, of course everyone should understand this is a huge project, no one is going to abandon more important tasks and start converting, that'd be stupid to think.

In my mind, maintainers keep on working on what they're good at, while keeping this issue open for someone to try out. If someone finds a way to gradually convert files, while keeping compatibility, then you could decide whether or not you want to take that route.

I actually came to this issue wanting to make a PR which would migrate to more recent version of JS/TS. My plan of action was to come up with simple build which will distribute phaser in es5/es3, which is what everyone is doing anyway, (I do hope people realize all npm libraries modules published should be in es5/es3 as of now) because a lot of people don't have es6 compatible browser. "If were to come up with a way that it'll keep your customers happy and move your classes one by one, would you have a look at it?" is what I would have mentioned, I totally dropped the ball there, sorry.

BTW: I'd have to disagree your point about: "None of popular library or framework uses TypeScript", I'd have to say Angular, Aurelia, ember, vscode, monacco editor (although vscode is using monacco), native script, ionic, Babylon.js (ironic that they have js in their name), apollo client, upterm, github desktop, oclif (supposedly good cli framework), and many others, I agree that some of these might not be that popular, but I'd give them a pat on the back anyway.

But if you're saying that at no point of this project will there be both kinds of classes, then you're right, in that case it'd be have to be big task and would take a huge chunk of time (I don't think that's a good idea though)

[photonstorm]

Thank you for the clarification @cyberhck - however, I really don't want this done piecemeal, one file at a time. There seems to be no real benefit doing it that way for anyone involved. It'd complicate the work I'm doing and there is no way the community will manage to keep-up with the current state of changes in the API.

Take a look at the 3.12 Beta 1 Change Log and look at how extensive that is for just 24 days of work. It's a kind of velocity that would be really hard for anyone in the community to keep up with, and nor would I want them to try and do so. It makes a lot more sense that once the API is in a state I'm happy with that we just put all features on hold and port the entire thing to ES6 or TS.

That will happen, and I'm more than happy to do the work myself, it just simply cannot happen yet.

When I said none of the popular libs use TS I really meant game frameworks. And to be honest, other than Angular and ember, most of your examples are end-user apps. The overwhelming majority of frameworks (of all kind) just provide TS defs (if at all!), but are not written in it. This makes no difference to what I'll choose when the time comes, it just grates a little that so many people keep going on about how it should be written in TS, yet the reality of it is that very little else (of the magnitude of Phaser) actually is.

[cyberhck]

In that case it makes sense, thanks.