<p>New year, new blog! After delaying the publication of my blog for a long time, I finally finished developing it using <a href="https://nextjs.org/">Next.js</a>, <a href="https://pocketbase.io/">PocketBase</a>, and <a href="https://mantine.dev/">Mantine</a>. Want to know why I chose these tools? Then, keep reading here with me.</p>
<p>I&#39;ve been creating blogs for a long time (since 2007). I started with Blogger, but then I migrated to WordPress. And that&#39;s when I started to be interested in Linux and programming. I spent a lot of time creating themes, customizing plugins, reading documentation, and translating themes and plugins for WordPress. And, although WordPress is an excellent CMS for those who just want to publish a website as quickly as possible, this time I wanted something more personalized, containing all the features I would like to have and nothing more. From there, I started researching.</p>
<p>I tried several CMSs (<a href="https://directus.io/">Directus</a>, <a href="https://keystonejs.com/">KeystoneJS</a>,
<a href="https://strapi.io/">Strapi</a> and <a href="https://getcockpit.com/">Cockpit</a>), but what I found most simple to meet my need was <a href="https://pocketbase.io/">PocketBase</a>, mainly because I intended to self-host my solution. The other CMSs are great, but when you&#39;re a team of one, you have to choose the right tools. And what&#39;s easier for one person to manage than an SQLite database? PocketBase already exposes database updates in real time with SSE, provides authentication and file management (with integration with S3), SDK for JavaScript and Flutter, and can even be used as a framework. All this within a small binary written in Go (if you want to know more about PocketBase, <a href="https://pocketbase.io/docs/">read the documentation</a> and watch this video from <a href="https://www.youtube.com/watch?v=Wqy3PBEglXQ">FireShip</a>, where he shows how to create a real-time chat system with PocketBase). And finally, in order to have real-time backups of my SQLite database and send them to S3, I use <a href="https://litestream.io/">Litestream</a>. Well, having made the choice for the backend, let&#39;s move on to the frontend.</p>
<p>I tried <a href="https://astro.build/">Astro</a> (which is excellent!) and <a href="https://remix.run/">Remix</a>, but I ended up choosing Next.js, mainly because of the Vercel image generation library, which I use to generate images of the post, like this one:</p>
<img src="https://douglasmoura.dev/api/v1/og?ok" alt="The job that's never started as takes longest to finish" />

<p>And here we come to the choice of what I would use to create the styles of the blog. In recent years, I styled React applications with <a href="https://github.com/css-modules/css-modules">CSS Modules</a>, <a href="https://styled-components.com/">Styled Components</a>, <a href="https://stitches.dev/">Stitches</a>, <a href="https://tailwindcss.com/">Tailwind</a> and <a href="https://chakra-ui.com/">Chakra UI</a>. I even stated to create a Design System with Stitches and Tailwind, but create an entire Design System all by myself would take a long time, so, I decided to take the shorter route.</p>
<p>I have tried a few libraries until I found <a href="https://mantine.dev/">Mantine</a>, which is an excellent library packaged with everything I wanted to use.
From there, the work consisted of implementing the blog with the basic initial features:</p>
<ul>
<li><a href="https://nextjs.org/docs/basic-features/data-fetching/incremental-static-regeneration">Incremental Static Regeneration</a> of posts;</li>
<li>Form validation with <a href="https://github.com/colinhacks/zod">Zod</a>;</li>
<li>Nested comment system with anti-spam verification provided by <a href="https://akismet.com/">Akismet</a>;</li>
<li>Display of commentator avatars with <a href="http://pt.gravatar.com/">Gravatar</a>;</li>
<li>SVG Favicon with light/dark mode;</li>
<li>I18n (Portuguese and English).</li>
</ul>
<p>With all that ready, I changed the canonical URLs of my articles on <a href="https://dev.to/douglasdemoura">Dev.to</a> to point to the new URLs and finally published my blog.</p>
<p>Of course, if you&#39;re reading this on my blog now, you&#39;ll see that an important feature is still missing: search. I&#39;ll be studying possible solutions for this in the coming days, but I&#39;ll already let you know that you can preview the functionality by pressing the <kbd>/</kbd> key on any page.</p>
<p>Happy 2023, everyone 🎉.</p>


New year, new blog (or how I created this blog for 2023)

<p><a href="https://graphql.org/">GraphQL</a> is a query language for APIs and a runtime for fulfilling those queries with your existing data, developed by Facebook in 2012 and open sourced in 2015. The goal was to create a query language that allowed fine-grained control over the needed data a client can request to an API server.</p>
<p>A GraphQL service is created by defining <strong>types</strong> and <strong>fields</strong> to those types in a <strong>schema</strong>. A commom way to defining the schema of your GraphQL service is through the GraphQL Schema Definition Language (SDL).</p>
<p>In this article, I&#39;ll show how to create a GraphQL schema compliant with the <a href="https://relay.dev/docs/guides/graphql-server-specification/">Relay GraphQL Server</a> specification.</p>
<h2>Defining your schema in GraphQL</h2>
<p>A GraphQL schema should informe the users about all the types and objects that can be queried and mutated on the graph. GraphQL even provides a feature to query metadata about those types and objects, which can be used to document the GraphQL.</p>
<p>Let&#39;s define a simple schema using GraphQL SDL (Schema Definition Language):</p>
<pre><code class="highlited-code-wrapper langgraphql"><div class="highlited-code" data-language="graphql">&quot;&quot;&quot;
Serialize and validate JavaScript dates.
&quot;&quot;&quot;
scalar Date

