Keystone: Using Typescript to build my backend

[thekevinbrown]

Feature request

Is your feature request related to a problem? Please describe.

I use Typescript in general on my applications. I can't find documentation or types I can use to be able to produce a Keystone application using Typescript.

Describe the solution you'd like

Whether Keystone uses Typescript internally doesn't matter that much to me as a consumer of the library, but it'd be nice to be able to use Typescript and have that fit neatly into Keystone's build process.

Describe alternatives you've considered

The alternative is to use JS in the backend and Typescript everywhere else, which is what I'm currently doing, but would like to stop.

[timleslie]

Hey @thekevinbrown, thanks for raising this as an issue. It's something that is definitely at the back of our minds, but it is yet to make it to the top of the priority list, so hearing this request will help to move the needle on that. If you or anyone else reading this have any thoughts on what shape a solution might look like we'd love to hear them 👍

[MadeByMike]

Hey Kevin, We have an issue discussion whether Keystone should use Typescript internally #1373 if this is different is it about having an npm script that will transpile backend code before to passing to Keystone for execution?

Have you tried starting Keystone with a custom server rather than the CLI? It sounds pretty doable to write a backend typescript and still use Keystone. Unless I am missing something?

[thekevinbrown]

@timleslie, sounds good. The shape of the solution I'm after is:

• I could use index.ts to spin up Keystone and the arguments to new Keystone() would be typed.
• I could define my lists, permissions, and custom components in Typescript, again with types on the parameters.
• Running keystone dev, keystone build, or keystone start would process the Typescript in some way, either with ts-node or webpack / parcel / et al to result in a usable backend and admin UI.

@MadeByMike, I've already fed back on that issue. When you say "custom server", do you mean not using Keystone's backend at all and only using the admin UI, or are you talking about some other way of setting up the backend?

Edit: @MadeByMike I missed custom servers in the docs, that makes sense.

[thekevinbrown]

I should mention that if you're not going to transition Keystone itself to using Typescript, I could contribute a set of type files pretty easily, the hard thing for me to manage is how Typescript fits into the build process for both the Admin UI and backend in a supported way.

[jesstelford]

@thekevinbrown It sounds like there are two discreet steps here:

1. Export TypeScript types for Keystone's packages.
2. Provide a mechanism for the keystone command to execute .ts files as well as .js files.

If so, it would make sense to split this issue up. In particular, I know that 1 is something we may support in the future, but 2 is not something we've even considered.

[thekevinbrown]

@jesstelford, no worries, I'll get started with a custom server and my own local types for now. If you guys decide to transition to Typescript in #1373, there'll be no need for those, otherwise if I get to the place where there's something useful for the community in general I'll contribute them to Definitely Typed as a first step so the team doesn't have to manage them at all.

Unless you see a reason to open the other issue now, I think it makes sense to wait until things settle before we contemplate updating the CLI for first class TS support, as it seems like you've got many bigger fish to fry.

[thekevinbrown]

https://github.com/DefinitelyTyped/DefinitelyTyped/issues/40147

I can also confirm that a custom server with ts-node and my (very skeleton) local types works fine.

[tclain]

I would very intestered in contributing ts definitions as well @thekevinbrown. I think it is a must have at least given the tremendous editor support. Let me know if I can help in any way

[MadeByMike]

If someone can create an example typescript project (minimal boilerplate with a custom server I assume) I'll add it to the CLI. I think that would be a great step.

My one question about adding types for projects to consume is that if we are not using them internally they could easily fall behind with changes? I assume we'd need to do some work to builds\CI to ensure this was maintained. cc/ @mitchellhamilton

[thekevinbrown]

@MadeByMike, unless you guys are using Typescript yourselves or otherwise autogenerating the types from another typing system, they can and will fall behind. The nice thing though is that DefinitelyTyped makes it very easy for maintainers of types to push new versions and accept PRs, so types that are used frequently tend to very much track the core package. There's no automatic fix for this unless you guys either use Typescript in the package or script the creation of Typescript types from another typing system.

Since there's resistance on training the Thinkmill team up on Typescript, there's already a gap that needs covering for Typescript users, so this is an easy way to just keep everything untangled and support the Typescript community without you guys having to do anything differently or take over any maintenance of anything. In the future we could package these definitions with the core packages, but that requires you guys to maintain them, so I think this is a good first step.

[thekevinbrown]

@tclain I've published what I was working on locally with usage instructions so we can collaborate:
https://www.npmjs.com/package/keystone-typescript-types
https://github.com/TechInSite/keystone-typescript-types

As I said, they're really rough, but they're enough that I have a server running in dev. I want to continue to expand the types and get rid of any. Please feel to expand those and PR changes back to your heart's content. When it's starting to feel like they're a solid v1, I'll PR it back into Definitely Typed.

[tclain]

@MadeByMike, unless you guys are using Typescript yourselves or otherwise autogenerating the types from another typing system, they can and will fall behind. The nice thing though is that DefinitelyTyped makes it very easy for maintainers of types to push new versions and accept PRs, so types that are used frequently tend to very much track the core package. There's no automatic fix for this unless you guys either use Typescript in the package or script the creation of Typescript types from another typing system.

Since there's resistance on training the Thinkmill team up on Typescript, there's already a gap that needs covering for Typescript users, so this is an easy way to just keep everything untangled and support the Typescript community without you guys having to do anything differently or take over any maintenance of anything. In the future we could package these definitions with the core packages, but that requires you guys to maintain them, so I think this is a good first step.

