DEV Community: Pascal Martineau

Form generation and validation with FormKit

Pascal Martineau — Wed, 23 Feb 2022 14:31:57 +0000

Since our project is already on the bleeding edge, we might just as well use a very exciting form library that just came out of private beta: FormKit.

Setting up FormKit in Nuxt3

At the time of writing this, the official @formkit/nuxt module offers little more than passing the options from an external file to the library and configuring transpilation. Also, since the FormKitSchema component isn't imported by default, we'll setup the library ourselves in a plugin.

yarn add -D @formkit/vue

The library needs to be transpiled to work with ES modules, so in nuxt.config.ts we add @formkit/vue to the build.transpile array.

We can now create our plugin in plugins/formkit.ts:

import { plugin, defaultConfig, FormKitSchema } from "@formkit/vue";

export default defineNuxtPlugin((nuxtApp) => {
  nuxtApp.vueApp.component("FormKitSchema", FormKitSchema);
  nuxtApp.vueApp.use(plugin, defaultConfig);
});

Configuring form classes with Tailwind CSS

Let's add some styles to our form sections by customizing the default plugin options:

// ...
import type { DefaultConfigOptions } from "@formkit/vue";

const options: DefaultConfigOptions = {
  config: {
    classes: {
      outer: "mb-3",
      label: "font-bold",
      help: "text-sm text-slate-400",
      messages: "mb-3 text-sm text-red-800",
    },
  },
};

// ...
  nuxtApp.vueApp.use(plugin, defaultConfig(options));
// ...

Adding the btn class to the submit input is a little more tricky, as it requires hooking into rootClasses:

// ...
    rootClasses(sectionKey, node) {
      return {
        [`formkit-${sectionKey}`]: true,
        ...(sectionKey === "input" && node.props.type === "submit" && { btn: true }),
      };
    },
// ...

Refactoring the login form with FormKit

Our login form's structure (fields types, names, labels and validation) can be abstracted away inside useAuth by adding a FormKit schema property which we'll name loginFormSchema:

// FormKit schema for the login form
const loginFormSchema = [
  {
    $formkit: "text",
    name: "email",
    label: "Email",
    validation: "required|email",
  },
  {
    $formkit: "password",
    name: "password",
    label: "Password",
    validation: "required",
  },
];

Our FormLogin component can now be rewritten like so:

<script setup lang="ts">
const { login, loginFormSchema } = useAuth();
const formErrors = ref<string[]>([]);

async function handleSubmit(credentials: any) {
  const redirect = (useRoute().query as { redirect: string }).redirect || "/";
  try {
    await login(credentials as LoginFormData);
    useRouter().push(redirect);
  } catch (error) {
    // Remove status code and path from error message
    const message = (error as Error).message.replace(/\d+ (.*) .*/, "$1");
    formErrors.value = [message];
  }
}
</script>

<template>
  <FormKit type="form" :errors="formErrors" submit-label="Login" @submit="handleSubmit">
    <FormKitSchema :schema="loginFormSchema" />
  </FormKit>
</template>

In the code above, we bind formErrors in order to handle server errors in addition to validation warnings. To make the error human-readable, we extract the meaningful part with a regex before adding it to our form.

Also, we have to cast credentials as LoginFormData because the typings are not available at build time (i.e. FormKit being very dynamic, the structure could be altered at runtime).

Conclusion

This concludes the first public version of this series, which I hope you have found both enjoyable and helpful. I plan on keeping it up to date as the various libraries used evolve.

Isomorphic authentication / authorization

Pascal Martineau — Wed, 23 Feb 2022 14:27:10 +0000

This one is a very long read, so hang on tight!

What does isomorphic mean for our project?

The goal here is to share as much authentication and authorization logic as possible between the backend and frontend. In practice, the authentication state and authorization rules' signatures should be the same but the logic itself will sometimes have to be implemented separately.

Setting up login / logout API routes

Our users will be authenticated by storing a JSON Web Token (JWT) in a HTTP-only cookie. We could return this token from a login mutation in our GraphQL API, but we'd still have to manage the cookie logic in Nuxt.

To make things simpler, we can implement login/logout as API routes and manage the cookie from the server response directly instead of splitting the logic between Nuxt and our GraphQL schema. This will also come in handy for third-party authentication providers, which require a callback route for handling the response anyways.

Unless I'm mistaken, there isn't an easy way to set cookies from within GraphQL mutation resolvers. This would require hacking into GraphQL Helix or creating a custom Envelop plugin.

Encrypting & verifying passwords

Before going any further, we'll need to add basic encryption for storing and verifying passwords securely. This will require the following packages:

yarn add -D bcrypt @types/bcrypt

We can encapsulate our encryption and verification logic as helper functions inside utils/password.ts:

import { compareSync, hashSync } from "bcrypt";

export const encryptPassword = (password: string): string => hashSync(password, 10);

export const verifyPassword = (password: string, encrypted: string): boolean => compareSync(password, encrypted);

Let's adjust our seeding script to store the encrypted password (remember to run yarn prisma db seed after):

// ...
import { encryptPassword } from "../utils/password";

// ...
  // Default admin user
  const admin = {
    email: process.env.SEED_ADMIN_EMAIL || "admin@example.com",
    password: encryptPassword(process.env.SEED_ADMIN_PASSWORD || "changeme"),
    role: UserRole.ADMIN,
  };
