grapesjs
grapesjs copied to clipboard
GrapesJS
[Feature request]: Typescript declarations
This is an amazing project! Thanks.
Would it be possible to get typings for Typescript? It would make life a lot easier for the project I am working on.
Thanks so much!
If someone starts working on this, poke me please, we might be able to give a hand here and there... Would really love to have typings for this project
I have started this. I'll let you know in case I finish/abandon my work.
I will mainly address the public API.
This might take a little bit longer because dts-gen is not compatible with grapesjs, not even the browser version. Thats why I have to make everything by hand.
As a result I am not sure if it will be accepted in official types repository.
So far I have created the definition for configuration objects and the grapesjs editor itself. Here's the current document
The last few classes should be finished today. Testing and validating types are the biggest tasks on this. The configuration can already be tested by placing the file DefinitelyTyped/types/grapesjs/index.dts at node_modules\@types\grapesjs\index.d.ts
There are still definetly some types wrong where I have put instead of Backbone.Model an Object and instead of Backbone.Collection an Array.
Thanks @Rottohawkins really appreciate your work
dts-gen is not compatible with grapesjs, not even the browser version
Can you elaborate on this? Can I help somehow with this point?
@Rottohawkins great job!
I noticed that you are missing plugins and pluginsOpts in EditorConfig
Thanks, I had already included those properties, but I have not uploaded the current draft yet.
@Rottohawkins Do you have any updates? Any response from DefinitelyTyped? :)
@tristanMatthias @artf I think using react, Vue to replace backbone will involve more people in open source projects, backbone learning materials are too few, and writing code is not elegant enough, purely personal understanding.
Can somebody explain its own opinions about declaring types inline or externally (like in DefinitelyTyped)? I think the inlined declaration will be obviously easier to maintain/update but I don't really like the idea of switching from "js" to "ts", seems the same story of CoffeeScript, another brick in the javascript fatigue and another barrier for contributors. If you agree, do you have a solution to this issue?
I think converting the project to typescript at this point (with the backbone usage) would really be a pain, even though it would be the easiest way of maintaining it and it would prevent eventual mistakes when type definitions and the code go out of sync (this sometimes happens).
But back to your question for inline/DT definitions.
In the majority of cases (and I believe most will agree), it is better to provide definitions as part of the library rather than through DT if the maintainer is not against it. DefinitelyTyped helps TS users to provide definitions for projects where maintainers are not interested in typescript themselves, or don't want to have TS as part of their project and don't want to maintain it (this is not always the case as some (many?) DT packages are maintained by the project maintainers as well). Note that you can also just add DT package as a dependency of your own project if someone else maintains it.
However, I see a few advantages of having definitions as part of the project:
- When the code changes, it is easier to keep the definitions in sync
- the library version and the definitions should match (again, mistakes happen) as they are all in one place with the code and versioned together
- If contributions are made, Types can be a part of the PR and easily checked with the corresponding changes
- Library users can just install your package and have definitions out of the box
- It may help you with development of your own code as you will already have the definitions for the code you write (though you will need to update defs whenever you update function signatures for example)... and although IDEs can help you if you have proper JSDocs, they could help you better if you have type definitions.
Since you mentioned CS, have a look at the following comparison: https://trends.google.com/trends/explore?date=all&q=%2Fm%2F0n50hxv,%2Fm%2F0hjc5m0
There is a reason TS is gaining this popularity (well it already gained enough to be honest) and why all the major frameworks are switching to it. It just makes development more straightforward and prevents a lot of mistakes, especially when using third party code. Not having types can also be a deal breaker for TS users. When we choose packages, we always go with TS first... Your project is an exception :)
However, you are correct that it may prevent contributions from non-TS users, although it needs to be considered that it may enable more contributions from TS users. From my point of view, not only it is easier to contribute to a project written in TS, but it also prevents a lot of mistakes that can be introduced with code changes.
Note that I am not trying to convince you of anything, just trying to share some love of TS :) I was afraid of it before we started using it about a year ago... And now when I see a piece of JS code I have to maintain I cry a little.
I totally agree with @Sharsie. Having definitions as part of the project would help a lot when integrating or extending the functionality of grapsejs (that's what I am doing/struggling a bit with now :-) ).
I know it is a huge step and lot fo work but it will also help you yourself maintaining your codebase as well.
And using TS is definitely not the same kind of path as it has been with CoffeeScript before.
Anyway, keep up the good work, amazing project!
@Rottohawkins Any news on TS definitions? Looks like it's not there at DefinitelyTyped yet.
I know it is a huge step and lot fo work but it will also help you yourself maintaining your codebase as well.
I'm totally in for the typed approach and I agree with you guys, undoubtedly everyone would agree on the benefits, just would like to make the adoption as smooth as possible.
Is it possible (and if it would make sense) to create definitions in parallel to the source? Eg. if I have 'myFile.js' I'd need myFile.ts file in the same directory
@artf No you don't. You can simply have definitions as separate files in DefinitelyTyped. The users can install them with a command like this:
npm i -D @types/grapesjs
@mamal72 I think we are over that question now :)
@artf It could be possible to do what you want, but I think it does not work out of the box, it might need some setting up and you might have to read up on this.
Just to make sure I got your question right, you want to have definitions, NOT newly written typescript code in the myFile.ts, is that correct?
Definitions reside in files ending with .d.ts and unless it is somehow possible to setup in a different way, the common sense is to put them in a directory types in the project root (or src/lib) and then the types dir is referenced in package.json in files key... have a look how vue does it for example:
https://github.com/vuejs/vue
It should be also possible to generate declaration files from JSDoc, but I never tried that approach.
If however you are asking about migrating files to typescript, then you can just rename your .js file to .ts file... any javascript is valid typescript. You will ofcourse get errors from typescript compiler, but these can be ignored until the migration process is complete. You can read more about migrating here https://www.typescriptlang.org/docs/handbook/migrating-from-javascript.html
@artf would you support moving to typescript? I'm interested in this upgrade and can help, but I'd rather go from .js -> .ts than make .dts files.
A little perspective, the typescript transition typically happens according to the process @Sharsie outlined in the typescriptlang handbook. Even a partial upgrade is often immediately helpful to engineers using editors with autocomplete or IntelliSense.
In my opinion, adding typescript is especially useful for a configuration heavy project like this one and may make it easier for new developers to get started.
Edit: Reread the thread and realized @artf is interested in types. I think that transitioning js -> ts is actually the least turbulent way of doing it.
Would love to see TS declarations as well. TypeScript is becoming fairly standard / essential for production codebases
However... I would much prefer to see Kotlin declarations =). I've actually started it locally.
I don't know if this will work for everyone. I made it in a hurry for one of my projects, and it's working, but that's about all. I haven't tested every feature using this. I took if from one of the examples several months ago, so I apologize, but I can't remember which one. I believe it was from the the source of of the demo found here https://grapesjs.com/demo.html.
Anyway, I hope this gist helps. https://gist.github.com/scottpage/7a2b04de7f54b90e6bf1b92f35f30b5f
LOTs of uses of that evil any, so there's still more to be done. At least I don't have any errors that show up, so there's that.
@artf As others have stated there are ways to make a typscript enabled project without doing an overhaul. One way is to type your code and start that by doing a mass conversion of the codebase from .js files to .ts file and running tsc in your deployment pipeline. Everything should run the same.
The alternative, also proposed, is to make separate files for type definitions with the extension .d.ts. Manually completing this process would not be advised as now you have code segregation. On the other-hand, you can once again make use of the typescript compiler and generate the definition files from JSDoc.
The first option brings in more typescript developers under the fold. The second option does not exclude the non typescript developers in the javascript space. Both options, when done right, bring typescript support without the need to manage two code bases.
Is there any news on this PR? i'm not very familiar with rewriting javascript to typescript, but i could possibly help
I just updated my gist based on changes I needed during use in Vue and React. Shouldn't matter which front-end, since this TS typing file is for GrapesJS and front-end agnostic.
GrapesJS TypeScript grapesjs.d.ts
A few updates and my help requests for the Typescript migration (which I'd like to fully support):
- I added already the tsconfig in the project and also the support for .ts files in grapesjs-cli (on which we already rely)
- [Solved in v3.0.0] ~~I still didn't figure out how to bundle all types in one single file for the build (I've tried with mainly suggested webpack plugins but nothing worked properly on my side) and I guess that's the only proper way to bundle them with the final package/build, right? This is something that should be solved in grapesjs-cli in order to support also any other plugin.~~
- I don't know which would be the best way to organize this migration but I'd start by suggesting PRs split by modules (eg. one PR for all
/asset_manager/*files) or even module directories (eg./asset_manager/model/*files). This would help to speed up the review process and reduce the number of conflicts. If you decided to migrate some module/directories, please check and post it here before starting, so we won't risk having multiple PR for the same files.
Update: I'm adding the declaration file provided by @erdomke as index.d.ts as it's a really good start and a good alternative before the full migration. Thanks Eric ❤️