← back

Create a Bun REST API With Elysia & Prisma - Complete Guide

bun
elysia
prisma
backend

In the previous article (which you can check out here) we looked at Bun and how to create a basic REST API without using any external libraries or frameworks. As you might have guessed, although possible, it was not the cleanest code and we had to code for problems that have been solved for a long time (like pulling out a param from a route url).

This time, we will introduce a few new things. We will start with Elysia for handling our routes and validation, this will clean up a lot of code and overall improve the quality of our routes. Then, we will introduce Prisma as our ORM of choice to be able to work with a PostgreSQL database. Finally, we will add Swagger in order to generate documentation for our routes.

Prerequisites

To be able to follow along with this tutorial, there are a few prerequisites:

  • Basic understanding of what a REST API is
  • Basic understanding of JavaScript
  • Bun and Docker installed

Create the Application

Instead of continuing with the REST API we built in the previous article, I’ve decided to start fresh so anyone can follow along with this tutorial. We are still creating a blog application API but using the new fancy tools.

To get started, we need to run the following command (assuming you have Bun already installed):

bun create elysia bun-elysia-prisma

This command will generate a basic Elysia server using Bun for us in order to get up and running a lot faster. I’ve called my project bun-elysia-prisma but feel free to call it whatever you’d like. Your src/index.ts should now look something like this:

import { Elysia } from 'elysia';
 
const app = new Elysia().get('/', () => 'Hello Elysia').listen(3000);
 
console.log(
  `🦊 Elysia is running at ${app.server?.hostname}:${app.server?.port}`
);

Database Setup

In order to work with Prisma, we first need to installed it:

bun add -d prisma

After installing, all we have left to do is initialize it which is done using the following command:

bunx prisma init

You might be wondering if the above is a mistake where I misspelled bun. If you are familiar with Node and npx, you can think of bunx as the npx equivalent for Bun.

Next we have to add the schema for our model. Since we are going for a blog application, we will need a table for our posts. To create this model, all we have to do is add it to prisma/schema.prisma

model Post {
  id        Int      @id @default(autoincrement())
  title     String
  content   String   @db.Text()
  createdAt DateTime @default(now())
  updatedAt DateTime @updatedAt
}

It is pretty self explanatory, but our Post will have an id which is a number that gets automatically incremented, a title, the content, a created at timestamp and an updated at timestamp. We can expand on this further in the future but for now, this will do.

We now have a model, but this model won’t mean much if the work is not also reflected on the database side. Let’s start by creating a database. Since we are running all of this locally, we will run our database in a docker container which we can do by running the following command:

docker run --name dev-postgres -p 5432:5432 -e POSTGRES_PASSWORD=12345678 -d postgres

This will create a docker container for us with the name dev-postgres inside of which our database will be running. To access this database, the username should be postgres and the password will be the one we provided 12345678.

Let’s add our database url to a .env file. This file should have already been created by the prisma init, but if it didn’t we can manually create it at the root of our project. Inside of here, we just add the DATABASE_URL as follows:

DATABASE_URL=postgresql://postgres:12345678@localhost:5432/postgres?schema=public

The last step here will be to create and run our migration. This will take the changes we made to our schema, generate the SQL necessary in order to reflect those changes in the database and running them. Luckily, this step is very straight forward and all we have to do is run:

bunx prisma migrate dev --name create-post-model

You will notice that this created a migrations folder within the prisma folder. As we add more to our schema, all of the changes we make to our database will be tracked here where we can view all of the scripts we’ve ran. This is also useful if we ever have to revert changes in the future, but for now that is all for our database setup!

Database Seeding

To make things easier to test, we can create a script where we insert a bunch of posts into our posts table. These posts are useful in a dev environment for manual testing that things are working as expected with our routes.

We’ll start by updating our package.json to include the command we want to run for seeding.

"prisma": {
  "seed": "node scripts/seed.js"
}

You’ll notice that we are using Node to run our script. This is because at the time of writing this article, there is a bug with Bun where the main module will exit before the async tasks resolve which was resulting in the posts not being inserted into the database by the script.

Next, let’s actually create the folder and file we specified above by creating scripts/seed.js. Inside of here, we will start by importing the prisma client and initializing it:

const { PrismaClient } = require('@prisma/client');
 
