Introduction

Join the chat at https://gitter.im/floyd-framework/cli

Floyd is a framework for building GraphQL backends, with first-class support for Typescript.

Why

REST APIs are cumbersome to build and even tougher to deal with (for frontend developers). GraphQL eliminates most of the problems developers face while building and using APIs. See more benefits of GraphQL here.

Features

1. Zero config

You won't have to spend time searching and downloading packages and then setting them up just so you can get started. Floyd will do all that for you so you can hit the ground running and start writing your application logic.

2. Components

Floyd will split your application code into separate components so that the logic remains easy to understand and maintain.

3. Playground

Use GraphQL Playground to test your API in development environment. You won't need to install and config any client just to explore your API.

GraphQL Playground

Getting started

Install the Floyd CLI

using npm:

npm install -g floyd-cli

or using Yarn:

yarn global add floyd-cli

Create your project in any directory you want using the create command:

floyd create <name> <path>

For example:

floyd create hello-world ~/playground

will create your project in ~/playground/hello-world/

Learn more about the command here

Compile your Typescript code

Typescript cannot be executed directly from your terminal. You would need to compile it into JavaScript, like so:

npm run build

Start your server and check out the playground

Now that you have compiled your code, you can simply run it, like so:

npm start

Now visit localhost:3000/graphql in your browser to test your GraphQL API using GraphQL Playground. It will look like this:

Enter GraphQL queries on the left and see their result on the right

Concepts

Floyd only has a few concepts you need to understand to get up and running with it. It is made to be as simple as possible to pick up and use.

Components

A Floyd app is divided into multiple components, with each component having its own Schema, Resolvers and Model.

  • Schema: It is a GraphQL schema with its own queries, mutations and subscriptions. Learn more here

  • Resolvers: These are the functions you write in code that map to the queries, mutations and subscriptions you have defined. Learn more here

  • Model: This is your Database model for your component. It is the M in MVC. In this file, you specify your model's database schema and export the model object.

Typescript

One of the advantages of GraphQL over REST is you can define beforehand exactly what the type and structure of the response data will be. We wanted to extend this feature into all your app's code and hence we chose Typescript. Typescript helps you avoid a lot of the errors that might encounter during runtime in Javascript simply because you used the wrong type of object or didn't know what members the object has. Learn more here.

Project structure

Floyd has a simple and recognisable project structure so when you pick up someone else's Floyd app to maintain or contribute to, you feel right at home.

.
├── app
│ ├── app.config.json
│ ├── components
│ │ └── cat
│ │ ├── model.ts
│ │ ├── resolvers.ts
│ │ └── schema.graphql
│ ├── db.ts
│ ├── helpers.ts
│ ├── index.ts
│ ├── resolvers.ts
│ └── schema.graphql
├── LICENSE
├── package.json
├── package-lock.json
├── README.md
└── tsconfig.json

The app folder will contain all the code for your backend.

  • app.config.json will contain all your configuration options, like database URL, name of all the components, etc.

  • The components folder will contain all your components, each in its separate folder by name.

  • schema.graphql will contain the global types of your schema, i.e. types needed by more than one component's schema.

  • Similarly, resolvers.ts will contain all the global resolvers that you might need, just make sure none (neither global nor component specific) of your resolver names collide, since all of them will be made available in the same scope.

Contributing

For a guide on how to contribute to this project, click here.

Code of Conduct

Coming soon