In this guide, we'll be using a JSON or CSV file with some data in it to build a fully featured GraphQL API inside a NextJS application.

For this to work, we'll need some tools, here are links to all the tools used in this guide if you'd like to check any of them out or potentially explore replacements:

• Prisma The database connector where all the magic happens

• Typegraphql-Prisma To generate the TypeGraphQL schema for the Apollo server from Prisma

• TypeGraphQL

• Apollo Server

• graphql-code-generator To build the types for the frontend

• Next The fullstack framework we'll be using

• React The frontend part

Create a MongoDB database and add your data (skip if you already have a MongoDB database with data in it)

Head to mongodb.com and sign up for a free Atlas account or set up mongodb locally

Create your project

Create a cluster, select SHARED for the free tier.

Create your user and add your IP address to the list of allowed IP addresses (or 0.0.0.0 to allow any connection).

Press connect on your cluster on mongodb.com

Click on Compass

Download Compass if you don't have it, and copy the connection string

Paste the connection string into Compass, replacing with the password for the database user you created earlier and press connect

Click databases

Click create

In the database name and collection name fields, describe the data type your database will contain, for example a database of football players could be called football_players or players

Once the database is created, click on it

Click the collection

You can now upload your JSON or CSV file to the database to fill it

We now have a database with the data we need, you can close Compass.

Create a NextJS app with TypeScript

Answer the questions as you like but when asked

'if you want to use the new /app directory' no

'if you want to use src directory' no

yarn create next-app --typescript

Install dependencies

yarn add prisma typegraphql-prisma -D

yarn add @apollo/server @as-integrations/next @prisma/client graphql class-validator type-graphql@next reflect-metadata graphql-scalars graphql-fields @types/graphql-fields tslib

Initialize prisma

yarn prisma init --datasource-provider mongodb

Add mongodb connection and the eventual graphql api url to .env

DATABASE_URL="mongodb+srv://username:password@address.mongodb.net/tablename?retryWrites=true&w=majority"
NEXT_PUBLIC_API_URL="http://localhost:3000/api/graphql"

Pull the database schema into Prisma

yarn prisma db pull

Add generator to prisma

generator typegraphql {
  provider = "typegraphql-prisma"
  output   = "../prisma/generated/type-graphql"
  simpleResolvers = true
}

Create tsconfig.json or modify it at the NextJS root

{
  "compilerOptions": {
    "allowJs": true,
    "forceConsistentCasingInFileNames": true,
    "noEmit": true,
    "moduleResolution": "node",
    "resolveJsonModule": true,
    "isolatedModules": true,
    "jsx": "preserve",
    "incremental": true,
    "baseUrl": ".",
    "paths": {
      "@/*": ["./*"]
    },
    "sourceMap": true,
    "outDir": "dist",
    "strict": true,
    "lib": ["esnext", "esnext.asynciterable", "dom", "dom.iterable"],
    "target": "es2018",
    "module": "commonjs",
    "esModuleInterop": true,
    "emitDecoratorMetadata": true,
    "experimentalDecorators": true,
    "skipLibCheck": true
  },
  "include": ["next-env.d.ts", "**/*.ts", "**/*.tsx"],
  "exclude": ["node_modules"]
}

Generate the prisma schema

yarn prisma generate

Create /pages/api/graphql.ts

import 'reflect-metadata';
import { resolvers } from 'prisma/generated/type-graphql';
import { PrismaClient } from '@prisma/client';
import { ApolloServer } from '@apollo/server';
import * as tq from 'type-graphql';
import { startServerAndCreateNextHandler } from '@as-integrations/next';

const prisma = new PrismaClient();

const schema = tq.buildSchemaSync({
  resolvers,
  validate: false,
});

const server = new ApolloServer({ schema });

export default startServerAndCreateNextHandler(server, {
  context: async () => ({ prisma }),
});

Add this line to the top of _app.tsx

import 'reflect-metadata';

Start your Next app

yarn dev

Access the server at http://localhost:3000/api/graphql

Enabling CORS to use outside Vercel

Add the following to next.config.js.

