Get started

⚠️

Please make sure that you project is using Babel. I will provide a swc plugin / preset in the future, though it is not ready yet.

This guide focuses on setting up your Next.js project to utilize joice. It is important to note that we will be using the page structure instead of the new app router for the purpose of this guide.

At a high level, there are two key steps involved in making joice work seamlessly:

The Use of Compilation Plugin: Since passing a function directly between the server and client is not feasible, joice employs a compilation plugin, specifically for Babel in this case. This plugin transforms the server code based on the target environment. During runtime, the client then imports an endpoint descriptor object, from which the endpoint signature can be derived.
Environment Configuration: To ensure joice functions optimally, it is essential to configure the environment by customizing the Request and Response types that joice employs. In order to achieve this, we will create a joice-env.d.ts file in the project's root directory.

Let's dive into the step-by-step instructions to set up your Next.js project with joice.

Step-by-Step

Installing the dependencies

To get started with joice, we'll need to install a few essential packages. Make sure to install @joice/joice and @joice/babel. Additionally, it is highly recommended to install @joice/zod for enhanced validation capabilities. What you don't have to install are any kinds of types from a different package, @joice/... ships natively with types.

npm install @joice/joice @joice/zod

npm install -D @joice/babel

We will need the babel dependency only during HMR or when building your project, so we can move it into devDependencies.

Setting up Babel

All you need to do now is update your Babel configuration file (such as .babelrc, babel.config.js, or any other type of Babel config file). This step will ensure that your code is properly transformed and ready to leverage the power of joice. If didn't yet alter the base configuration with which Next.js ships with, you will be able to directly copy and paste the following code. If not, then add the @joice/babel preset right after the next/babel preset:

.babelrc

{
  "presets": ["next/babel", "@joice/babel"]
}

Configuring the environment

This step is only necessary if you are using TypeScript.

If you are using a bare Next.js TypeScript Template, you will be able to get away with copy and pasting the following code segment. If you are already customizing the Request and Response types, either consciously or unconsciously due to type pollution, this might be the most difficult part. For the correct type assertions regarding the req and res types used in the endpoint handlers, we need to make sure that the types are passed correctly and the generic parts are passed down to the actual Response type.

To provde the type information, we will create a joice-env.d.ts file in the root directory of the project (so on the same level as the next-env.d.ts file).

joice-env.d.ts

import type {NextApiRequest, NextApiResponse} from "next";
 
declare module "@joice/joice" {
  interface Request extends NextApiRequest {}
  interface Response<T> extends NextApiResponse<T> {}
}

Introduction