const client = new PrismaClient();

We then create our array of posts to be created:

const postsToCreate = [
  {
    id: 1,
    title: 'First Post :)',
    content: 'The first post made',
  },
  {
    id: 2,
    title: 'My Second Post Ever',
    content: 'Only my second post, still working on this',
  },
  {
    id: 3,
    title: 'One more for good measure',
    content:
      "I don't  write a lot but when I do, we end up with this many posts",
  },
  {
    id: 4,
    title: 'Final Post, Thank You',
    content: 'This should be enough posts for testing!',
  },
];

You will notice that for each, I’ve hardcoded an id. This is just a hacky way of ensuring each time we run the script we don’t create more posts. The script will check if these ids exist, if they do, update them but if they don’t, create them.

Next we just have to create the function that will create these posts:

const seed = async (posts) => {
  console.log('Creating posts ...');
 
  for (let i = 0; i < posts.length; i++) {
    const post = posts[i];
    console.log('Creating post:', post);
    await client.post.upsert({
      where: { id: post.id },
      update: post,
      create: post,
    });
  }
};

Lastly, we just have to call the function and provide the list of posts to create:

seed(postsToCreate)
  .then(() => {
    console.log('Created/Updated posts successfully.');
  })
  .catch((error) => {
    console.error('Error:', error);
  })
  .finally(() => {
    client.$disconnect();
    console.log('Disconnected Prisma Client, exiting.');
  });

Now that our seeding script is ready, we can test it by running:

bunx prisma db seed

Routes

If you followed the previous article, you will notice how much nicer this section of the API will look.

Let’s start by first creating our files. We will place everything in a new folder so we will start by creating the src/routes directory. Next, since we will have routes dedicated specifically to posts, let’s create a directory inside of the one we just created, called posts. In here, let’s start with the index.ts file which will hold all of the routes.

import { Elysia } from 'elysia';
 
const postsRoutes = new Elysia({ prefix: '/posts' })
  .get('/', () => 'get all posts')
  .get('/:id', () => 'get post by id')
  .post('/', () => 'create post')
  .patch('/:id', () => 'update post')
  .delete('/', () => 'delete post');
 
export default postsRoutes;

Just like before, we are handling the following routes:

  • GET — post by ID
  • GET — all posts
  • POST — create post
  • PATCH — edit post
  • DELETE — delete post by ID

For now, our routes simply just return a string with the action they should be doing. Let’s connect everything before worrying about handling each action.

Inside of src/index.ts we can now add our posts routes, which will look something like this:

import { Elysia } from 'elysia';
import postsRoutes from './routes/posts';
 
const app = new Elysia();
 
app
  .group('/api', (app) => app.use(postsRoutes))
  .listen(process.env.PORT || 3049);
 
console.log(
  `🦊 Elysia is running at http://${app.server?.hostname}:${app.server?.port}`
);

The .group() is not necessary here, but it will be once we add other routes. The purpose of it is to add the /api prefix to all of the routes it wraps. Together with the prefix: '/posts' that we set when setting up our posts routes, the base path for our posts is localhost:3049/api/posts.

Let’s also quickly create a file which has only one job: export the prisma client. This is just so our code looks a lot cleaner whenever we need to access our database. We will place the following code in src/db/index.ts

import { PrismaClient } from '@prisma/client';

const prisma = new PrismaClient();

export default prisma;

Now that we have the base of our routing set up, we can focus on the handlers for each route. We will place all of the, in src/routes/posts/handlers.ts

GET — All Posts

/**
 * Getting all posts
 */
export async function getPosts() {
  try {
    return await db.post.findMany({ orderBy: { createdAt: 'asc' } });
  } catch (e: unknown) {
    console.error(`Error getting posts: ${e}`);
  }
}

This is a very straight forward handler, but the thing you might have noticed is I am ordering the posts returned by their createdAt. This is just so the posts are always returned in the same order.

For this example, if we encounter any errors we will simply just console.error() them.

GET — Post By ID

/**
 * Getting a post by ID
 */
export async function getPost(id: number) {
  try {
    const post = await db.post.findUnique({
      where: { id },
    });
 
    if (!post) {
      throw new NotFoundError('Post not found.');
    }
 
    return post;
  } catch (e: unknown) {
    console.error(`Error finding post: ${e}`);
  }
}