/** @type {import('next').NextConfig} */
const nextConfig = {
  reactStrictMode: true,
  async headers() {
    return [
      {
        source: '/api/:path*',
        headers: [
          { key: 'Access-Control-Allow-Credentials', value: 'true' },
          { key: 'Access-Control-Allow-Origin', value: '*' },
          {
            key: 'Access-Control-Allow-Methods',
            value: 'GET,OPTIONS,PATCH,DELETE,POST,PUT',
          },
          {
            key: 'Access-Control-Allow-Headers',
            value:
              'X-CSRF-Token, X-Requested-With, Accept, Accept-Version, Content-Length, Content-MD5, Content-Type, Date, X-Api-Version',
          },
        ],
      },
    ];
  },
};

module.exports = nextConfig;

Automatically generate types for the client

Install graphql-code-generator

yarn add -D ts-node @graphql-codegen/cli @graphql-codegen/client-preset

Create codegen.ts

import { CodegenConfig } from '@graphql-codegen/cli';

const config: CodegenConfig = {
  schema: "http://localhost:3000/api/graphql",
  documents: ['pages/**/*.tsx'],
  ignoreNoDocuments: true, // for better experience with the watcher
  generates: {
    './gql/': {
      preset: 'client',
      plugins: [],
    },
  },
};

export default config;

Install concurrently

yarn add -D concurrently

Modify your dev script in package.json

"dev": "concurrently \"yarn next dev\" \"yarn graphql-codegen --watch\"",

Communicating with the API within Next

Add graphql-request and react-query

yarn add graphql-request react-query

Add React query provider and a global graphql-request client to _app.tsx

import 'reflect-metadata';
import type { AppProps } from 'next/app';
import { QueryClient, QueryClientProvider } from 'react-query';
import { GraphQLClient } from 'graphql-request';

const queryClient = new QueryClient();

export const client = new GraphQLClient(process.env.NEXT_PUBLIC_API_URL as string, {
  headers: {},
});

export default function App({ Component, pageProps }: AppProps) {
  return (
    <QueryClientProvider client={queryClient}>
      <Component {...pageProps} />
    </QueryClientProvider>
  );
}

You're now ready to use react-query with your types, here's an example index.tsx with a database of players

import Head from 'next/head';
import { graphql } from 'gql';
import { useQuery } from 'react-query';
import React from 'react';
import { client } from './_app';

const findManyPlayers = graphql(`
  query FindManyPlayers($take: Int) {
    findManyPlayers(take: $take) {
      age
      hits
      name
      id
      nationality
      overall
      player_id
      position
      potential
      team
    }
  }
`);

export default function Home() {
  const { data } = useQuery(['players'], async () =>
    client.request(findManyPlayers, {
      take: 5,
    })
  );
  if (!data) return <></>;
  return (
    <>
      <Head>
        <title>Create Next App</title>
        <meta name='description' content='Generated by create next app' />
        <meta name='viewport' content='width=device-width, initial-scale=1' />
        <link rel='icon' href='/favicon.ico' />
      </Head>
      <main>
        <div>
          {data.findManyPlayers.map((player) => (
            <React.Fragment key={player.id}>
              <p>{player.name}</p>
            </React.Fragment>
          ))}
        </div>
      </main>
    </>
  );
}

A newcomer to this space will be bombarded with thousands of articles, videos and posts on platforms like YouTube, Reddit or dev.to that claim to have the "definitive roadmap".

To clarify, roadmaps are basically guided learning paths. Essentially a list of "learn this, then learn that, do this in the middle" that's intended to be the go-to step-by-step process for becoming a junior, mid-level or senior. In reality, these roadmaps are often either too simplistic/broad or unrealistic in the amount of time they usually claim is sufficient to complete them.

The Burden of Choice

Let's step back and consider why a newcomer would even need a roadmap. It should be easy to simply parse job descriptions for an idea on what technologies a position will require and just tackle those individually, but it isn't.

The first barrier to entry is that there's a lot of unknown pre-requisite and supplementary materials for the technologies actually listed in a given job description. These pre-requisite and companion materials are branching in the sense that for each library there are potentially dozens of technologies that will pair perfectly with it and are used in industry to accompany it.