&quot;&quot;&quot;
Node interface
&quot;&quot;&quot;
interface Node {
  id: ID!
}

&quot;&quot;&quot;
Priority level
&quot;&quot;&quot;
enum Priority {
  LOW
  MEDIUM
  HIGH
}

&quot;&quot;&quot;
A task that the user should complete
&quot;&quot;&quot;
type Task implements Node {
  &quot;Task ID&quot;
  id ID! # ID is a GraphQL special type for IDs.
  &quot;Task title&quot;
  title String!
  &quot;Task creation date&quot;
  created: Date!
  &quot;Task modification date&quot;
  modified: Date
  priority: Priority!
}

&quot;&quot;&quot;
Needed input data to add a new task.
&quot;&quot;&quot;
input AddTaskInput {
  title: String!
  priority: Priority
}

type Query {
  &quot;Get a task by ID&quot;
  task(id: ID!): Task
}

type Mutation {
  addTask(input: AddTaskInput): Task
}</div>
</code></pre><ol>
<li>First we define a <a href="https://graphql.org/learn/schema/#scalar-types">custom Date scalar</a> that should validate and serialize Date objects;</li>
<li>We define a <code>Node</code> interface. I&#39;ll explain more on why I&#39;m defining this interface the next topic;</li>
<li>We define an <a href="https://graphql.org/learn/schema/#enumeration-types">enumeration type</a> to define the valid priority status of a task;</li>
<li>We create our <code>Task</code> type with all the field it should contain. Notice that all field with the exclamation mark at the end are obligatory;</li>
<li>We add an input called <code>AddTaskInput</code> that defines the obligatory data to add a new <code>Task</code>;</li>
<li>In the Query type (which is a GraphQL reserved type), we define what queries are available from our root object;</li>
<li>In the Mutation type (which is a GraphQL reserved type), we define which operations to alter our data are available. Such operations are called <a href="https://graphql.org/learn/queries/#mutations">mutations</a>.</li>
</ol>
<p>Notice that, in GraphQL, comments between quotes serve as documentation (it&#39;ll be parsed and displayed in your GraphiQL web documentation interface), while the comments that start with <code>#</code> are ignored.</p>
<h2>Querying your data in GraphQL</h2>
<p>Tipically, you&#39;d query a GraphQL server like this:</p>
<pre><code class="highlited-code-wrapper langgraphql"><div class="highlited-code" data-language="graphql">{
  task(id: &quot;2&quot;) {
    title
  }
}</div>
</code></pre><p>Which would return the following, in JSON format:</p>
<pre><code class="highlited-code-wrapper langjson"><div class="highlited-code" data-language="json">{
  &quot;data&quot;: {
    &quot;task&quot;: {
      &quot;title&quot;: &quot;Write GraphQL tutorial&quot;
    }
  }
}</div>
</code></pre><p>In the query above, we started with a special &quot;root&quot; object, from where we select the <code>task</code> field with the id equals to <code>2</code> Then, we select the <code>title</code> field from the <code>task</code> object. But, if no task has an id equals to 2? In this case, our response would be:</p>
<pre><code class="highlited-code-wrapper langjson"><div class="highlited-code" data-language="json">{
  &quot;data&quot;: {
    &quot;task&quot;: null
  }
}</div>
</code></pre><p>Or, in case of a error, we would receive this response:</p>
<pre><code class="highlited-code-wrapper langjson"><div class="highlited-code" data-language="json">{
  &quot;data&quot;: {
    &quot;task&quot;: null
  },
  &quot;errors&quot;: [
    {
      &quot;message&quot;: &quot;Internal server error.&quot;
    }
  ]
}</div>
</code></pre><p>You may want rename a field before using your data. Well, you can create your <a href="https://graphql.org/learn/queries/#aliases">aliases</a> just like this:</p>
<pre><code class="highlited-code-wrapper langgraphql"><div class="highlited-code" data-language="graphql">{
  todo: task(id: &quot;2&quot;) {
    name: title
  }
}</div>
</code></pre><p>And that would be the return:</p>
<pre><code class="highlited-code-wrapper langjson"><div class="highlited-code" data-language="json">{
  &quot;data&quot;: {
    &quot;todo&quot;: {
      &quot;name&quot;: &quot;Write GraphQL tutorial&quot;
    }
  }
}</div>
</code></pre><p>GraphQL also provides the feature of create <a href="https://graphql.org/learn/queries/#fragments">query fragments</a> and setting up  <a href="https://graphql.org/learn/queries/#directives">directives</a> to query your data. I&#39;ll need to add more complexity to our current schema in order to explain that, so, for while, let&#39;s move to the next topic.</p>
<h2>The Relay GraphQL Server specification</h2>
<p>Despite you may not want to use <a href="https://relay.dev/">Relay</a> (or even React) to consume your GraphQL data, their specification is very useful and provides a common ground of what developers should expect from a GraphQL server.</p>
<p>Remember that <code>Node</code> interface we defined above? Its purpose is to provide a <a href="https://graphql.org/learn/global-object-identification/">global object identification</a> for all the GraphQL nodes in our server. Therefore, a GraphQL client can handle re-fetching and caching in a more standardized way. Notice that each ID must be globally unique on your application.</p>
<p>As the <code>Node</code> interface will be used for all objects in our server, GraphQL provides a reusable unit called <a href="https://graphql.org/learn/queries/#fragments">fragment</a>. Now, let&#39;s add a new way the query nodes on our schema:</p>
<pre><code class="highlited-code-wrapper langgraphql"><div class="highlited-code" data-language="graphql"># ...

type Query {
  &quot;Get a node by ID&quot;
  node(id: ID!): Node
}

# ...</div>
</code></pre><p>Notice that the <code>task</code> query was removed, as it is no more needed. And now, we will re-do our query using a fragment:</p>
<pre><code class="highlited-code-wrapper langgraphql"><div class="highlited-code" data-language="graphql"># We name the query and pass a variable
# to improve the development experience.
query getTask(id: ID!) {
  node(id: $id) {
    ...taskFields
  }
}

fragment taskFields on Task {
  title
}</div>
</code></pre><p>And now, we will change our schema to comply with the Relay GraphQL Server specification. Take some time to read the comments in order to understand what is being done here.</p>
<pre><code class="highlited-code-wrapper langgraphql"><div class="highlited-code" data-language="graphql">&quot;&quot;&quot;
Serialize and validate JavaScript dates.
&quot;&quot;&quot;
scalar Date

&quot;&quot;&quot;
Node interface
&quot;&quot;&quot;
interface Node {
  id: ID!
}

&quot;&quot;&quot;
Priority level
&quot;&quot;&quot;
enum Priority {
  LOW
  MEDIUM
  HIGH
}

&quot;&quot;&quot;
A task that the user should complete
&quot;&quot;&quot;
type Task implements Node {
  &quot;Task ID&quot;
  id ID! # ID is a GraphQL special type for IDs.
  &quot;Task title&quot;
  title String!
  &quot;Task creation date&quot;
  created: Date!
  &quot;Task modification date&quot;
  modified: Date
  priority: Priority!
}

&quot;&quot;&quot;
Define an edge of the task,
containing a node and a pagination cursor.
&quot;&quot;&quot;
type TaskEdge {
  cursor: String!
  node: Task
}

&quot;&quot;&quot;
Define a connection between the
task edges, including the PageInfo
object for pagination info.
&quot;&quot;&quot;
type TaskConnection {
  edges: [TaskEdge] # Yes, we use brackets to define arrays in GraphQL
  pageInfo: PageInfo!
}

&quot;&quot;&quot;
Provides pagination info
for a cursor-based pagination
&quot;&quot;&quot;
type PageInfo {
  hasNextPage: Boolean!
  hasPreviousPage: Boolean!
  startCursor: String
  endCursor: String
}

&quot;&quot;&quot;
Needed input data to add a new task.
&quot;&quot;&quot;
input AddTaskInput {
  title: String!
  priority: Priority
}

type Query {
  node(id: ID!): Node
  tasks(
    first: Int, # The amount of tasks requested
    after: String # Cursor to mark the point
  ): TaskConnection
}

type Mutation {
  addTask(input: AddTaskInput): Task
}</div>
</code></pre><p>At this point, the metaphor of <a href="https://en.wikipedia.org/wiki/Graph_(discrete_mathematics)">graphs</a> used here should be very clear. Each <strong>edge</strong> of your graph has a node and a <strong>connection</strong> of edges has a collection of nodes that can be paginated. Note that, in this specification, is expected that you implement a <a href="https://www.prisma.io/docs/concepts/components/prisma-client/pagination#cursor-based-pagination">cursor based pagination</a>, rather than a <a href="https://www.prisma.io/docs/concepts/components/prisma-client/pagination#offset-pagination">offset pagination</a> (follow the previous link to have more information about their differences.</p>
<p>And that&#39;s all we need to comply with the <a href="https://relay.dev/docs/guides/graphql-server-specification/">Relay GraphQL Server Specification</a>.</p>
<p>In the next article, I&#39;ll implement a GraphQL server using all the concepts that we learned here.</p>
<p>Source:</p>
<p><a href="https://graphql.org/">GraphQL</a></p>


Douglas Moura

Douglas Moura

#webdev

New year, new blog (or how I created this blog for 2023)

Introduction to GraphQL