You will notice, outside of the check for what the .findUnique returns, there is no validation on the id being passed in. That is because we will add the validation on the route itself after.

This route simply just takes an id and tries finding that id in the database. If we don’t find the post, we simply just throw a NotFoundError and log it.

POST — Create Post

/**
 * Creating a post
 */
export async function createPost(options: { title: string; content: string }) {
  try {
    const { title, content } = options;
 
    return await db.post.create({ data: { title, content } });
  } catch (e: unknown) {
    console.error(`Error creating post: ${e}`);
  }
}

Creating a post will require a title and the content for the post. Once these are passed in, we can simply just call db.post.create() with the data and it will be inserted into the database. If any issue is encountered here, the error will be logged.

PATCH — Update Post

/**
 * Updating a post
 */
export async function updatePost(
  id: number,
  options: { title?: string; content?: string }
) {
  try {
    const { title, content } = options;
 
    return await db.post.update({
      where: { id },
      data: {
        ...(title ? { title } : {}),
        ...(content ? { content } : {}),
      },
    });
  } catch (e: unknown) {
    console.error(`Error updating post: ${e}`);
  }
}

Updating a post is a bit trickier. This is because the user does not have to update both at the same time. They can update just the title or just the content or both. We need to be able to do partial updates. I’ve accomplished this through ternary operators for the data provided to the update. For example, if the title is provided, we spread the value into the data object, otherwise we omit it.

DELETE — Delete Post

/**
 * Deleting a post
 */
export async function deletePost(options: { id: number }) {
  try {
    const { id } = options;
 
    return await db.post.delete({
      where: { id },
    });
  } catch (e: unknown) {
    console.error(`Error deleting post: ${e}`);
  }
}

Deleting a post is based on the id we get provided in the body of the request. Once we have the id, it is as simple as just providing that id to db.post.delete().

All Handlers Together

If we put all of this together, our handlers.ts should look like this:

import { NotFoundError } from 'elysia';
import db from '../../db';
 
/**
 * Getting all posts
 */
export async function getPosts() {
  try {
    return await db.post.findMany({ orderBy: { createdAt: 'asc' } });
  } catch (e: unknown) {
    console.error(`Error getting posts: ${e}`);
  }
}
 
/**
 * Getting a post by ID
 */
export async function getPost(id: number) {
  try {
    const post = await db.post.findUnique({
      where: { id },
    });
 
    if (!post) {
      throw new NotFoundError('Post not found.');
    }
 
    return post;
  } catch (e: unknown) {
    console.error(`Error finding post: ${e}`);
  }
}
 
/**
 * Creating a post
 */
export async function createPost(options: { title: string; content: string }) {
  try {
    const { title, content } = options;
 
    return await db.post.create({ data: { title, content } });
  } catch (e: unknown) {
    console.error(`Error creating post: ${e}`);
  }
}
 
/**
 * Updating a post
 */
export async function updatePost(
  id: number,
  options: { title?: string; content?: string }
) {
  try {
    const { title, content } = options;
 
    return await db.post.update({
      where: { id },
      data: {
        ...(title ? { title } : {}),
        ...(content ? { content } : {}),
      },
    });
  } catch (e: unknown) {
    console.error(`Error updating post: ${e}`);
  }
}
 
/**
 * Deleting a post
 */
export async function deletePost(options: { id: number }) {
  try {
    const { id } = options;
 
    return await db.post.delete({
      where: { id },
    });
  } catch (e: unknown) {
    console.error(`Error deleting post: ${e}`);
  }
}

Now that we have all of our handlers, let’s add them to our routes:

import {
  createPost,
  getPost,
  getPosts,
  updatePost,
  deletePost,
} from './handlers';
 
const postsRoutes = new Elysia({ prefix: '/posts' })
  .get('/', () => getPosts())
  .get('/:id', ({ params: { id } }) => getPost(id))
  .post('/', ({ body }) => createPost(body))
  .patch('/:id', ({ params: { id }, body }) => updatePost(id, body))
  .delete('/', ({ body }) => deletePost(body));

You will notice TypeScript is complaining here. This is because it doesn’t know the types of the params and bodies coming into the requests. This is a very simple fix with Elysia, as all we have to do is add validation. Once validation is in place, TypeScript will be able to infer the types.