The second barrier to entry, compounding the first, is the number of options available for an aspiring developer willing to put in the work and learn what they need to. There are simply too many libraries, frameworks, concepts, patterns, technologies and principles to learn from too many course websites, videos, articles, documentation pages, guides and open university courses. It sounds like a first world problem, but this flood of options and resources leads to every developer having a unique collection of information due to the difficult choices they have to make when learning. Effectively, every developer is different in some way unless they follow the same learning path.

This is where roadmaps come in. A roadmap promises some guidance on what to learn and in what order or what to focus on in order to gain the skills needed to perform the role well. In principle, there's nothing wrong with them. In practice, they leave a lot to be desired.

The Problem With Roadmaps

A rampant issue we have is that roadmaps often just parrot the names of libraries instead of explaining why to learn this or that technology or this or that library. There are also roadmaps that are just collections of disconnected links which expect you to learn a concept from a random article or page and then jump to a completely different article or page to learn a related concept... This makes no sense!

The major issue with these library-centric roadmaps is that they encourage learning the tools instead of the concepts. This is understandable, given that the job market requires knowledge of the tools more than the concepts in many cases. But unless the learner knows this beforehand, they'll end up ignoring many of the concepts that will allow them to keep their job when the library they've learned is eventually deprecated in favor of the newer and shinier contender.

I see this a lot with people who learn a framework and skip learning the basics and understanding the architecture of applications, when their framework of choice is deprecated or when they're offered a new position using a different framework a lot of them struggle to make the switch. This is because after following their framework centric roadmap they became framework users not developers.

The solution for this is simple, roadmaps can be descriptive of why you need to learn something. But even when a roadmap has relevant content and descriptive resources like this one for frontend developers and the same one but for backend developers, it can often look very intimidating to beginners. There's so many items that make little sense to a complete beginner that even with guidance on where to start, it's impossible to look at the whole list without feeling discouraged from trying. Effectively, the roadmap becomes a giant self-study syllabus without a teacher and that barrier becomes very difficult to overcome.

Escaping this, newcomers will end up searching for a more structured learning path to follow. This usually comes in the form of a course on an online platform like Udemy or a long video series on YouTube or structured journey-based websites like The Odin Project, freecodecamp and Full Stack Open. I have nothing against these approaches and, in fact, that's the way I'd recommend for most newcomers. These websites are mature and have started many developers' successful careers and can often be a saving grace when all the other resources are too dispersed to properly learn anything from.

However, there's a dangerous common issue that faces both those who follow a roadmap and those who follow guided resources: Burnout.

Burnout

By this point, you may have realized that there are indeed a lot of things you need to learn to become an effective developer. What I've discussed so far does not dispute this fact. However, it helps to outline that the real issue here isn't that you have to learn a lot, it's that you'll experience burnout.

I'm sure not a single developer on Earth can claim they've never felt a little burnt out while learning new things. In fact, it's so common that it's often assumed to be part of the process, that it'll happen eventually and delaying it is the best we can do. Simply put, when trying to follow a roadmap and giving yourself a strict timeline, you could often end up either covering too much in too little time or being stuck on sections that ultimately don't matter and becoming discouraged.

I strongly disagree with the idea that burnout is inevitable. In my own experience, I've suffered from it before, but rarely have I ever felt like I hadn't locked myself into this unhealthy pattern of not pacing myself to the point where it caused burnout in the first place. I can't stress enough that the point of a realistic roadmap and proper pacing along the way isn't to ensure that you'll learn everything, but rather to ensure that you can do that while maintaining the balance of your life and your mental health.

Building A Realistic Roadmap

At this point, I'd like to include a disclaimer that I am not creating a roadmap for you to follow. Rather, I am going to include a set of guidelines that I've personally used to build my own roadmap to avoid burnout and make sure that I've covered the material that I need at a pace that makes me comfortable. It's also worth noting that everyone has their own method and process when learning and I do not discourage you from deviating as little or as much as you'd like from this set of guidelines.

You Can Learn For Free

Because a lot of developers struggle with finding where and what to learn, a lot of people have capitalized on this by offering absurdly priced courses, resources and even roadmaps costing money. There's nothing wrong with paying for learning materials, but you don't have to.

