Getting Started

Aetheris is split into two main packages: @aetheris/server and @aetheris/client. The server package is used to define your API in the backend and the client package is used to call your API on the frontend. Depending on your project, you may want to install these packages into their respective applications.

In this guide, we'll be focusing on the Next.js implementation which installs both packages in the same project.

Installation

pnpm add @aetheris/server @aetheris/client 

Quick Start

Setting up Aetheris is simple and doesn't require much boilerplate. Let's break down everything we need to do to get started.

Creating the router

In an existing Next.js project, create a new file. This can be anywhere in your project, but for this example we will create a new directory and create an index.ts file. In this file we will import createAetheris to create a new Aetheris server.

import { createAetheris } from "@aetheris/server";
 
export const aether = createAetheris();

This function returns a class that gives us a few utilities. These will be used to define your API. Let's begin with creating our appication router. The router function is used to create a new object that defines the entrypoint of our application.

import { createAetheris, router } from "@aetheris/server";
 
const aether = createAetheris();
 
export const app = router({});
 
export type App = typeof app;

We also export the infered type of the router so that we can import it in the future to create our API client.

Next, we can create our first procedure. For now, we'll create a basic hello world procedure.

import { createAetheris, router } from "@aetheris/server";
 
const aether = createAetheris();
 
export const app = router({
    helloWorld: aether.handler({
        resolve: async () => {
            return "Hello, World!";
        },
    }),
});
 
export type App = typeof app;

Creating a route handler

Now that we've created a basic procedure, we can expose this API by creating a Next.js route handler. Create the new file in a directory like src/app/api/[[...slug]]/route.ts and import the router object we created earlier and the createNextHandler function from the @aetheris/server package. The createNextHandler function will create a new Next.js route handler that you can assign to the POST method of your route.

import { createNextHandler } from "@aetheris/server/adapters/next";
import { app } from "@/server";
 
const handler = createNextHandler({
    app,
    // We have to set a prefix to let Aetheris know where the route is located.
    prefix: "/api",
});
 
export const POST = handler;

Creating the API client

After creating this file, we still need a method to call the API. Create a new file in a directory like src/lib/api.ts and import the createClient function from the @aetheris/client package. This function takes a generic type that represents the router object. We can import the App type we exported earlier to use as the generic type. For this example, we will hardcode the base URL, but you will likely need some additional logic to determine the base URL based on the environment.

import type { App } from "@/server";
import { createClient, httpLink } from "@aetheris/client";
 
export const api = createClient<App>({
    links:[
        httpLink({
            baseUrl: "http://localhost:3000/api",
        }),
    ],
});

Calling our API

That's it! We've done everything we need to get started with Aetheris. You can now call the API from anywhere in your project by importing the api object we created earlier. If everything is set up correctly, the API client should be fully typed and will reflect any procedures you define in the server.

export default async function Page() {
    const response = await api.helloWorld(); // Hello World!
 
    return (
      <div>{response}</div>
    );
}