// ...

Handling authentication state with JWT

In addition to encrypting passwords, we need a secure way of storing and retrieving the authentication state using the JSON Web Token open standard. It's very important to get this right, as it is central to our application security.

Let's install the packages required to do this:

yarn add -D jsonwebtoken @types/jsonwebtoken

Since we want our JWT payload to be strongly typed, let's define a AuthState interface and a runtime validation helper in utils/jwt.ts:

import type { UserRole } from "@prisma/client";

// Type safe authentication state validation
export interface AuthState {
  user: null | {
    id: number;
    role: UserRole;
  };
}

export const validateAuthState = (authState: AuthState): AuthState => ({
  user: authState?.user ? (({ id, role }) => ({ id, role }))(authState.user) : null,
});

validateAuthState ensures the authentication state will always have the exact shape defined in the interface. In short, the user property will either be null when the user is not authenticated, or contain both id and role otherwise (these are the bare minimum for our authorization needs).

Next, we'll implement a helper for decoding the token into a validated authentication state. This will later be used in the contextFactory to set the current user in the GraphQL execution context:

import jwt from "jsonwebtoken";

// ...

// Decode and validate authentication state payload from (string) token
const jwtSecretKey = process.env.JWT_SECRET_KEY || "jwtsecretkey";

export const decodeJwt = (token: string): AuthState => {
  try {
    const authState = jwt.verify(token, jwtSecretKey) as AuthState;
    return validateAuthState(authState);
  } catch (error) {
    return { user: null };
  }
};

Then, we implement setAuthState, our helper for updating the authentication state as a JWT cookie in the server response:

import type { ServerResponse } from "http";
import type { User, UserRole } from "@prisma/client";
import type { CookieSerializeOptions } from "cookie-es";
import { setCookie } from "h3";
import type { SignOptions } from "jsonwebtoken";
import jwt from "jsonwebtoken";

// ...

// Encode authentication state as JWT cookie in server response
export const jwtCookieName = process.env.JWT_COOKIE_NAME || "jwt";
const jwtSignOptions: SignOptions = { expiresIn: "2h" };
const jwtCookieOptions: CookieSerializeOptions = { path: "/", httpOnly: true };

export const setAuthState = (user: User | null, res: ServerResponse): AuthState => {
  const authState = validateAuthState({ user });
  setCookie(res, jwtCookieName, jwt.sign(authState, jwtSecretKey, jwtSignOptions), jwtCookieOptions);
  return authState;
};

This helper will be used by our authentication API endpoints to set (or reset) the current user. Under the hood, it takes a User object (typed from our data layer) and a ServerResponse, encodes a validated authState in the Set-Cookie HTTP response header and finally returns the authentication state itself.

The various options (jwtSignOptions and jwtCookieOptions) can be tweaked to fit your security needs, but the provided settings should be a good start (all tokens expire after 2h, HTTP-only cookie with / path).

Can we setup the authentication API routes already?

At this point, we have everything we need to implement our login / logout API routes. Let's create the easiest one first in server/api/logout.ts:

import { defineHandle } from "h3";
import { setAuthState } from "~/utils/jwt";

export default defineHandle((_req, res) => {
  return setAuthState(null, res);
});

As you can see, logging out is quite simple!

Now let's add server/api/login.ts:

import { defineHandle, useBody } from "h3";
import { prisma } from "~/prisma/client";
import { setAuthState } from "~/utils/jwt";
import { verifyPassword } from "~/utils/password";

export default defineHandle(async (req, res) => {
  try {
    const { email, password } = await useBody(req);
    const user = await prisma.user.findFirst({ where: { email } });
    if (!user) throw new Error("User does not exist.");
    if (!verifyPassword(password, user.password)) throw new Error("Invalid password");
    return setAuthState(user, res);
  } catch (error) {
    res.statusCode = 401;
    res.statusMessage = (error as Error).message;
    return setAuthState(null, res);
  }
});

In both cases, returning the authentication state in the response body will allow us to keep the client-side authentication state up to date without having to query the GraphQL backend (more on this later).

Authentication / authorization in the backend

This section covers the backend logic required to properly authenticate users and restrict some operations at the field-level based on custom authorization rules.

Getting the authentication state in the context

In order to provide the authentication state to our resolvers, we'll add the auth property on our Context type and set its value from the token passed to contextFactory:

import { prisma } from "../prisma/client";
import type { AuthState } from "../utils/jwt";

export type Context = {
  auth: AuthState;
  prisma: typeof prisma;
};

export const contextFactory = (token: string): Context => {
  return { auth: decodeJwt(token), prisma };
};

To obtain the token from the incoming request, we have to parse its headers and extract the cookie, so let's add a helper in utils/jwt.ts:

import { parse } from "cookie-es";

// Extract JWT token from request headers
export const getTokenFromHeaders = (headers: { cookies: string }): string => {
  const cookies: Record<string, string> = parse(headers.cookies || "");
  return cookies[jwtCookieName] || "";
};

We could also pass the token in the request's authorization header, we'd just have to adjust the code above.

Finally, we need to adjust the options to processRequest in server/api/graphql.ts:

import { getTokenFromHeaders } from "../../utils/jwt";

    // ...
    contextFactory: ({ request }) => contextFactory(getTokenFromHeaders(request.headers as { cookies: string })),
    // ...

Adding field-level authorization rules