Practice, Don't Cram.

Development is inherently a practical field, a lot of the knowledge that we acquire is meant to be applied when developing, designing or architecting systems and applications. The approach of trying to fly through materials as fast as possible or to keep cramming until you get tired is not going to allow you to properly process this information and retain it.

Try to learn one "thing" at a time. If you're feeling like you haven't covered enough today, instead of covering more material, prioritize applying what you've learned. If today's thing is a new framework, try building an application with it. If it's a library, try using it in an application. Keep your learning sessions short and your practice sessions frequent to avoid forgetting things.

Read Job Descriptions

The new and shiny libraries of the day are often overrepresented in online material; from articles to videos and pages dedicated to this new tech, it can be easy to forget that companies still use stable and battle-tested tech. This can so extreme as to be old and deprecated, but remember that you're focusing on the concepts and not the specific libraries.

Job descriptions usually include the main technology that you'll be working with day to day, other supplemental technologies may or may not be mentioned as well. Reading these allows you to know what to keep an eye on for your desired position, but keep in mind you shouldn't take it as gospel that what's required in this job description will be what's required in the same role at a different company. Be mindful of what's being used in the industry to guide your learning process, but do not let it overwhelm your choices.

Build Meaningful Projects

This is different from practicing in the sense that I'm not talking about building a little project to try out a library or a framework, but rather building a project to allow you to run into real world issues that you would only face when building an application or system.

If you can avoid template project tutorials like "How to build a Facebook Clone", I strongly suggest you stay away from them. These projects, unless you wildly innovate on them, act as a placeholder on your resume and portfolio. Not to mention that, usually, you end up making no decisions of your own for the application.

Coming up with project ideas is difficult, but you don't need to build something complicated. My approach is to build things that I'd like to use or have like tools or to build exploratory projects or working with weird and interesting libraries.

Join The Community

Whether you'd like to know about new and interesting technologies, get help from other learners, help other developers with their own learning path or even just see what other people are learning, I believe you should join online communities like Reddit's many learning-friendly subreddits such as r/learnprogramming or websites like dev.to. These positive communities encourage participation and discussion while allowing developers of all levels to ask questions and help each other.

Finally, Don't Give Up

The big secret to learning anything is consistency, it's more useful to study an hour a day for a year than it is to study ten hours a day for two weeks.

The more you learn, the more knowledgeable and confident you'll become and the more receptive you'll become to learning even more amazing things. The beautiful thing about becoming a developer is that one day you'll realize you know a ton of things and have a million ways to tackle the many problems that computers are built to solve.

You should be aware that the reason I urge you so strongly to build your own roadmap is to avoid two central issues: tutorial hell and being a master of nothing.

Let's Talk About Tutorial Hell

I'd like to shed some light on tutorial hell and why it's the reason roadmaps can be dangerous.

When you learn a technology without having a reason to, as you would if you were simply learning it because someone told you to, you can often miss the intended learning outcomes of this technology; or what you were supposed to learn about it beyond its syntax or its constructs. In essence, you lose out on what the point of this technology is.

When your only knowledge of a technology is its syntax or usage, you can very easily fall into tutorial hell: where the only way you can make anything using this technology that you know is to follow a guided tutorial teaching you how to make something with it.

I hinted at this earlier when I urged you to avoid "How to build a Facebook Clone"-type tutorials, these are purpose built for padding your GitHub and your resume with "projects" where in reality you know nothing about the decisions involved in building the project or the process followed to make those decisions. You serve as an outside observer to the whole part of the process that as a developer you should be involved in, the decision making, problem solving and architecture.

Following roadmaps and guided resources can be a double-edged sword, with the right mindset they can be infinitely more useful to you than simply learning every technology possible and hoping something sticks. Building your own well-researched roadmap helps you understand why you're learning a certain technology and by understanding the reasons you're covering this material you can hopefully avoid relying on others to tell you in what way to use a tool you already know how to use.

A Jack Of All Trades, A Master of None

