[Track 2/9] GraphQL Setup

[taki-tiler-server[bot]]

Step 1/5 - Create a git branch

• Create a branch called feature/setup-graphql

If you don't remember how to create a branch, check the references in the previous issues.

Note: From here, the issues will contain fewer tutorials and step-by-step guides. However, it doesn't mean you won't be able to ask. You can always ask anything to any Taqtiler. We are here to help 😉

[JonasBorgesLM]

Finish

[taki-tiler-server[bot]]

Step 2/5 - GraphQL setup

Estimated time: 3 hours

In this step you'll create a basic hello-world GraphQL Node Server. But before you start, there are some core concepts you need to know in order to understand what's going on on your code. Try to do some research on your own about these topics, but feel free to ask your tutor, or even another Taqtiler, for references, tips and/or clarifications:

1. Client-server architecture
2. HTTP communication
3. REST
4. GraphQL: shema (queries, mutations, types and inputs)

When you are comfortable to follow, we suggest you take a look at the GraphQL Getting Started guide to begin your quest.

To call this step done, you must have:

1. A simple GraphQL node server properly setup
2. A query called hello that returns a string, for example: Hello, world!
3. Your should have an Express server running with GraphQL
4. Create a scripts on package.json called start. For now, it will be node server.js (or the name of the file you've chosen).
5. Make sure you tested your server running with npm start and performed the hello query. You should be able to access the Graphql docs and perform the query on: browser, Graphiql or Graphql Playground (you can choose the one you like). Keep this query for future testing!

[JonasBorgesLM]

Finish

[taki-tiler-server[bot]]

Step 3/5 - Create a Pull Request

• Open a Pull Request of your feature/setup-graphql branch

If you don't remember how to open a Pull Request, check out the references in the previous issues. Your PR should have develop branch as base, to be merged into later.

This pull request will be reviewed by your Taqtile tutor and possibly by some other people. This process is called Code Review (CR). You can ask your tutor about who will be revising your code.

Make sure you're marking them on every Pull Request as reviewers. Check here for an example of Code Review. You'll possibly have some requested/suggested changes in order to merge this new branch on develop. Make sure to resolve all those changes before merging your branch into develop. 😉

After opening the pull request, you can continue your work on a new branch.

[JonasBorgesLM]

Finish

[taki-tiler-server[bot]]

Step 4/5 - Typescript and Apollo Server

Estimated time: 3 hours

In this step you'll have two main tasks: add Typescript to your project and use Apollo Server to setup GraphQL.

But first, let's create a new branch. You can call it feature/apollo-typescript-setup (but for now on, you're going to choose the branches names 😼).

Apollo Server is a nice library that we use to make GraphQL setup much easier. We recommend the tutorial from Apollo, but you can follow one of your choice on the internet if you'd like. There are a bunch of posts like "create a Node GraphQL Server with Apollo and Typescript" or something like that 📝.

After the tutorial and setup, adapt your index.ts to have the hello query as the previous step had, and then you can remove the js code. Make sure that the start script is working and that you can use the hello query on the Apollo sandbox tool.

TIP: we recommend you to add a script called dev on your package.json. It will be similar to start, but you can use some lib to watch your code and restart the execution right after any changes. This will improve your speed when testing code with minimal modifications. You can find a tutorial for this on the internet. Something to help you research: "watch and reload with node and typescript", "hot reload", "live reload", etc. You can see if it's working by running the script npm run dev, changing something on your hello query, for example, and check if terminal reloaded the application correcly with that change.

After this, open a new pull request.

NOTE: when you open a PR, you have to select two branches: the "compare", the branch you're working, and the "base", which is the branch you desire to merge yours. Try to choose the base branch that allows reviewers to see only the changed code of the current branch (in this case, feature/apollo-typescript-setup) without showing previous PR changes. Look on the internet for ways to see your branches sketched to help you do this. If you have any difficulties, feel free to ask your tutors, or any Taqtiler 😉.

[JonasBorgesLM]

Finish

[taki-tiler-server[bot]]

Step 5/5 - Formatting code and conventions

Estimated time: 2 hours

So, now that you have properly setup and run your project, let's talk about some nice tools that we use to format our code and also some conventions we have. These are very important subjects when we work as a team, making our work of reading and contributing on projects much easier.

Lint

Lint is a very powerful tool to inspect code and warn about some possible mistakes. Lints use to be more language-specific. In our projects, we use eslint, which is a Javascript linter, but sure we have some additional support for Typescript features too. You can follow this guide to configure eslint with Typescript.

We recommend you install eslint Vscode extension, so the lint errors will be shown while you write your code.

Prettier

Prettier is a tool that helps us formatting our code. They have a VSCode extension that makes possible to auto-format a file according to these rules. We highly recommend you install it, if it's not already present on your machine.

We generally use prettier in our projects as a plugin for eslint, so code styling becomes something like lint rules. To add prettier in your project as a eslint plugin, please follow this guide.

This is the .prettiertc.js we use on our projects, in case you want to use it.

Conventions

Conventions are very important to maintain all projects code more readable for all developers and make the process of switching between projects less painful. We're going to list some of them here, but you will be learning and practicing more of them on code-reviews:

• We name our folders and files with kebab-case: lowercase characters and words combined with a dash (-)
• We name functions and local variables with camelCase: first char lowercase and words combined by the first letter at uppercase
• We name Typescript interfaces, classes and exported objects with PascalCase - it's similar to camelCase, but first char is uppercase
• We don't use if without brackets, even if it's a one command only condition. This can avoid some readability problems

Add these tools on your project, check the code you have untill now to follow our conventions. Also, make sure that if you change something on code that generates a format or lint error, it's detected in real-time on the editor. Then, open a Pull Request.

[JonasBorgesLM]

Finish

[taki-tiler-server[bot]]

Click here for your next track