Feathers-Plus CLI

Generate a FeathersJS application in TypeScript

by Simon Abrams on Unsplash

Six months ago type definitions for the

FeathersJS

core packages were first published on DefinitelyTyped. Yet, TypeScript adoption never really took off among Feathers users. Why’s that? There had been various open issues about Feathers Auk and Buzzard releases lacking typings, so there seemed to be at least some demand.

Those familiar with Feathers most likely have come across the original Feathers CLI. Setting up a working HTTP- or websocket-based API is a breeze, hooking it up with a variety of database adapters of your liking in no time. Neat. Until you try to migrate your freshly created application scaffold to TypeScript and all the lovely breeziness fades away. There’s so much refactoring that needs to be done that in the end you’re better off with writing the boilerplate by hand.

In total, using Feathers with TypeScript negated a lot of the benefits the CLI would have gotten you when you’d stuck to JavaScript.

Feathers-Plus CLI to the rescue

If you’ve always wanted to use Feathers with TypeScript’s benefits without sacrificing near-automatic code generation, your time has finally come.

Another generator, Feathers-Plus CLI, has recently seen the light of day, one of its main features being the ability to choose TypeScript generation mode and even (in parts) regenerate an already generated JavaScript app to a TypeScript equivalent. Feathers-Plus CLI is designed to be similar to the original CLI in terms of both usage and generated code, so you’ll feel right at home if you’ve used the original before. If you haven’t, no problem. It’s quite simple, so let’s get straight to it.

Generating a Feathers TypeScript app

The easiest and recommended way to get things up and running is to install the Feathers-Plus CLI globally via npm (or yarn).

npm install -g @feathers-plus/cli

Once that’s done, create an empty folder in a place of your choice and cd to it. Instead of using generate app right away, we’ll have to tell the generator to use TypeScript first with the CLI’s generate options command.

mkdir myProject
cd myProject
feathers-plus generate options

The prompts are pretty self-explanatory, the one that’s important for us is Generate TypeScript Code? which we happily answer with yes. Leave the other ones alone, i.e. just use their default values by pressing the enter key.

You’ll now find a file named feathers-gen-specs.json in the current directory. Anything you generate or configure using the generator is saved in this file. Have a look if you like, but there’s not much to see yet. Let’s go ahead and generate the app.

feathers-plus generate app

Again, self-explanatory prompts. Again, just use the default values.

You’ll end up with a basic Feathers application with working REST and websockets as you know it, but in a fully set up TypeScript development environment. ts-node and ts-mocha are included, saving you further configuration for debugging and testing.

Finally generate a service called messages with the default adapter NeDB

feathers-plus generate service

(If the GraphQL line caught your eye, make sure to head over here later to read up on how the Feathers-Plus CLI makes GraphQL and Feathers play together.)

Have a look around the project, if you’ve been using the original Feathers-CLI it will look familar. You’ll find a detailed explanation of the generated files and folder structure in the docs.

You can easily run the application using npm start or ts-node src/ and our TypeScript codebase will be transpiled on the fly. This is great for development, but it’s rather slow in comparison to running JavaScript. For a production build, run npm run compile and the compiled application

Interface generation

Of course TypeScript is all about interfaces. We could create one by hand, but we’re not going to. The Feathers-Plus generator leverages service specific JSON-schemas to generate various other needed schemas, one of which is the corresponding TypeScript interface.
Open src/services/messages/messages.schema.ts and find line 24.

properties: {
  // !code: schema_properties // !end
}

You may notice many more of similar // !code: ... comments in this file and the entire project. These are needed by the generator to identify and extract the code we enter. Far from pretty, but it gets the job done. Let’s add three properties to the messages schema: Its id, its owner’s id and the text of the message. Make sure you add it between // !code: schema_properties and // !end.

properties: {
  // !code: schema_properties
  _id: { type: 'string' },
  ownerId: { type: 'string' },
  text: { type: 'string' }
  // !end
}

After that, run feathers-plus generate all to regenerate everything. Hit enter a couple of times to keep the settings unchanged. You don’t necessarily have to regenerate the entire application, you could run feathers-plus generate service just as well, but generate all is a nice shortcut.
Open messages.interface.ts now and you’ll find a TypeScript interface consistent with the JSON-schema you created. You’ll also find that the other files in the messages folder containing MongoDB, Mongoose and Sequelize schemas as well as validation functions are now fully populated.

Application interface

Take a peek at src/app.interface.ts. It contains a type named App made up of all the generated services’ interfaces. If you’ve ever wondered, why Feathers’ Application interface is generic, here’s why.

The generic Application interface can make TypeScript aware of available services’ names as well as their interfaces. Because of this app.service('messages') returns a typed service which in the end leaves you with a properly typed response:

Those who do fullstack development may get the additional benefit of importing the generated interfaces in both their server and their client codebases. Sharing common functionalities between both is a thing already and having common interfaces helps ensuring client and server adhere to the API contract even before any of the code is run. Fully configuring a fullstack project is out of scope of this article, but make sure to take a look at one of the many fullstack boilerplates like Angular-Full-Stack and fullstack-typescript (React).

Feel free to give FeathersJS and TypeScript a try and make sure to file any issues you have with the CLI, Feathers or with Feathers’ typings packages!