To bring it all together, I'll clarify the biggest problem with the majority of learning paths that new developers follow. Whether it's a roadmap; a guided course or simply parsing job descriptions and learning what they list off, a newcomer would believe that there's so many technologies on their radar that they end up being a jack of all trades and a master of none. To become a frontend developer, they would think that even the smallest styling library makes sense to learn compared to the component framework that they would be actually using the vast majority of the time.

By giving equal focus to so many technologies, you can very easily lose sight of what technology is the most important to your role or to the job you're applying for. It's easy to get lost in the details when you don't yet have the insight into the development process to know the value of what you're learning.

The common pitfall here is developers will learn every major component framework on the frontend side or every server framework on the backend side instead of focusing on one and learning the concepts that will easily be transferrable if they move to another.

Earlier I mentioned that learning only the specifics of a framework makes you a framework user and not a developer, which is true, but the critical detail here is that doesn't prevent you from learning those specifics in addition to the concepts that you need to know. Gaining deep knowledge of your tool of choice is always an excellent idea and is necessary to be an effective and productive developer, the mark of a great developer is to know how to eject from this technology into a similar one at will.

To sum up: master the concepts, gain expertise in your technology of choice and focus strongly on gaining general skills in your role rather than learning 1% of every tool available or learning 100% of only one tool.

Accessibility in web design is often an afterthought, at most a designer will care about color contrast, text sizing and other elements meeting the visual part of the Web Content Accessibility Guidelines. While this is something to encourage, it doesn't even scratch the surface of what's needed for the end product to be actually accessible.

For a website to really be accessible, it's up to the developer as well to code with that in mind. From adding alt attributes, using WAI-ARIA or not using <div> for all content, all these approaches and everything else outlined in the WCAG are what can really help create more accessible websites.

So why are we talking about designs if it's a developer's problem to implement the accessible parts? Because a developer can only build what was designed correctly in the first place. If a designer is tasked with creating a design for a site, they have the first say in what parts will be accessible.

Accessible vs Aesthetically Pleasing

When you visit an accessible site, it could look ugly. In fact, it may look old and outdated in many different ways compared to the trends you can find on Dribbble or Behance.

Any accessibility aware designer or developer who inspects such a site and discovers that it's accessible would then sympathize with whomever designed or developed the site. I mean, they had a different goal than making it look good, right?

This is the problem with accessible markup on the web, the belief that an accessible site built for everyone can't have good aesthetics as a goal too, because it's difficult to build a website that looks good and also works for everyone.

In a sense, these simultaneously beautiful and accessible websites would be accessible despite the design, not in conformance to it. Someone explicitly chose to build a custom card component that tries to be accessible or to use pages instead of modals when possible to avoid the common pitfalls of hijacking the page.

These choices weren't enforced by the languages involved, or the technologies powering the web, they weren't enforced by the programs used to design the site or the frameworks used to build it. They were enforced by people who care about others and wanted to design and build something for everyone.

Running away from the problem

The tools we use to build the web may not enforce accessibility best practices, but it's common for companies based in the US afraid of violating the ADA to look for workarounds, shortcuts and ways to sidestep the man hours it takes to build an inclusive product.

They don't want to tell their developers to write accessible markup or to tell their designers to care about designing accessible interfaces because these initiatives could mean hiring more skilled employees or training their existing staff. They just want the equivalent of a normalizer or build tool to do the work for them.

Such tools exist in droves, not linked in this post but easy to find with a web search for "accessibility widget". They all parrot the same promise, pay a small monthly fee and import it and suddenly your whole site is accessible to all and lawsuit-free, does it sound too good to be true?

That's because it is. There's no shortcut to making an accessible website. These websites aren't accessible because the people building them chose to be inclusive, they're accessible (if at all), because they're trying to sidestep legal obligations.

Maybe one day we'll have build tools and external scripts that can truly make our sites accessible. Maybe even further in the future we'll have these tools for free because that's exactly what an open web should cost. Today, some tools exist that achieve the goal some of the time. I'm sure if you're paying a premium for accessibility on your websites, you don't want it to only work sometimes. You wouldn't want it to go away when you stop paying the monthly fee; because under the hood, your website isn't inclusive or accessible. The widget didn't change the problems with your code and designs, it hid them.

