Skip to content

Latest commit

 

History

History
233 lines (159 loc) · 6.08 KB

FRONTEND.md

File metadata and controls

233 lines (159 loc) · 6.08 KB
Raw

MetaGame's FrontEnd API Guide

Requirements

In order to develop MetaGame FrontEnd components, you need.

  • Node.js (the current setup is using lts/gallium (16.13.1))

  • Yarn (v1.19.0 as some later versions throw errors when adding dependencies) (to set yarn's version: yarn policies set-version 1.19.0)

You can either choose to only develop the frontend and use our deployed backend services, or run the services on your own machines. If you're only going to work on UI, it's much quicker to connect to the remote servers.

Install dependencies

yarn

Connecting to remote servers

To connect to staging servers, you'll need to create a file .env under packages/web/ and write this inside:

NEXT_PUBLIC_GRAPHQL_URL=https://api-staging.metagame.wtf/v1/graphql

Enabling profile image editing

The storage of images associated with a profile is in web3.storage. In order to be able to connect, you will need to create an API token and save it in packages/web/.env as WEB3_STORAGE_TOKEN.

Connecting to local server

If you want to connect to locally running backend services, you will need to be able to start the backend with:

yarn docker:start

Or, if you prefer to be able to see the output from the backend:

docker-compose up --build

If you have difficulties running the backend, checkout the Backend Guide.

Starting web app in dev mode

Once you are ready to connect to the backend, you can start the web app by using:

yarn web:dev

Go to localhost:3000.

Happy Coding!

Creating GraphQL queries

The GraphQL queries are created by running, first, yarn update-schema which exports a GraphQL schema from Hasura, then, yarn generate which combines that schema with additional programmer-provided queries and mutations.

The programmer contributions can be found at:

  • packages/web/graphql/
  • packages/backend/src/handlers/graphql/

Related queries and mutations should be in the same file.

Creating a GraphQL query

Queries are to pull and retrieve data from the database. In the following example we will be using the Map table as an example.

export const GetMapQuery = /* GraphQL */ `
  query GetMap($id: uuid!) {
    Map_by_pk(id: $id) {
      id
      author_address
      name
      data
    }
  }
`;

In the above example we retrieved a map by id. There are several key things you need to factor in the implementation.

  1. The parameters, if you look at:
query GetMap($id: uuid!) {
  ⋮

We provided a $id. It is important that all queries and mutations have parameters that are prefixed with a $.

  1. The returned columns:
{
  id
  author_address
  name
  data
}

Specifying these columns are important depending on what data you need to pull to the frontend.

  1. The Hasura related function:
Map_by_pk(id: $id)

You can actually review all queries and mutations available in Hasura on http://localhost:9695 by running yarn hasura console.

Integrating the GraphQL query

In order to integrate the GraphQL query you need to use the useQuery function in the urql package. You will also need to import the GraphQL query created. The following showcases how to use the query with a React functional component.

import React, { FC } from 'react';
import { useQuery } from 'urql';
import { GetMapQuery } from '/path/to/query';

export const Component: FC = () => {
  const id = 'uuid';

  const [result] = useQuery({
    query: GetMapQuery,
    variables: { id },
  });

  const { data, fetching, error } = result;

  return(
    ...
  )
}

Optional, use useEffect

You can also useEffect to rexecute queries based on changes to variables in GraphQL.

import React, { FC, useEffect } from 'react';
import { useQuery } from 'urql';
import { GetMapQuery } from '/path/to/query';

export const Component: FC = ({ id }) => {
  const [result, reexecuteQuery] = useQuery({
    query: GetMapQuery,
    variables: { id },
  });

  useEffect(() => {
    reexecuteQuery();
    // Add variables to the array to trigger when the query is updated
  }, [id]);

  const { data, fetching, error } = result;

  return(
    ...
  )
}

Keep in mind the following parts of the query state:

  1. fetching is a boolean that indicates whether or not the query is loading

  2. error is whether or not an error was thrown executing the query

  3. data is the data returned from the query

Creating GraphQL mutations

GraphQL mutations are used to update and insert new data into the database. The following is an example of inserting data into the Map table.

export const CreateMap = /* GraphQL */ `
  mutation createMap($author: String!, $name: String!) {
    insert_Map_one(object: { author_address: $author, name: $name, data: "" }) {
      id
    }
  }
`;

For the most part, the key things to be mindful of syntax are the same as seen in the query section.

Integrating the GraphQL mutation

In order to use the mutation, you will need to use the useMutation function in the urql package. Mutations typically should only be done via user interactions. The following example showcases how a button triggers a mutation.

import React, { FC } from 'react';
import { useMutation } from 'urql';
import { CreateMap } from '/path/to/query';

export const Component: FC = () => {
  const [state, executeMutation] = useMutation(CreateMap);
  const { fetching, error, data } = state;

  async function insertMap(author, name) {
    try {
      await executeMutation({ author, name });
    } catch (err) {
      console.error(err);
    }
  }

  return (
    <button type="button" onClick={() => insertMap('Hello World', 'Test 1234')}>
      Generate
    </button>
  );
};

Keep in mind the following parts of the mutation state:

  1. fetching is a boolean that indicates whether or not the mutation is loading

  2. error is whether or not an error was thrown executing the mutation

  3. data is the data returned from the mutation

For the most part the structure of states are relatively the same to queries.