Since we don't want to repeat the same authorization patterns over and over again in our resolvers, we'll implement re-usable authorization rules using nexus-shield:

yarn add -D nexus-shield

This package is a Nexus plugin, so we need to add it inside server/schema.ts as an option to makeSchema:

import { nexusShield, allow } from "nexus-shield";

// ...

export default makeSchema({
  plugins: [
    nexusShield({
      defaultError: new Error("Unauthorized"),
      defaultRule: allow,
    }),
  ],
  // ...
}) as unknown as GraphQLSchema;

We'll only define two authorization rules for now (isAuthenticated and hasUserRole) and re-export the provided operators (and, or, etc.), which should cover most cases. I chose to put this inside server/nexus/_rules.ts:

import { generic, ruleType, ShieldCache } from "nexus-shield";
import type { UserRole } from "@prisma/client";

export { and, or, chain, not, race } from "nexus-shield";

export const isAuthenticated = generic(
  ruleType({
    cache: ShieldCache.CONTEXTUAL,
    resolve: (_root, _args, { auth }) => {
      return !!auth.user;
    },
  }),
);

export const hasUserRole = (role: UserRole) =>
  generic(
    ruleType({
      cache: ShieldCache.CONTEXTUAL,
      resolve: (_root, _args, { auth }) => {
        return [role, "ADMIN"].includes(auth.user?.role || "");
      },
    }),
  );

As you can see from the code above, isAuthenticated simply checks if the user is authenticated while hasUserRole checks for a specific role (with "ADMIN" always being authorized).

Using these rules in our Nexus types is quite straightforward, for example our hello query can be restricted to the "EDITOR" role like so:

import { extendType } from "nexus";
import { hasUserRole } from "./_rules";

export const HelloQuery = extendType({
  type: "Query",
  definition(t) {
    t.nonNull.field("hello", {
      type: "String",
      resolve: () => `Hello Nexus`,
      shield: hasUserRole("EDITOR")(),
    });
  },
});

To learn about different rule types, caching and more, please refer to the nexus-shield documentation.

Authentication / authorization in the frontend

This section covers the frontend logic required to access the currently authenticated user from our pages, components and navigation.

Getting the authentication state in a composable

To make things as simple as possible for our components, we'll create a useAuth composable that will return various helpers for managing authentication & authorization logic (login, logout, authorization rules, etc.)

Let's begin by defining a reactive and SSR-friendly shared state in a server plugin. Essentially, this plugin initializes the authentication state (auth) with the decoded JWT cookie on each request. The code for this goes in plugins/auth.server.ts:

import type { AuthState } from "~/utils/jwt";
import { jwtCookieName, decodeJwt } from "~/utils/jwt";

export default defineNuxtPlugin(() => {
  const token = useCookie(jwtCookieName).value;
  useState<AuthState>("auth", () => decodeJwt(token));
});

With the auth state initialized by our Nuxt server plugin on each request, we can implement useAuth in composables/auth.ts:

import { UserRole } from "@prisma/client";
import type { AuthState } from "~/utils/jwt";

export const useAuth = () => {
  // Current authentication state (initialized in plugins/auth.server.ts)
  const auth = useState<AuthState>("auth", () => ({ user: null }));

  // Authorization rules
  const isAuthenticated = computed<boolean>(() => !!auth.value.user?.id);
  const hasUserRole = (role: UserRole) => ["ADMIN", role].includes(auth.value.user?.role || "");

  // Authentication helpers
  const login = async (credentials: { email: string; password: string }) => {
    const result = await $fetch("/api/login", { method: "POST", body: credentials });
    auth.value = result;
  };
  const logout = async () => {
    const result = await $fetch("/api/logout", { method: "POST" });
    auth.value = result;
  };

  return { auth, isAuthenticated, hasUserRole, login, logout };
};

Defining the authentication process

Creating useful navigation guards requires having a minimal set of routes and navigation logic for the authentication process (i.e. login form, redirect on success / failure, etc.)

To keep things simple, we'll define the following routes:

/ : Front page
/login : Login page (with optional redirect parameter)
/secret : Secret page (requires authentication)

When trying to navigate to /secret, the user should be taken to /login?redirect=/secret, then redirected to /secret upon a successful login.

Login / logout forms

Again let's start with the most obvious of the two, components/form/logout.vue:

<script setup lang="ts">
const { logout } = useAuth();
async function onLogout() {
  await logout();
  location.reload();
}
</script>

<template>
  <button @click="onLogout">Logout</button>
</template>

In the code above, we force a location.reload() to reset the GraphQL client SSR cache.

Let's create a basic login form in components/form/login.vue (see the next article of this series for the final component with full validation):

<script setup lang="ts">
const { login } = useAuth();
const credentials = reactive({
  email: "",
  password: "",
});
const error = ref<string>("");

async function onLogin() {
  try {
    await login(credentials);
    const { query } = useRoute();
    useRouter().push((query as { redirect: string }).redirect || "/");
  } catch (e) {
    error.value = (e as Error).message;
  }
}
</script>

<template>
  <form class="space-y-1.5" @submit.prevent="onLogin">
    <p v-if="error">{{ error }}</p>
    <div><input v-model="credentials.email" type="email" placeholder="Email" /></div>
    <div><input v-model="credentials.password" type="password" placeholder="Password" /></div>
    <div>
      <button type="submit" class="btn">Login</button>
    </div>
  </form>