So what if you're building or designing a project for yourself or you're a company who wants to build something inclusive but you can't get an accessibility professional to manually audit your designs and test your application?

Learning to build differently

There's no end to the references online for writing accessible markup. I don't want to outline some reference or principle as an absolute because, as it turns out, making inclusive interfaces is not easy and thus is open to a lot of subjective views.

A good starting point that I've been following is the Web Content Accessibility Guidelines Quick Reference, this shows you where to start in terms of making your content accessible. In essence, this is really all you need but a cursory read will reveal that it's not the easiest resource to parse. If you're a designer or a developer, I recommend you start here; I'll also include other more approachable resources below.

For designers

Countless plugins exist for tools like Figma, Sketch and Adobe XD that allow you to check contrast, make sure that font sizes are appropriate and make sure that your content is approachable.

I use Figma, so I can't speak for other tools, but I use the Able and Focus Orderer plugins to both check that my colors are approachable and my designs are keyboard ready.

For developers

the W3C have also created a draft of how to use ARIA when building websites, this is an essential read if you're a developer who wants to build more inclusive websites.

For those who prefer to approach this with developer documentation rather than reference documents, the Mozilla Developer Network has a wonderful set of guides on Accessibility. These include HTML guidelines, CSS and JavaScript best practices and the basics of using ARIA as linked above. What they also offer is a summary of how to work with mobile devices to be more accessible. So far in this post I've focused mostly on websites since I'm a web designer and developer, but mobile is an equally large if not bigger part of this equation to consider as well.

For a while now, I've been a huge advocate of the principles of inclusive design. Case in point, I think everyone should check out Inclusive Components. It's a set of docs outlining how to make common component patterns more inclusive and accessible, the author also wrote a book as well as a post on inclusive design that I highly recommend you give a look.

Bringing it all together

In addition to these resources, I'd like to share some tips from my learning journey that I think can accelerate the process of building inclusive sites. This is by no means a summary or absolute reference, but simply guidelines I picked up along the way that I think can help ease the learning curve a bit.

Semantic HTML is here to help

HTML is made for everyone and just using semantic HTML elements for their purpose already goes a long way. For example: if you need to make a list, there's no reason to make a custom <mylist> component in your framework of choice if <ul> and <ol> exist. More on this is covered in how to use ARIA and on the Inclusive Components site.

You can still use tools

Earlier, I mentioned that you shouldn't use a widget that automatically modifies your site and makes it accessible in one go. While this is true, there are tools to augment the development process and help you stay within the Web Content guidelines without having to memorize or to always have the guidelines as shorthand. Examples include Eslint's JSX-A11y Plugin for React users that helps you write more inclusive markup, alternatives exist for Vue, Angular and probably whatever framework or library you're using as well.

Simple sites are not bad

I know that in the age of CSS frameworks being so prevalent and JavaScript frameworks allowing us to create feature-rich and content-rich websites it's easy to scoff at such a remark, but making your website simpler in terms of its markup and navigation can go a long way. A simpler website requires less markup, less JavaScript and probably less CSS as well. It's a lot easier to audit such a site yourself to see if your elements are accessible or not.

Develop with understanding

When keeping non-sighted users in mind while developing your site, it can be difficult to know the impact of adding an ARIA label or role or the impact of using a link tag to build a card. Installing or enabling a screen reader on your operating system can fix this, use it to audit your own website and see if it's truly easy to navigate using the keyboard and if all the content is there. Bonus points if you do it blindfolded for the extra immersion.

Know your demographic

If you're building a site assuming your content is not going to be useful for a non-sighted user or a user with motor problems or visual/auditory requirements, research your audience and see if your website is indeed only used by people outside those demographics. Chances are if your website is big enough and frequented by enough visitors, this isn't the case.

In short

The Internet exists for all of us, not just users who don't have accessibility concerns. It may be difficult to spend the time learning and developing with accessibility in mind, but your pages shouldn't be yet another walled garden that's only accessible to your perceived demographic. The steps you take to make your websites open to everyone may seem thankless; but every time someone who needs those changes visits your site, I guarantee you they'll be grateful that they're enjoying a website that's built with accessibility in mind.