We can start with the route to get a post by id. When the id is pulled from the params, it will be a string but we want it as a number. In order to achieve this, we first have to import t from elysia then we can do the following:

.get('/:id', ({ params: { id }}) => getPost(id), {
  params: t.Object({
    id: t.Numeric(),
  })
})

For the id, we have two types we can use: Number or Numeric. The difference here being that Number simply just validates that what was passed in is indeed a number, whereas Numeric also converts it to a number if it isn’t one.

When creating a post, we can validate that the title and content passed into the body are strings, but we can also take it a step further by setting the minimum and maximum lengths we want these strings to be.

.post('/', ({ body }) => createPost(body), {
  body: t.Object({
    title: t.String({
      minLength: 3,
      maxLength: 50,
    }),
    content: t.String({
      minLength: 3,
      maxLength: 50,
    }),
  })
})

Next, we have to validate the patch route. Here we not only have both params and the body to validate, but the title and content are both optional since the user should be able to provide just one to update. The issue is, if both are optional, how do we stop them from hitting the route with no data? This achieved by specifying a number of minimum properties on the body so that at least one of them is present.

.patch('/:id', ({ params: { id }, body }) => updatePost(id, body), {
  params: t.Object({
    id: t.Numeric(),
  }),
  body: t.Object({
    title: t.Optional(t.String({
      minLength: 3,
      maxLength: 50,
    })),
    content: t.Optional(t.String({
      minLength: 3,
      maxLength: 50,
    })),
  }, {
    minProperties: 1,
  })
})

If we put all of this together, we will end up with the following posts/index.ts file for our posts routes:

import { Elysia, t } from 'elysia';
import {
  createPost,
  getPost,
  getPosts,
  updatePost,
  deletePost,
} from './handlers';
 
const postsRoutes = new Elysia({ prefix: '/posts' })
  .get('/', () => getPosts())
  .get('/:id', ({ params: { id } }) => getPost(id), {
    params: t.Object({
      id: t.Numeric(),
    }),
  })
  .post('/', ({ body }) => createPost(body), {
    body: t.Object({
      title: t.String({
        minLength: 3,
        maxLength: 50,
      }),
      content: t.String({
        minLength: 3,
        maxLength: 50,
      }),
    }),
  })
  .patch('/:id', ({ params: { id }, body }) => updatePost(id, body), {
    params: t.Object({
      id: t.Numeric(),
    }),
    body: t.Object(
      {
        title: t.Optional(
          t.String({
            minLength: 3,
            maxLength: 50,
          })
        ),
        content: t.Optional(
          t.String({
            minLength: 3,
            maxLength: 50,
          })
        ),
      },
      {
        minProperties: 1,
      }
    ),
  })
  .delete('/', ({ body }) => deletePost(body), {
    body: t.Object({
      id: t.Numeric(),
    }),
  });
 
export default postsRoutes;

All of our routes are now validated and working! Let’s take a quick look at how we can set up our documentation.

Swagger Documentation

With Swagger, not only will we get a page where we can view all of our routes with the parameters they take but we will also be able to test these routes from the same place.

To do this, we have to install the plugin by runnnig:

bun add @elysiajs/swagger

Next, to use it, we simply just add it to our server like this:

import { Elysia } from 'elysia';
import { swagger } from '@elysiajs/swagger';
import postsRoutes from './routes/posts';
 
const app = new Elysia();
 
app
  .use(swagger())
  .group('/api', (app) => app.use(postsRoutes))
  .listen(process.env.PORT || 3049);
 
console.log(
  `🦊 Elysia is running at http://${app.server?.hostname}:${app.server?.port}`
);

We’re all set! Once our server restarts, we will be able to go to localhost:3049/swagger and view all of our routes.

Conclusion

Congratulations! You have now created a REST API using Bun with Elysia and Prisma. If you have any questions or concerns, leave a comment and I will try to provide some help or edits where needed. If you find yourself stuck, check out the video where I build this same exact project while also explaining each step.

Let me know what other things you would like to learn more about. If you enjoyed this article and found it useful, check out my other articles here on Medium and also my YouTube channel where I cover most of these things in video formats.