</template>

We leave out the CSS for the .btn component as an exercise for the reader :)

<script setup lang="ts">
const { isAuthenticated } = useAuth();
</script>

<template>
  <div class="py-3 bg-slate-800 text-white">
    <nav class="container">
      <ul class="flex items-center gap-6">
        <li>
          <NuxtLink to="/">Home</NuxtLink>
        </li>
        <li v-if="isAuthenticated">
          <NuxtLink to="/secret">Secret</NuxtLink>
        </li>
        <li class="ml-auto">
          <NuxtLink v-if="!isAuthenticated" to="/login">Login</NuxtLink>
          <FormLogout v-else />
        </li>
      </ul>
    </nav>
  </div>
</template>

This component can then be added in layouts/default.vue.

Implementing the authorization middleware

Before creating our pages, we need a way to prevent users from navigating to protected routes under certain circumstances. These helpers are referred to as navigation guards and they are implemented using Nuxt middlewares.

For the sake of isomorphism, we'll try to reproduce the authorization rules from our backend, i.e. isAuthenticated and hasUserRole.

The first one goes in middleware/is-authenticated.ts:

export default defineNuxtRouteMiddleware((to, from) => {
  const { isAuthenticated } = useAuth();
  if (!isAuthenticated.value) {
    return navigateTo(`/login?redirect=${to.fullPath}`);
  }
});

You see how the useAuth composable is already coming in handy? Also note we are sending the current full path as a redirect query parameter to our login page so the user can be redirected back after a successful login.

Applying this middleware to a page is done via the page metadata like so:

<script setup lang="ts">
definePageMeta({
  middleware: ["is-authenticated"],
});
</script>

You probably have already guessed that the second navigation guard goes in middleware/has-user-role.ts:

import type { UserRole } from "@prisma/client";

export default defineNuxtRouteMiddleware((to, from) => {
  const { isAuthenticated, hasUserRole } = useAuth();
  if (!isAuthenticated.value) {
    return navigateTo(`/login?redirect=${to.fullPath}`);
  } else if (!hasUserRole(to.meta.hasUserRole || "ADMIN")) {
    return abortNavigation("You do not have permission to visit this page.");
  }
});

declare module "nuxt3/dist/pages/runtime/composables" {
  interface PageMeta {
    hasUserRole?: UserRole;
  }
}