I agree with @thekevinbrown whole-heartedly.
I know that rewriting the project in typescript is not practical nor always feasible.
This said providing ts definitions is really a vital step to spread adoption IMHO. Even for people consuming the lib from javascript, the IDE will benefit from rich autocompletion insights.

Sure it will require someone to update the ts definition, but keep in mind that is effort could only affect your public api for now. as long as fonction signatures matches, the effort will be incremental.Keeping ts definition in sync help the project to have a clear, documented public api, I personnally think that`s a good thing.

alongside @thekevinbrown I will help to bring definitions to a usable state. From there, providing an example custom server will be trivial.
Thanks for the good work folks !

[tclain]

@thekevinbrown and I have started an effort here: https://github.com/TechInSite/keystone-typescript-types .

we now have basic support for the following packages:

• [x] @keystonejs/keystone
• [x] @keystonejs/fields

APPS

• [x] @keystonejs/app-admin-ui
• [x] @keystonejs/app-next
• [x] @keystonejs/app-nuxt
• [x] @keystonejs/app-static

FIELD ADAPTERS

• [ ] @keystonejs/file-adapters
• [ ] @keystonejs/oembed-adapters

AUTHENTICATION STRATEGIES

• [x] @keystonejs/auth-password
• [ ] @keystonejs/auth-passport

UTILITIES

• [x] @keystonejs/list-plugins
• [x] @keystonejs/apollo-helpers
• [x] @keystonejs/email
• [x] @keystonejs/logger
• [x] @keystonejs/session

DATABASE ADAPTERS

• [x] @keystonejs/adapter-knex
• [x] @keystonejs/adapter-mongoose

[MadeByMike]

@thekevinbrown & @tclain this is awesome, thanks!

I want to let you know that there is no real resistance on our part, most of the Thinkmill staff know how to use TypeScript and some are even big advocates for it. When I said "using internally" I meant on the Keystone project, core maintainers and other significant contributors.

We're a really small team and, as much as we'd like to be, none of us are full-time on Keystone. Any extra work, whatever the benefit, is extra work. Unless we have someone maintaining types and focused on this until it's well integrated into our workflows there's a good chance it could impact momentum.

Regarding TypeScript helping "spread adoption", this goes both ways. I can see how Types are a draw card for some developers but a full TypeScript codebase can can be off-putting to other types of contributors that we want to feel equally welcome.

For these reason we have to think carefully before we make a move.

That said, I don't want to look a gift horse in the mouth so if you're offering good PRs with free types I can't wait to have a deeper look. What you've done looks like the right approach for now.

Thanks for the discussion and contributions :) This is great!

[tclain]

@MadeByMike, thanks for your answer, rereading my message made me realize that the projected tone was not what I had in mind. I apologize if it seemed aggressive or implied a lack of will from your part, that really wasn't my thought.. I really appreciate the job you do folks !

It is a blessing for us to benefit from your work on keystone, and as stated before, I know that rewriting everything in typescript is not a panacea.

As library maintainers you have a fair share of decision to make, and keeping everyone welcome is a challenge !

Personally I will be using keystone with typescript so if I can do anything to help, I will do it with pleasure, I see it as a way to help with the documentation, only in that case documenting types :-).

Take care.

[gautamsi]

It is not that hard to convert to TypeScript, see #1454 and #1460

That said, one day we will have it in TypeScript. Not sooner as I like but I am relentless :smiley:

[thekevinbrown]

https://github.com/DefinitelyTyped/DefinitelyTyped/pull/40316

[thekevinbrown]

The types are now live on @types/keystonejs__(whatever)

I’ll prepare a sample project when I get a chance.

[stale[bot]]

It looks like there hasn't been any activity here in over 6 months. Sorry about that! We've flagged this issue for special attention. It wil be manually reviewed by maintainers, not automatically closed. If you have any additional information please leave us a comment. It really helps! Thank you for you contribution. :)

[thekevinbrown]

For the maintainers, probably makes sense to provide a sample project for the community. I haven't had a chance to make this yet.

[abhijithvijayan]

@thekevinbrown So typescript is supported right?

I am about to migrate from v4 to v5

It would be again difficult to migrate to typescript if I go with Javascript

[thekevinbrown]

@abhijithvijayan we have a set of types up on DefinitelyTyped, and we're using Typescript with our keystone projects.

It's not officially supported by the project maintainers but it works well.

[abhijithvijayan]

@thekevinbrown Only if there were an example project for this!

There are a lot of ToDo's on types packages.

I will be submitting PRs with changes to the packages.
Please review as you are the author in DefinitelyTyped

[stale[bot]]

It looks like there hasn't been any activity here in over 6 months. Sorry about that! We've flagged this issue for special attention. It wil be manually reviewed by maintainers, not automatically closed. If you have any additional information please leave us a comment. It really helps! Thank you for you contribution. :)

[thekevinbrown]

It looks like the main thing outstanding here is an example project. We're using this in production with TypeScript, but have not yet had a chance to do an example up.

[abhijithvijayan]

@thekevinbrown exactly

[stale[bot]]

It looks like there hasn't been any activity here in over 6 months. Sorry about that! We've flagged this issue for special attention. It wil be manually reviewed by maintainers, not automatically closed. If you have any additional information please leave us a comment. It really helps! Thank you for you contribution. :)

[paulkre]

Any news on when Keystone will have full TypeScript support?

[gautamsi]

more update on this https://keystonejs.slack.com/archives/CAXTZ552S/p1607757728032200?thread_ts=1607326247.030600&cid=CAXTZ552S

[paulkre]

Is there a way to access the Slack without a @keystonejs.com or @thinkmill.com.au email address?

[thekevinbrown]

@paulkre: https://community.keystonejs.com/