There is a lot to point out in the code above. First, if the user is not authenticated at all, we redirect just like is-authenticated to allow a chance of logging in. Then if the user doesn't have the proper role, it's a dead-end so we abort the navigation (I'm still looking for a nicer way of letting the user know something was wrong).

As for the PageMeta interface extension right below, this is used to add typings to definePageMeta so it accepts a UserRole that will be used as a parameter to the middleware, like so:

<script setup lang="ts">
definePageMeta({
  middleware: ["has-user-role"],
  hasUserRole: "EDITOR",
});
</script>

Creating the secret and login pages

At last, we can create the missing pages to achieve the authentication process described earlier.

First, let's take a look at pages/secret.vue:

<script setup lang="ts">
definePageMeta({
  middleware: ["is-authenticated"],
});
</script>

<template>
  <div id="secret-page" class="prose">
    <h1>Secret page</h1>
  </div>
</template>

And as for pages/login.vue:

<script setup lang="ts">
definePageMeta({
  middleware: ["is-not-authenticated"],
});
</script>

<template>
  <div id="login-page" class="prose">
    <h1>Login page</h1>
    <div class="not-prose">
      <FormLogin />
    </div>
  </div>
</template>

We left out middleware/is-not-authenticated.ts as another exercise for the reader! Also, know that definePageMeta can be used for SEO as well.

So that's it, our application now features isomorphic authentication and authorization with a great DX!

SSR friendly GraphQL client

Pascal Martineau — Wed, 23 Feb 2022 13:55:20 +0000

In the previous article, we generated type safe GraphQL composables from .graphql files to be used in our VueJS frontend code. Under the hood, the generated functions rely on the @urql/vue client, which should be configured first before attempting to access our GraphQL operations.

Configuring @urql/vue with a Nuxt3 plugin

To get started, we can provide a basic @urql/vue client with a plugin in plugins/urql.ts:

import urql from "@urql/vue";
import { defineNuxtPlugin, useRuntimeConfig } from "#app";

export default defineNuxtPlugin((nuxtApp) => {
  const { graphqlApiURL } = useRuntimeConfig();

  nuxtApp.vueApp.use(urql, {
    url: graphqlApiURL,
  });
});

We provide graphqlApiURL as a public runtime configuration inside nuxt.config.ts:

publicRuntimeConfig: {
  graphqlApiURL: process.env.GRAPHQL_API_URL || "http://localhost:3000/api/graphql",
}

We could try to determine the API URL based on Nuxt options at build or run time, but it's so much easier to define it explicitly.

Setting up the SSR exchange

When executing queries in a page and/or component(s), the fetched results can be combined and serialized in the page payload sent by the server, then rehydrated by the client upon rendering.

To achieve this, we'll need to override urql's default exchanges by adding the configured SSR exchange at the proper index in the array.

The relevant code for setting this up looks like this:

// ...
import urql, { cacheExchange, dedupExchange, fetchExchange, ssrExchange } from "@urql/vue";

// ...
  // Create SSR exchange
  const ssr = ssrExchange({
    isClient: process.client,
  });

  // Extract SSR payload once app is rendered on the server
  if (process.server) {
    nuxtApp.hook("app:rendered", () => {
      nuxtApp.payload?.data && (nuxtApp.payload.data.urql = ssr.extractData());
    });
  }

  // Restore SSR payload once app is created on the client
  if (process.client) {
    nuxtApp.hook("app:created", () => {
      nuxtApp.payload?.data && ssr.restoreData(nuxtApp.payload.data.urql);
    });
  }

  // Custom exchanges
  const exchanges = [dedupExchange, cacheExchange, ssr, fetchExchange];
// ...

The exchanges array is then passed to urql's options to override the default ones.

I'm not 100% sure about the server/client payload handling code above but it works (there might be some Nuxt helpers for achieving this in a simpler way).

Bonus: Configuring the devtools exchange

It can be useful to debug urql with its official devtools. Let's add it to our dependencies:

yarn add -D @urql/devtools

We can then prepend it to our custom exchanges in plugins/urql.ts:

import { devtoolsExchange } from "@urql/devtools";

// ...
  // Devtools exchange
  if (nuxtApp._legacyContext?.isDev) {
    exchanges.unshift(devtoolsExchange);
  }
// ...

And voilà, our app should now expose debug events in the devtools panel, provided the extension is properly installed in your browser.

Using the generated operations

Since our generated operations can be auto-imported (see the previous article), executing our { hello } query is as simple as this:

<script setup lang="ts">
const { data } = await useHelloQuery();
</script>

<template>
  <div id="front-page" class="prose">
    <h1>{{ data?.hello || "Nuxt3 ❤️ GraphQL" }}</h1>
  </div>
</template>

How amazing is that? Thanks to the <script setup> syntax and auto-importing, one line of TypeScript is all it takes to execute our generated query operation and access the result with full type safety!

What about mutations (and subscriptions)?

Using generated mutation operations isn't very different than using queries, the main difference being that the mutation isn't executed automatically. Instead, we have to use the executeMutation method on the result object returned from our generated composable, i.e. useSomeMutation.

As for subscriptions, we'll need to configure some kind of transport to use them. This will be the subject of an upcoming article in this exciting series!

For more information, please refer to the @urql/vue documentation on mutations and subscriptions.

End to end type safety

Pascal Martineau — Wed, 23 Feb 2022 13:48:41 +0000

One of the best things about GraphQL and TypeScript is the prospect of end to end type safety, i.e. having strict type checking and auto-completion from the back end all the way to the front end. This makes for a great DX and can potentially prevent errors as well.

In order to achieve this, our project can leverage code generation to alleviate the tedious process of manually creating the typings for our GraphQL schema and operations. The fine people at The Guild (who are also responsible for GraphQL Helix) have put together a powerful tool called GraphQL Code Generator to do exactly that.

Setting up GraphQL Code Generator

First of all, we'll add the required packages:

yarn add -D @graphql-codegen/cli @graphql-codegen/typescript

We'll need a codegen.yml configuration file at the root of our project. A simple configuration looks like this:

schema: generated/schema.graphql
generates:
  generated/schema.ts:
    plugins:
      - typescript

We could use http://localhost:3000/api/graphql instead of generated/schema.graphql to enable executing our operations directly from VS Code but this requires having the development server constantly running in the background (the code generation would also fail otherwise).

Let's add a codegen script to our package.json for running the code generation:

"codegen": "NODE_NO_WARNINGS=1 graphql-codegen",

The annoying ExperimentalWarning: stream/web is an experimental feature. can be hidden by adding NODE_NO_WARNINGS=1 in front of the codegen script in package.json.

We can now generate the typings with yarn codegen or watch for changes with yarn codegen -w.

Generating type safe GraphQL operations

Now that we have generated the schema types, it's time to generate typings for our GraphQL operations as well (queries, mutations and subscriptions). For this purpose, the choice of generator plugins will depend on the GraphQL client we plan on using, in our case @urql/vue (see the next article of the series for details).

Let's add @urql/vue and the required graphql-codegen plugins:

yarn add -D @urql/vue @graphql-codegen/near-operation-file-preset @graphql-codegen/typescript-operations @graphql-codegen/typescript-vue-urql

Then we need to configure documents and add an entry under generates for our desired output inside codegen.yml:

schema: generated/schema.graphql
documents: graphql/**/*.graphql
generates:
  generated/schema.ts:
    plugins:
      - typescript
  composables/:
    preset: near-operation-file
    presetConfig:
      baseTypesPath: ../generated/schema.ts
      extension: .ts
      folder: ../composables
    config:
      documentMode: documentNode
    plugins:
      - typescript
      - typescript-operations
      - typescript-vue-urql

As you can see, our source documents will live in .graphql files under the graphql/ directory and the type safe operations will be generated in composables/*.ts. By using @graphql-codegen/near-operation-file-preset, we can generate one file per operation and thus benefit from the auto importing feature of Nuxt3 (again, see the next article of this series).

For more information on the options above, please refer to the various graphql-codegen plugins' documentation.

Before code generating again, we'll need to create at least one operation file, so let's add graphql/hello.query.graphql:

query Hello {
  hello
}

It's important to name your operations inside each document file since the generated composables will be named accordingly, i.e. query Hello becomes useHelloQuery.

We can also make sure the generated code will be properly formatted by adding a command to the afterAllFileWrite hook in codegen.yml:

hooks:
  afterAllFileWrite:
    - eslint --fix ./generated ./composables

Finally, there are some options that are needed in nuxt.config.ts to prevent runtime errors with @urql/vue and to enable strict type-checking:

build: {
  transpile: ["@urql/vue"],
},
typescript: { strict: true },

We're now ready to start using our type safe operations on the front end!

Code-first schema definition

Pascal Martineau — Wed, 23 Feb 2022 13:40:33 +0000

Having the Prisma client ready to work with our data on the server side is great, although we still need to define and expose a GraphQL API for interacting with the front end.

But before setting up the GraphQL API endpoint, it's a good idea to create a basic schema first.

Defining the schema using Nexus types

The code-first approach we propose here is based on Nexus, since it will eventually have first-class integration with Prisma (see here).

Let's add Nexus and GraphQL to our project:

yarn add -D nexus graphql

We can structure the server-side source code to make it somewhat scaleable by having our main schema file in server/schema.ts and all of our Nexus types in nexus/*.ts (we don't use types/ to avoid confusion with TypeScript types).

Also, exporting all of these types from a single source file simplifies the schema construction, and naming it server/nexus/_types.ts will keep this file above the others inside the directory. We could also use server/nexus/**/*.ts and server/nexus/index.ts for larger projects.

With this structure in mind, let's create server/schema.ts:

import { resolve } from "pathe";
import { GraphQLSchema } from "graphql";
import { makeSchema } from "nexus";
import * as types from "./nexus/_types";

export default makeSchema({
  types,
  shouldGenerateArtifacts: process.env.NODE_ENV === "development",
  outputs: {
    schema: resolve(process.cwd(), "generated/schema.graphql"),
    typegen: resolve(process.cwd(), "generated/nexus-types.ts"),
  },
}) as unknown as GraphQLSchema;

We need to cast the schema using as unknown as GraphQLSchema until Nexus properly supports GraphQL 16, see this issue for details.

We set shouldGenerateArtifacts and outputs so that Nexus will generate the exposed GraphQL schema and its corresponding typings in the generated/ directory (in development mode only). These are useful for type safety and generating further artifacts with graphql-codegen (see the next article of this series).

Since we only want a minimal schema at this point, let's create a simple hello query in server/nexus/hello.ts (see the Nexus documentation to learn more):

import { extendType } from "nexus";

export const HelloQuery = extendType({
  type: "Query",
  definition(t) {
    t.nonNull.field("hello", {
      type: "String",
      resolve: () => `Hello Nexus`,
    });
  },
});

... and export it in server/nexus/_types.ts:

export * from "./hello";

Our schema is now ready to be exposed via a GraphQL API.

Exposing the GraphQL API endpoint

While there are many GraphQL server packages available, we need one that will play nicely with Nuxt3's server engine (Nitro / h3). In the spirit of keeping things extensible and framework-agnostic, GraphQL Helix seems like a really good choice. Let's add it to our project:

yarn add -D graphql-helix

With Nuxt3's auto-discovery of API endpoints, we can setup the /api/graphql endpoint by simply creating the server/api/graphql.ts file, and using GraphQL Helix to process the incoming request in the handler function:

import { defineHandle, useBody, useQuery } from "h3";
import { getGraphQLParameters, processRequest, renderGraphiQL, sendResult, shouldRenderGraphiQL } from "graphql-helix";
import schema from "../schema";

export default defineHandle(async (req, res) => {
  // Construct GraphQL request
  const request = {
    body: req.method !== "GET" && (await useBody(req)),
    headers: req.headers,
    method: req.method || "GET",
    query: useQuery(req),
  };

  // Render GraphiQL in development only
  if (process.env.NODE_ENV === "development" && shouldRenderGraphiQL(request))
    return renderGraphiQL({ endpoint: "/api/graphql" });

  // Process GraphQL request and send result
  const { operationName, query, variables } = getGraphQLParameters(request);
  const result = await processRequest({
    operationName,
    query,
    variables,
    request,
    schema,
  });
  sendResult(result, res);
});

We now have a GraphQL over HTTP specification-compliant server exposing the schema we built with Nexus types.

You may have noticed from the code above that we also get a configured GraphiQL instance at http://localhost:3000/api/graphql in development mode, nice!

Providing the GraphQL execution context

To be useful, our resolvers need access to the Prisma client instance and eventually to the currently logged-in user. These are usually passed to the resolvers in the GraphQL execution context. Fortunately, GraphQL Helix provides an easy way to provide this with full type safety.

First, we'll define our Context type and its corresponding context factory function inside server/context.ts:

import { prisma } from "../prisma/client";

export type Context = {
  prisma: typeof prisma;
};

export async function contextFactory(): Promise<Context> {
  return { prisma };
}

Then, back in our handler function inside server/api/graphql.ts, we'll pass contextFactory to processRequest and specify Context as its type variable:

import type { Context } from "../context";
import { contextFactory } from "../context";

// ...
  const result = await processRequest<Context>({
    // ...
    contextFactory,
  });
// ...

Finally, we have to configure Nexus to use our Context type in server/schema.ts by setting the contextType option in makeSchema like so:

export default makeSchema({
  // ...
  contextType: {
    module: resolve(process.cwd(), "server/context.ts"),
    export: "Context",
  },
}) as unknown as GraphQLSchema;

After running yarn dev to update generated/nexus-types.ts, our resolvers should have access to the fully-typed execution context.

Projecting the Prisma schema

Defining the exposed GraphQL schema will often involve re-creating our Prisma models using Nexus types, which can be tedious and error-prone. By using the official Prisma plugin for Nexus, we can easily project models from the data layer unto GraphQL types in our API layer.

Please note that nexus-prisma is still in early preview, so it should not be used in production right now.

Now that you've been warned, let's add it to our project:

yarn add -D nexus-prisma

We first need to add a nexus-prisma generator block in prisma/schema.prisma:

generator nexusPrisma {
  provider = "nexus-prisma"
}

This will generate the available Nexus types directly in node_modules/nexus-prisma/ on the next prisma generate. Similarly to the Prisma client, this package does not work well with ES modules (see this issue), so until it does we have to re-export all of our models and enums in prisma/nexus.ts:

import NP, * as NPS from "nexus-prisma/dist-cjs/entrypoints/main";

export const User = NP?.User || NPS?.User;
export const UserRole = NP?.UserRole || NPS?.UserRole;

To project the User and UserRole in our API layer, we add the following in server/nexus/user.ts (remember to export it from server/nexus/_types.ts):

import { enumType, objectType } from "nexus";
import { User, UserRole } from "../../prisma/nexus";

export const UserRoleEnum = enumType(UserRole);

export const UserObject = objectType({
  name: User.$name,
  description: User.$description,
  definition(t) {
    t.field(User.id);
    t.field(User.email);
    t.field(User.role);
  },
});

You'll notice in the code above that we omitted the password field so it can never be returned by our API.

While this example only covers the basic features of nexus-prisma, feel free to read its documentation to learn more.

Declarative database modelling

Pascal Martineau — Wed, 23 Feb 2022 13:34:29 +0000

Easily defining our app's data model in a declarative way requires some kind of ORM. Among the many solutions available, Prisma seems like a solid choice for many reasons: it's actively maintained, stable and performant, has lots of supported databases, etc.

Setting up Prisma

Let's add the Prisma client and CLI packages as development dependencies:

yarn add -D @prisma/client prisma

We can now initialize the Prisma configuration with the following:

yarn prisma init

This creates the .env and prisma/schema.prisma files which will respectively hold our database URL and Prisma schema definition.

Assuming a MySQL database, DATABASE_URL would look like this in .env:

DATABASE_URL=mysql://dbuser:dbpassword@localhost:3306/dbname

As for the Prisma schema file, this is where we'll define our data sources, generators and data models.

If using VS Code, which I strongly recommend, installing the official Prisma extension will give us syntax highlighting, linting, code completion, formatting, jump-to-definition and more when editing the schema file.

Data sources

A data source determines how Prisma connects to the database, in our case MySQL. While the corresponding definition block is already present in the freshly initialized prisma/schema.prisma, we'll need to adjust the provider value to match our database type like so:

datasource db {
  provider = "mysql"
  url      = env("DATABASE_URL")
}

Generators

A generator determines which assets are created when we execute prisma generate. For now, we only need the default definition block for the JavaScript client:

generator client {
  provider = "prisma-client-js"
}

Data models

Finally, we can declare our data model by adding definition blocks for our entities and enums. In our case, we'll pave the way for authentication by defining a User model and UserRole enum:

model User {
  id       Int      @id @default(autoincrement())
  email    String   @unique
  password String
  role     UserRole @default(UNVERIFIED)
}

enum UserRole {
  UNVERIFIED
  GUEST
  EDITOR
  ADMIN
}

Generating the Prisma client

We're now ready to generate the Prisma client from our schema file, which will create the type-safe query engine runtime in node_modules/.prisma/client (which in turn is exposed via the @prisma/client package).

Although I did successfully use nodemon in the past to watch for schema changes and regenerate the Prisma client automatically, having multiple watchers for different purposes seemed a little bloated. Using a Nuxt module to achieve this would be a lot cleaner IMHO.

That being said, I now prefer hooking up the postinstall script in package.json to generate on each yarn install:

"postinstall": "prisma generate"

Database migration workflow

Having generated the client, we still need the actual database to reflect our schema with the proper tables and columns. This process is referred to as migrating the database.

The Prisma CLI provides two commands to achieve this: db push and migrate.

As our data model evolves, we can apply any pending changes to the database with the first method:

yarn prisma db push

Once we're ready to commit these changes to source control, we use the second method, which requires naming the migration with the name parameter (prompted if missing):

yarn prisma migrate dev --name initial-user-model

Seeding the database

In order to consistently populate our database with some default data (for example, an administrator user), we'll create a prisma/seed.ts seeding script which will be executed with ts-node, so let's add it to our project:

yarn add -D ts-node

We can instruct Prisma's integrated seeding functionality to execute prisma/seed.ts by adding the following section in package.json:

"prisma": {
  "seed": "ts-node --compiler-options {\"module\":\"CommonJS\"} prisma/seed.ts"
}

Note the --compiler-options needed to import the @prisma/client package properly (more on this later).

In this case, the data we want to seed corresponds to the default user's email, password and role. Since we want our seeding scripts to be modular, let's create prisma/seeds/users.ts (yes, the password will eventually be encrypted):

import { PrismaClient, UserRole } from "@prisma/client";

export async function seedUsers(prisma: PrismaClient) {
  // Default admin user
  const admin = {
    email: process.env.SEED_ADMIN_EMAIL || "admin@example.com",
    // TODO: Encrypt password
    password: process.env.SEED_ADMIN_PASSWORD || "changeme",
    role: UserRole.ADMIN,
  };
  return await prisma.user.upsert({
    where: { email: admin.email },
    create: admin,
    update: admin,
  });
}

In order to import all of scripts at once, we re-export every file in prisma/seeds/index.ts:

export * from "./users";

Finally, we create our main seeding script prisma/seed.ts:

import { PrismaClient } from "@prisma/client";
import * as seeds from "./seeds";

const prisma = new PrismaClient();

async function main() {
  for (const seed of Object.values(seeds)) {
    console.log(await seed(prisma));
  }
}

main()
  .catch((e) => {
    console.error(e);
    process.exit(1);
  })
  .finally(async () => {
    await prisma.$disconnect();
  });

We can now seed the database with the following:

yarn prisma db seed

Resetting the database will also execute the seeding script:

yarn prisma migrate reset

Importing the Prisma client in Nuxt3

In production, Nitro bundles the environment variables at build time, but the Prisma runtime doesn't understand that for DATABASE_URL. As a workaround, we can use dotenv to make sure our .env file is always loaded no matter what:

yarn add -D dotenv

Also, until @prisma/client supports proper ES modules exports (see this issue), we can re-export it from a helper file in prisma/client.ts like so:

import { config } from "dotenv";
import Prisma, * as PrismaScope from "@prisma/client";
const PrismaClient = Prisma?.PrismaClient || PrismaScope?.PrismaClient;

// Load process.env.DATABASE_URL from .env
config();

export const prisma = new PrismaClient();

Please note that the current setup probably won't work in a serverless environment as this would require configuring Prisma Data Proxy. I plan on adding support for serverless deployments in the future but I wanted to get things working nicely in NodeJS first.

Exploring our data

Prisma Studio allows us to explore and edit the data visually by running:

yarn prisma studio

Nuxt3 ️ GraphQL

Pascal Martineau — Wed, 23 Feb 2022 13:21:35 +0000

The repository containing the example code for this series is available here.

For some time I've been trying to assemble a full stack solution based on Nuxt and GraphQL. Now that Nuxt3 RC ~~is just around the corner~~ has landed, I figured it would be interesting to explore its full stack capabilities with the following goals in mind:

Declarative database modelling
Code-first schema definition
End to end type safety
SSR friendly GraphQL client
Isomorphic authentication / authorization
Form generation and validation

Conveniently, these features correspond to the following projects:

This series aims to document my progress towards integrating these in a full stack application boilerplate.

Initializing the Nuxt3 project

First things first, let's create a Nuxt3 project:

npx nuxi init nuxt3-fullstack
cd nuxt3-fullstack && yarn install

Starting the development server will generate the .nuxt/tsconfig.json TypeScript configuration extended by tsconfig.json:

yarn dev

Automatic code formatting

It's also a good idea to add ESLint for automatic code formatting with the preset of your choice:

yarn add -D eslint @lewebsimple/eslint-config-vue

The ESLint configuration can be defined with the following section inside package.json :

"eslintConfig": {
  "extends": "@lewebsimple/eslint-config-vue"
}

If your IDE is configured properly, saving a source file should now reformat it automatically (this might require restarting the TypeScript language service). Otherwise, we can manually lint the project with the following script (which should be added to the corresponding section in package.json):

"lint": "eslint --fix --ignore-path .gitignore ."

Bonus: Adding Tailwind CSS

Let's add Tailwind CSS because we're really cool:

yarn add -D @nuxtjs/tailwindcss @tailwindcss/forms @tailwindcss/line-clamp @tailwindcss/typography

We need to add @nuxtjs/tailwindcss to modules in nuxt.config.ts:

import { defineNuxtConfig } from "nuxt3";

// https://v3.nuxtjs.org/docs/directory-structure/nuxt.config
export default defineNuxtConfig({
  modules: ["@nuxtjs/tailwindcss"],
  tailwindcss: {
    viewer: false,
  },
});

Then generate and adjust tailwind.config.js:

npx tailwindcss init

/* eslint-disable @typescript-eslint/no-var-requires */

module.exports = {
  theme: {
    extend: {
      container: {
        center: true,
        padding: "1.5rem",
      },
      typography: {
        DEFAULT: {
          css: {
            maxWidth: "none",
          },
        },
      },
    },
  },
  plugins: [
    require("@tailwindcss/forms"),
    require("@tailwindcss/line-clamp"),
    require("@tailwindcss/typography"),
  ],
};

To display a basic frontend design, we'll delete app.vue, create a default layout in layouts/default.vue:

<template>
  <div class="container py-6">
    <NuxtPage />
  </div>
</template>

... and a default front page in pages/index.vue:

<template>
  <div id="front-page" class="prose">
    <h1>Nuxt3 ❤️ GraphQL</h1>
  </div>
</template>

Wow, such a nice design!

Finishing touches

Now is also a good time to set the project name, description, version and license in package.json and to commit our changes to Git.

We can also setup release-it to manage our release process:

yarn add -D release-it

We can create new releases with the following script in package.json:

"release": "release-it"

With our Nuxt3 project properly initialized, we’re ready to start adding some features!